repositories / dotfiles

dotfiles

bugabingas dorkfiles

owned by admin

pi/agent/skills/writing-skills/SKILL.md

Raw

Rendered preview

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.
Write descriptions for routing: concrete capability, trigger phrases, and relevant task context; keep workflow steps in the body.
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.
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.

Sources

---
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.
- Write descriptions for routing: concrete capability, trigger phrases, and relevant task context; keep workflow steps in the body.
- 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.
- 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)