proguha/pstack-pi/skill-development

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.