Your AI doesn't forget code. Why should it forget process?
skill-spec turns the invisible patterns in your Claude Code sessions into versionable, iterable, composable specs — automatically.
npx skills add ChamberZ40/skill-specThat's it. Works on all supported agents — Claude Code, Cursor, Codex, Gemini CLI, and more.
Claude Code users: enable precision tracking (optional)
bash ~/.claude/skills/skill-spec/scripts/setup-hooks.shAdds background hooks for zero-token, precise candidate detection. Without this, the skill uses in-context detection (works everywhere, costs ~50 tokens).
Alternative: curl installer (clone + hooks in one shot)
curl -sSL https://raw.githubusercontent.com/ChamberZ40/skill-spec/main/install.sh | bashEvery 20+ tool-call session you run is a process waiting to be captured. But you never stop to write it down because:
- You don't notice the pattern until the 3rd time
- Writing a skill from scratch is friction
- Existing skills rot because there's no change management
skill-spec solves all three with zero ongoing effort:
Session ends → hook fires → candidate logged → you review when ready → skill born (or existing skill improved)
Zero tokens consumed during normal work. The entire detection layer is pure shell.
YOUR DAILY WORKFLOW
│
┌────────────────────┼────────────────────┐
│ │ │
│ PostToolUse │ Stop hook │
│ (async, 0 tok) │ (threshold?) │
│ count + log │ │
│ │ < 15 → silent │
│ │ >= 15 → log it │
└────────────────────┼────────────────────┘
│
▼
data/candidates.md
(accumulates silently)
│
▼ when YOU decide
┌───────────────────────────────────┐
│ /skill-spec review │
│ │
│ For each candidate: │
│ 1. Is it repeatable? │
│ 2. Similar skill exists? │
│ YES → proposal │
│ NO → scaffold new skill │
└───────────────────────────────────┘
Two shell hooks run on every session:
- PostToolUse — counts calls + logs which tools you used
- Stop — if count >= threshold, writes a candidate entry
You never see this. It just runs.
When you review candidates:
- Scans existing skills for duplicates
- Match found → creates a proposal on the existing skill's CHANGE.md
- No match → scaffolds a new skill from template
No duplicate skills. Ever.
| Patch | Proposal | |
|---|---|---|
| What | Typo, wording, edge case | New step, reorder, behavior change |
| Process | Edit + commit | CHANGE.md → user review → implement |
| Test | Would a user notice? No → patch | Would a user say "wait what?" → proposal |
Skills declare their downstream connections:
[skill-A] --{output}--> [skill-B] --{output}--> [skill-C]
After a skill completes, Claude checks for downstream suggestions.
| Scenario | Cost |
|---|---|
| Normal session (< 15 calls) | 0 |
| Complex session (>= threshold) | ~30 tokens at session end |
| Skill loaded into context | ~700 tokens (only when triggered) |
| Description in skill list | ~40 tokens (same as any skill) |
The detection layer is invisible. You pay nothing until you actively review.
skill-spec/
├── SKILL.md # Methodology spec (what Claude reads)
├── CHANGE.md # This skill's own change proposals
├── README.md # You're here
├── scripts/
│ ├── count-tool-use.sh # PostToolUse hook
│ ├── check-skill-candidate.sh # Stop hook
│ └── test-hooks.sh # Schema validation
├── data/
│ ├── candidates.md # Auto-populated log
│ └── chains.md # Skill dependency registry
└── templates/
└── SKILL.template.md # New skill scaffold
| Variable | Default | What it does |
|---|---|---|
SKILL_CANDIDATE_THRESHOLD |
15 |
Min tool calls to trigger candidate logging |
Set in ~/.claude/settings.json under "env".
- Claude Code CLI
jq(JSON parsing in hooks)- Bash-compatible shell
Skills are specs. Specs need engineering.
- Observe — detect when a new spec is needed
- Deduplicate — enhance existing specs instead of creating clones
- Govern — light touch for patches, review gates for behavior changes
- Compose — specs that chain into pipelines
The goal is not more skills. It's better skills, continuously improved.
MIT