---
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

- One clear trigger → one outcome.
- Keep `SKILL.md` short, timeless, deduplicated, and bullet-led.
- Write in my voice: terse, direct, concrete; no filler or marketing.
- 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.
- 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, trigger, authority, non-goals, and observable success.
- Inspect existing skills, prompts, extensions, and policy for reuse or conflict.
- Choose the smallest asset: prompt → short expansion; skill → conditional
  guidance; extension → runtime behavior.
- Check automatic vs manual invocation in current Pi docs.
- Use installed docs and official sources as authority; record only durable
  conclusions.

## Build

- **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.
- Resolve every local path relative to the skill directory.
- Scripted skills include `package.json`, direct `node --test`, and isolated
  `.test.mjs` fixtures. Test helpers before relying on them.

## Verify

- Run `node scripts/check.mjs <skill-dir>`.
- Run `npm test` in each scripted skill directory.
- Inspect loading and observable behavior, not agent claims.
- Keep scenario, settings, outputs, and verdict in temporary evidence.
- Report scope, RED/GREEN evidence, blocked checks, and residual gaps.

## Sources

- [Authoring edge cases](references/authoring.md)
- [Checker scope](references/checker.md)
- [Sources of truth](references/sources.md)