mp-setup-matt-pocock-skills

---
name: mp-setup-matt-pocock-skills
description: "Use when bootstrapping a repo so Matt's engineering skills (to-issues, to-prd, triage, diagnose, tdd, etc.) know the issue tracker, triage labels, and domain doc layout — writes AGENTS.md/CLAUDE.md + docs/agents/."
source: https://github.com/mattpocock/skills/blob/main/skills/engineering/setup-matt-pocock-skills/SKILL.md
generated: 2026-05-12T18:05:16.719Z
category: tool
audience: engineers
---

## When to use

- Before the first use of to-issues, to-prd, triage, diagnose, tdd, improve-codebase-architecture, or zoom-out in a new repo
- When those skills appear to be missing context about the issue tracker, triage labels, or domain docs
- Switching the project from GitHub Issues to GitLab Issues, or to local-markdown issue tracking
- Adding an `## Agent skills` block to an existing CLAUDE.md / AGENTS.md without overwriting other content

## Key concepts

### issue tracker (Section A)

Where issues live for this repo — GitHub, GitLab, local-markdown under .scratch/, or 'other' (Jira/Linear). Skills like to-issues, triage, to-prd, qa need this so they call the right CLI (gh / glab) or follow your custom workflow. The skill proposes a default based on `git remote` and lets you override.

### triage label vocabulary (Section B)

Maps the five canonical triage roles (needs-triage, needs-info, ready-for-agent, ready-for-human, wontfix) to the actual label strings your tracker uses. Without this mapping, the triage skill creates duplicate labels (e.g. `bug:triage` vs `needs-triage`).

### domain docs (Section C)

Tells improve-codebase-architecture / diagnose / tdd where to read CONTEXT.md and ADRs. Single-context (one CONTEXT.md at root) vs multi-context (CONTEXT-MAP.md + per-context CONTEXT.md files, typically a monorepo).

### prompt-driven, not deterministic

Not a script. The skill EXPLORES the repo first (git remote, existing CLAUDE.md/AGENTS.md, CONTEXT.md, docs/adr/), then PRESENTS findings and asks each of the three sections one at a time, with explainers for users who don't know the terms.

### edit-only, never replace

Edits the existing CLAUDE.md if present, else AGENTS.md if present. Never creates AGENTS.md when CLAUDE.md exists (or vice versa). If an `## Agent skills` block already exists, updates it in-place rather than appending a duplicate.

### disable-model-invocation

Frontmatter sets `disable-model-invocation: true` — this skill doesn't self-trigger. The user invokes it explicitly when bootstrapping a repo. Don't expect it to run silently the first time an engineering skill is called.

## API reference

```
The `## Agent skills` block written into CLAUDE.md / AGENTS.md
```

Standard 3-section markdown block linking to docs/agents/*.md files. One-line summary per section so the agent doesn't have to load the doc unless it needs to.

```
## Agent skills

### Issue tracker
[one-line summary]. See `docs/agents/issue-tracker.md`.

### Triage labels
[one-line summary]. See `docs/agents/triage-labels.md`.

### Domain docs
[one-line summary — single-context | multi-context]. See `docs/agents/domain.md`.
```

```
docs/agents/* output files
```

Three per-topic doc files seeded from templates bundled in the skill folder.

```
docs/agents/issue-tracker.md   — github | gitlab | local-markdown | other
docs/agents/triage-labels.md  — canonical-role → your-tracker-label
docs/agents/domain.md         — single-context | multi-context layout + reading rules
```

```
Process (numbered)
```

Five steps. Explore → present findings → confirm draft → write → done. Each section explained one-at-a-time, not dumped together.

```
1. Explore — git remote, CLAUDE.md, AGENTS.md, CONTEXT.md, docs/adr/, .scratch/
2. Present + ask — Section A (tracker), B (triage labels), C (domain docs) ONE AT A TIME
3. Confirm — show drafts of the block + 3 docs; let user edit
4. Write — edit existing CLAUDE.md OR AGENTS.md (never both); update existing `## Agent skills` block in-place
5. Done — tell user which engineering skills will now read these files
```

## Gotchas

- disable-model-invocation: true — this skill won't self-fire. User must invoke it before running the other engineering skills.
- If CLAUDE.md exists, edit it. If only AGENTS.md exists, edit it. Never create the other file. If neither exists, ASK — don't pick.
- An existing `## Agent skills` block must be UPDATED in-place, not duplicated.
- Default issue tracker is inferred from `git remote -v` (GitHub → github, GitLab → gitlab), with local-markdown / 'other' as fallbacks.
- Triage labels default to the canonical names if no override is needed — only customize when the tracker already has different label strings.
- Walk the user through Sections A / B / C one at a time. Don't dump all three explainers at once.
- Each section's explainer assumes the user doesn't know what 'issue tracker', 'triage labels', or 'domain docs' mean in this context. Don't skip the explainer.
- For 'other' issue trackers, write docs/agents/issue-tracker.md from scratch using the user's prose description rather than a bundled template.

---
Generated by SkillMake from https://github.com/mattpocock/skills/blob/main/skills/engineering/setup-matt-pocock-skills/SKILL.md on 2026-05-12T18:05:16.719Z.
Verify against source before relying on details.

File: ~/.claude/skills/mp-setup-matt-pocock-skills/SKILL.md