Skill Spec Engineering#

Overview#

Skills are living specs that need continuous iteration. This methodology covers the full lifecycle: auto-detection → candidate logging → scaffolding → change management → downstream composition.

Phase 1: Detection#

Hook-driven (0 tokens)#

• PostToolUse (async) — increments counter + logs tool names, pure shell
• Stop — writes to data/candidates.md when threshold exceeded, injects one prompt (~30 tokens)

Default threshold: 15. Override: SKILL_CANDIDATE_THRESHOLD=20

Candidate format#

Auto-written to data/candidates.md:

markdown

## 2026-05-03 | 23 calls | 6 tool types
- **Session:** abc123
- **Tools:** Bash,Edit,Write,Agent,WebFetch,Read
- **Status:** pending

Review mode#

When invoked directly, read candidates.md and for each pending entry:

1. Summarize key steps from the session
2. Evaluate three criteria: multi-step, multi-turn, repeatable
3. If YES → proceed to Phase 2 (Scaffold with duplicate check); if NO → mark skipped

Phase 2: Scaffold#

Before creating a new skill, check for duplicates:

1. Scan ~/.claude/skills/*/SKILL.md frontmatter (name + description)
2. If a similar skill exists → create a proposal in that skill's CHANGE.md instead of a new skill
3. If no match → generate from templates/SKILL.template.md

text

~/.claude/skills/[new-skill-name]/
├── SKILL.md        # Generated from template, pre-filled with steps
└── CHANGE.md       # Empty, ready for proposals

Phase 3: Change Management#

Two tiers#

TierCriteriaProcessPatchWon't surprise users (wording, typo, edge case)Direct edit + git commitProposalChanges behavior (add/remove steps, reorder, change logic)CHANGE.md → user review

Rule of thumb: If someone using this skill would say "wait, what?" — it needs a proposal.

Proposal format#

markdown

## #001 - [Title]
- **Status:** proposed | accepted | rejected | implemented
- **Date:** 2026-05-03
- **Trigger:** What scenario triggered this change
- **Proposal:** What to change + why
- **Breaking?:** yes/no

Phase 4: Composition#

Next Steps format (append to each skill)#

markdown

## Next Steps
- **If [specific condition]**: invoke [skill-name] — [one-line reason]
- **If [other condition]**: invoke [another-skill] — [reason]

Chains registry#

data/chains.md records input/output relationships between skills:

text

[publisher-matcher] --{matched list}--> [publisher-review]
[publisher-review] --{confirmed list}--> [email-generator]
[email-generator] --{email content}--> [mail-send-batch]

After a skill completes, check chains.md for downstream → suggest to user.

Quick Reference#

PhaseTriggerToken costOutputDetectionEvery session (auto)0 (shell)data/candidates.mdScaffoldUser confirms candidateOn-demandNew skill directoryChangeIssue found during use0CHANGE.md or direct commitCompositionAfter skill executionOn-demandNext Steps / chains.md

Common Mistakes#

• Treating patches as proposals — fixing a typo doesn't need a proposal, just commit
• Letting candidates pile up — review periodically or they lose value
• Vague chaining — Next Steps must include specific conditions, not "you might want to use X"
• Treating scaffold as final — template output is a starting point, always customize