writing-skills

Files (7)

• SKILL.md
• anthropic-best-practices.md
• CLAUDE_MD_TESTING.md · examples/
• graphviz-conventions.dot
• persuasion-principles.md
• render-graphs.js
• testing-skills-with-subagents.md

SKILL.md (first lines)

# Writing Skills

Build a skill only when reusable guidance adds value beyond project instructions,
automation, or a one-off note. A skill can be a minimal meaningful artifact:
frontmatter plus a focused `SKILL.md`, with extra files only when they improve use.

## Anatomy and discovery

Use a directory named for the skill. Its `SKILL.md` frontmatter needs a stable
`name` and a concise `description` that names concrete triggers, symptoms, and
boundaries. The body explains the decision, semantic examples, and the smallest
safe workflow. Prefer progressive disclosure: keep first-use guidance short and
move heavy reference, scripts, or assets into linked files.

Map instructions to the active platform's tools and deployment surface rather
than assuming a namespace or runtime. Validate markdown syntax and links, then
resolve how the target harness discovers and loads the skill.

## Evaluation and publication

Choose validation proportional to novelty and risk. A reference skill may need
static checks and semantic examples; a behavior/process skill may need a real
scenario and a counterfactual or no-guidance control when it could change the
conclusion. Preserve useful drafts and iterate from evidence rather than deleting
work as ritual.

Commit, publish, push, PR, and release behavior follow current repository policy
and explicit authority. Do not use announcements, todo compliance, authority,
scarcity, or commitment manipulation as substitutes for a clear skill.

From BB-84C/superpowers-lite, MIT.

More from BB-84C/superpowers-lite