writing-skills

Writing skills

A greymatter skill is a reference document for a recurring technique or process phase. Skills are not narratives ("how I solved this once") — they're reusable contracts.

Anatomy

greymatter/
  skills/<skill-name>/SKILL.md      # claude prime: interactive guidance
  prompts/<skill-name>/prompt.md    # subagent: self-contained assignment
                                    # (only if the phase dispatches a subagent)

A pipeline phase skill has both. A cross-cutting skill (TDD, debugging) has SKILL.md only. A subagent-only artifact (a reviewer template) lives in prompts/ only.

SKILL.md frontmatter

---
name: <slug>                    # matches folder name
description: <one line>          # what this skill does
phase: <verb> | cross-cutting | meta
reads: <input artifacts>         # optional, pipeline phases only
emits: <output artifacts>        # optional, pipeline phases only
next: <skill name>               # optional, the natural handoff
triggers:
  phrases:                       # 5–15 direct invocation phrases
    - "..."
  collocation:                   # verb+noun fallback for novel phrasings
    - verbs: [...]
      nouns: [...]
      proximity: 6
  negate:                        # substring suppressions
    - "..."
---

The triggers: block is the source of truth — scripts/sync-triggers.js reads every skill's frontmatter and rebuilds ~/.claude/greymatter/prompt-triggers.json. Never hand-edit the trigger config. Edit the skill, run sync.

SKILL.md body conventions

• Lead with "When you're done." A one-paragraph definition of the terminal state. The skill ends; what does success look like?
• Numbered process steps. 4–8 steps for most skills. Each step is a real action.
• Anti-patterns section. What NOT to do, with the reason. The anti-patterns section is where most of the value lives — failure modes are how the skill earns its keep.
• Tight. 60–150 lines for a phase skill. If you're over 200, you're explaining instead of referencing. Cut.
• No "ALWAYS NEVER FOREVER." Direct, scoped guidance. Imperative voice is fine; cult voice is not.
• Self-contained. Don't reference other skills' bodies. If a phase truly depends on another skill, name it in next: and let the user invoke it.

prompt.md (subagent prompts)

Subagent prompts are different from SKILL.md. The subagent has zero session context.

• Self-contained. Every relevant fact, every path, every constraint is in the prompt. No "as discussed earlier."
• Structured output expected. Tell the subagent what shape the response should take (findings list with severity, structured JSON, ranked recommendations). Free-form prose makes triage harder.
• Boundaries explicit. What is the subagent's job? What is NOT its job? "Review this; don't write code" prevents drift.
• Greymatter-aware. Subagents can use the same MCP tools (get_node_bundle, query_blast_radius, grep_project); say which to use.

TDD for skills

When a new skill addresses a real recurring failure:

1. Document the failure scenario (RED): "agents do X when Y; the right move is Z."
2. Write the skill (GREEN): minimal text that fixes the failure.
3. Test by running the scenario again with the skill loaded (REFACTOR): does the agent comply? If not, find the loophole and tighten.

If you can't name the failure scenario the skill prevents, the skill probably shouldn't exist yet.

When NOT to write a skill

• One-off solution. Document in the relevant doc, not as a skill.
• Standard practice well-documented elsewhere (point at the canonical source).
• Project-specific convention. That's CLAUDE.md material.
• Mechanical constraint enforceable by a script. Save documentation for judgment calls.

Anti-patterns

• Skill as transcript. "Last week I solved X by…" — that's a postmortem, not a skill. The skill is the reusable extract.
• Skill as cult. ALWAYS, NEVER, FOREVER, YOU MUST language reads as authority but degrades fast. Direct present-tense imperatives ("Read the spec," "Write the failing test") are the right register.
• Skipping triggers:. Without triggers, the prompt-submit hook can't surface the skill. The skill exists but never fires.
• Skill that references other skills' content. Inline what's load-bearing; link in next: for handoff. Each skill has to stand alone.