Luigit
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

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

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