name: writing-skills
description: "Use when creating, reviewing, refactoring, or packaging agent skills: SKILL.md files, descriptions, references, scripts, assets, discovery, activation, or validation."
Writing skills
Create one useful, portable skill without duplicating project truth.
Shape
Keep SKILL.md short, timeless, deduplicated, and bullet-led.
description is a trigger, not a summary.
Keep it short: only wording needed to activate at intended times.
No capability inventory, workflow, benefits, or redundant triggers.
Match prescription to risk: flexible guidance for judgement, exact steps for fragile operations.
Keep durable workflow here; move edge cases, API facts, and examples to references/authoring.md.
Link sources of truth; do not copy mutable documentation.
Keep each skill's mechanics in one canonical owner; do not copy another skill's workflow.
By default, do not name or link other skills; it cascades skill loads.
Express relations in plain language ("when opening a PR, …") and let descriptions trigger.
Name a skill only when the relation is essential and plain language cannot carry it; never use machine-specific or repo-local paths.
Put deterministic, repeated work in dependency-free Node .mjs scripts.
Do not automate semantic judgement, voice, timelessness, or deduplication without observed repeated failure.
Before
Define outcome, triggers, authority, non-goals, and observable success.
Read the selected SKILL.md completely; continue truncated reads with offset.
Load references only when relevant; link them directly from SKILL.md.
Inspect existing skills, prompts, extensions, and policy for reuse or conflict.
Choose the smallest asset: prompt → short expansion; skill → conditional guidance; extension → runtime behavior.
Verify discovery and /skill:name invocation against installed Pi docs; do not infer Pi behavior from Claude Code docs.
Build
For behavior changes:
RED: run the harmless scenario without the skill; record the actual gap.
GREEN: write the minimum skill that closes that gap.
REFACTOR: rerun the same scenario; test a nearby non-trigger and relevant permission/error boundary; remove duplication.
For source-link or documentation-only refreshes, review accuracy and structure without requiring a new behavioral scenario.
Resolve every local path relative to the skill directory.
Verify
Run node scripts/check.mjs <skill-dir>; packaging rules and checker limits live in references/checker.md.
Run existing tests in each scripted skill directory before relying on helpers.
Inspect loading and observable behavior when changed, not agent claims.
Keep scenario, settings, outputs, and verdict in OS temp.
Report scope, executed checks, blocked checks, and residual gaps; include RED/GREEN evidence when behavior changed.
---
name: writing-skills
description: "Use when creating, reviewing, refactoring, or packaging agent skills: SKILL.md files, descriptions, references, scripts, assets, discovery, activation, or validation."
---
# Writing skills
Create one useful, portable skill without duplicating project truth.
## Shape
- Keep `SKILL.md` short, timeless, deduplicated, and bullet-led.
- `description` is a trigger, not a summary.
Keep it short: only wording needed to activate at intended times.
No capability inventory, workflow, benefits, or redundant triggers.
- Match prescription to risk: flexible guidance for judgement, exact steps for fragile operations.
- Keep durable workflow here; move edge cases, API facts, and examples to [`references/authoring.md`](references/authoring.md).
- Link sources of truth; do not copy mutable documentation.
- Keep each skill's mechanics in one canonical owner; do not copy another skill's workflow.
- By default, do not name or link other skills; it cascades skill loads.
Express relations in plain language ("when opening a PR, …") and let descriptions trigger.
Name a skill only when the relation is essential and plain language cannot carry it; never use machine-specific or repo-local paths.
- Put deterministic, repeated work in dependency-free Node `.mjs` scripts.
- Do not automate semantic judgement, voice, timelessness, or deduplication without observed repeated failure.
## Before
- Define outcome, triggers, authority, non-goals, and observable success.
- Read the selected `SKILL.md` completely; continue truncated reads with `offset`.
- Load references only when relevant; link them directly from `SKILL.md`.
- Inspect existing skills, prompts, extensions, and policy for reuse or conflict.
- Choose the smallest asset: prompt → short expansion; skill → conditional guidance; extension → runtime behavior.
- Verify discovery and `/skill:name` invocation against installed Pi docs; do not infer Pi behavior from Claude Code docs.
## Build
For behavior changes:
- **RED:** run the harmless scenario without the skill; record the actual gap.
- **GREEN:** write the minimum skill that closes that gap.
- **REFACTOR:** rerun the same scenario; test a nearby non-trigger and relevant permission/error boundary; remove duplication.
For source-link or documentation-only refreshes, review accuracy and structure without requiring a new behavioral scenario.
Resolve every local path relative to the skill directory.
## Verify
- Run `node scripts/check.mjs <skill-dir>`; packaging rules and checker limits live in [`references/checker.md`](references/checker.md).
- Run existing tests in each scripted skill directory before relying on helpers.
- Inspect loading and observable behavior when changed, not agent claims.
- Keep scenario, settings, outputs, and verdict in OS temp.
- Report scope, executed checks, blocked checks, and residual gaps; include RED/GREEN evidence when behavior changed.
## Sources
- [Authoring edge cases](references/authoring.md)
- [Checker scope](references/checker.md)
- [Sources of truth](references/sources.md)