setup-matt-pocock-skills

Files (6)

• SKILL.md
• domain.md
• issue-tracker-github.md
• issue-tracker-gitlab.md
• issue-tracker-local.md
• triage-labels.md

SKILL.md (first lines)

# Setup Matt Pocock's Skills

Scaffold the per-repo configuration that the engineering skills assume:

- **Issue tracker**: where issues live (GitHub by default; local markdown is also supported out of the box)
- **Triage labels**: the strings used for the five canonical triage roles
- **Domain docs**: where `CONTEXT.md` and ADRs live, and the consumer rules for reading them

This is a prompt-driven skill, not a deterministic script. Explore, present what you found, confirm with the user, then write.

## Process

### 0. Preflight (run first, before writing anything)

Run these checks in order. **a** and **b** are capability-scoped: record the result and continue,
because setup itself needs neither package. **c** and **d** are blocking: if either fails, stop,
print its remedy, and write nothing.

**a. `subagent` capability (capability-scoped, D10).**
Check whether the `subagent` tool is available to you in this session; it is registered by the
`pi-subagents` extension. You can confirm the package is installed with `pi list --approve` and
looking for `pi-subagents`.
If it is missing, mark `research`, `wayfinder`, `code-review`, and `implement` unavailable in the
capability report and print:

```
pi install npm:pi-subagents
```

Then continue. Setup does not need this package, so its absence never blocks repository
configuration.

**b. Web capability (capability-scoped, D10).**
Check whether `web_search`, `fetch_content`, `get_search_content`, and `source_check` are all
available to you; they are registered by the `pi-web-access` extension.
If any is missing, mark `research` and `wayfinder` (research tickets only) unavailable and print:

```
pi install npm:pi-web-access
```

Then continue, and say plainly that a user who only wants `grill-with-docs` → `to-spec` →
`to-tickets` → `implement` does not need this package. Do not over-gate.

**c. Skill-name collisions (blocking, D11).**
Pi keeps the first skill it finds for a name and warns; a later copy is silently shadowed. Names
in this package are the upstream names verbatim, so this is the one preflight that can make every
later skill behave like a different skill without saying so. Enumerate the names this package
defines and check each for a second definition.

- **Presence, the Pi-native way.** Do not look for a folder alongside this one. Pi puts the
  discovered skill names in your system prompt (`systemPromptOptions.skills`, rendered as the
  `<available_skills>` block). Read that list to answer "is `triage` available?".
- **Provenance and duplicates.** The authoritative per-command provenance is `pi.getCommands()`,
  whose entries carry `sourceInfo: { path, source, scope, origin, baseDir? }`. It is an extension
  API, not a tool, so read the resolved view from the startup header. Two limits matter: **it
  reports only the winner of a collision** — a shadowed copy does not appear at all — and it only
  sees registered commands. Pair it with this on-disk scan, run with `bash` (Node is always
  present because Pi requires it). It scans the user/project skill directories plus every package
  that `pi list --approve` resolves, which includes path and git installs that a fixed
  `node_modules` glob would miss, and prints every name declared more than once:

  ```bash
  node -e '
  const fs=require("fs"),cp=require("child_process"),path=require("path");
  const home=process.env.HOME||process.env.USERPROFILE||"";
  const roots=[path.join(home,".pi/agent/skills"),path.join(home,".agents/skills"),".pi/skills",".agents/skills"];
  try{for(const l of cp.execSync("pi list --approve",{encoding:"utf8"}).split(/\r?\n/)){const m=/^\s{4}(\S.*)$/.exec(l);if(m)roots.push(path.join(m[1].trim(),"skills"));}}catch{}
  const found=new Map();
  const walk=(d)=>{if(!fs.existsSync(d))return;for(const e of fs.readdirSync(d,{withFileTypes:true})){const p=path.join(d,e.name);if(e.isDirectory())walk(p);else if(e.name==="SKILL.md"){const m=/^name:\s*"?([^"\s]+)"?/m.exec(fs.readFileSync(p,"utf8"));if(m)(found.get(m[1])??found.set(m[1],[]).get(m[1])).push(p);}}};
  roots.forEach(walk);
  let n=0;for(const [name,ps] of [...found.entries()].sort())if(ps.length>1){n++;console.log("collision: "+name+"\n  "+ps.join("\n  "));}
  console.log(n?n+" collision(s)":"no skill-name collisions detected");
  '
  ```

On a collision, report the colliding name and every path found, and ask the user to remove, rename,
or reorder one installation. Never rename or remove anything yourself. A name that appears once on
disk but whose `pi.getCommands()` `sourceInfo.path` points somewhere other than this package is
also a collision: say the name resolved to another source rather than assuming this package's copy
won. Where neither surface can attribute a name, say it could not be attributed.

**d. `enableSkillCommands` (blocking, D3).**
Pi registers skills as `/skill:<name>` commands only while `enableSkillCommands` is not `false`
(the default is `true`). With it off, all 14 user-invoked skills are unreachable and no skill can
explain why. Read both settings files with the `read` tool — project settings override global:

- `~/.pi/agent/settings.json` (global)
- `.pi/settings.json` (project)

If the effective value is `false`, stop and print the remedy:

```
Re-enable skill commands: run /settings and turn "Enable skill commands" back on, or set
"enableSkillCommands": true in .pi/settings.json (project) or ~/.pi/agent/settings.json (global).
```

Reaching this skill as `/skill:setup-matt-pocock-skills` already proves skill commands are on for
this session; this check protects the other user-invoked skills. Project settings load only when
the project is trusted, so treat an untrusted `.pi/settings.json` as unread and say so.

### 1. Explore

Look at the current repo to understand its starting state. Read whatever exists; don't assume:

- `git remote -v` and `.git/config`: is this a GitHub repo? A GitLab repo? Which one?
- `AGENTS.md` at the repo root (and `AGENTS.override.md`): does either exist? Is there already an `## Agent skills` section? Pi's other context-file name is irrelevant here — this package standardizes on `AGENTS.md`.
- `CONTEXT.md` and `CONTEXT-MAP.md` at the repo root
- `docs/adr/` and any `src/*/docs/adr/` directories
- `docs/agents/`: does this skill's prior output already exist?
- `.scratch/`: a sign that a local-markdown issue tracker convention is already in use
- **Is the `triage` skill available?** Read Pi's own skill catalog: the `<available_skills>` block in your system prompt (`systemPromptOptions.skills`). If `triage` is listed, Section B runs; if it is not, skip Section B entirely. Do not probe the filesystem for a `triage` folder.
- Monorepo signals: a `pnpm-workspace.yaml`, a `workspaces` field in `package.json`, or a populated `packages/*` with its own `src/`. These are present only in a genuinely large multi-package repo; their absence means single-context, which is almost every repo.

### 2. Present findings and ask

Summarise what's present and what's missing, including the preflight capability report from step 0.
Then take the sections in order. One section, one answer, then the next.

From netname/pi-adapted-mp-skills, MIT.

More from netname/pi-adapted-mp-skills