skill-development

Files (3)

• SKILL.md
• check-skill.mjs · scripts/
• trigger-test.mjs · scripts/

SKILL.md (first lines)

# Skill development

A skill is a directory holding `SKILL.md` plus optional `scripts/`, `references/`, and `assets/`. Pi lists each skill's name, description, and path in the system prompt, and the model reads `SKILL.md` when a task matches the description. The description is the only part always in context; everything else loads on demand.

For the writing itself (pointers, information hierarchy, completion criteria, leading words, pruning), read the **writing-for-agents** skill when it is installed, and write every line through **unslop**. This skill covers Pi's mechanics and the loops.

## Pi mechanics

- **Where it goes.** Project: `.agents/skills/<name>/` (Pi searches from the working directory up to the repository root) or `.pi/skills/<name>/`. Personal: `~/.agents/skills/<name>/` or `~/.pi/agent/skills/<name>/`. Shared: a Pi package's `skills` directory, such as pstack-pi's `skills/`. Keep a pstack skill edit in pstack-pi's `port.json` or `overlay/`, since `scripts/sync-pstack.mjs` regenerates the skills tree.
- **Name collisions.** Pi keeps the first skill it finds under a name and warns about the rest. `~/.agents/skills/` is read before package skills, so a copy there shadows a package's skill of the same name.
- **Frontmatter.** `name` is lowercase letters, digits, and single hyphens, at most 64 characters, and should equal the directory name. `description` is required, at most 1024 characters, one YAML scalar; quote it or use `description: >-` when it holds a colon or wraps. `disable-model-invocation: true` hides the skill from the model so only `/skill:<name>` runs it. Pi ignores other runtimes' keys, such as Claude Code's `user-invocable`.
- **Paths.** Write links and script paths relative to the skill directory; Pi tells the model where the skill lives. Put deterministic work in `scripts/` rather than prose the model reinterprets each run.
- **Reload.** After an edit, run `/reload` or start a new session. Startup diagnostics report malformed skills and collisions.

## Draft, test, iterate

1. **Collect concrete cases.** Write three to five real requests the skill must handle and two or three near misses it must leave alone. Each case names what a correct run produces.
2. **Plan the contents.** For each case, decide what the model needs every run (steps in `SKILL.md`), what only some runs need (a `references/` file behind a pointer), and what should be a script.
3. **Draft.** Write the description first: what the skill does and the distinct situations that should trigger it, front-loaded with the words users actually say. Then write the body as steps with completion criteria, plus the reference each step consults.
4. **Check.** Run `node scripts/check-skill.mjs <skill-dir>` from this skill's directory. It checks the frontmatter rules above, relative links, and length. Fix every FAIL.
5. **Test triggering.** Put the cases in a file, one per line, `+ <prompt>` for must-load and `- <prompt>` for must-skip, and run `node scripts/trigger-test.mjs <skill-dir> <cases-file>`. Each case is one real model request with only this skill, only the `read` tool, and no extensions, so pass `--model` to test the model the skill will run under. Tell the user before running it, since it spends tokens.
6. **Test behavior.** Run each must-load case in a fresh session (`pi -p "<prompt>"` or a scratch interactive session) and compare the result against the case's expected output. Watch where the model skipped a step, reached for the wrong reference, or ended early.
7. **Iterate.** Fix the cause each failure shows: sharpen a vague completion criterion, move a buried step up, disclose reference that crowds the steps, or add a script for work the model keeps doing by hand. Rerun steps 4 to 6 until every case passes.

## Description optimization

Use this when a skill exists but did not trigger when it should have (`tune description: <skill path>`), or triggered when it should not have.

1. Add the missed or wrong request to the cases file as `+` or `-`, plus one or two paraphrases of it.
2. Run `trigger-test.mjs` and confirm the new cases fail. A case that already passes is not the bug.
3. Edit only the description. Add the missing trigger situation in the user's words, merge synonyms that name one situation, and cut identity the body already carries. Keep it short, since it costs context in every session.
4. Rerun the full cases file. Every earlier case must still pass. Repeat from step 3 until all pass.

From proguha/pstack-pi, MIT.

More from proguha/pstack-pi