phrazzld/tailor-skills

/tailor-skills

Pick the skill subset that fits this repo and record it. Every skill costs context in every session; most skills don't fit most repos. This skill is the commit-tracked filter that makes bootstrap honor a local catalog.

Moves

1. Read repo context. Inspect the current project: language, manifest files (package.json, Cargo.toml, pyproject.toml, go.mod, Gemfile, etc.), test framework, CI config, README. Form a one-paragraph mental model of what this repo is and what work happens here.

2. Read the catalog. Resolve $SPELLBOOK: prefer the $SPELLBOOK env var if set; otherwise readlink -f this SKILL.md and walk up two directories (works for symlink installs). Fail loud if neither resolves to a dir containing index.yaml. Read $SPELLBOOK/index.yaml — the generated catalog has name + description + source per skill. That's your input, not a glob of SKILL.md files.

3. Pick 10-20 skills. For each, write one line of justification tied to the repo's actual characteristics. Prefer first-party over externals. Skip speculative picks ("we might need X someday"). Aim for 10-20; fewer is fine for tiny repos. Emit all picks + justifications to stdout so the human can review.

4. Write $PROJECT_ROOT/.spellbook.yaml. Resolve $PROJECT_ROOT via git rev-parse --show-toplevel of the invoking repo. Format:

   # Tailored skill set for this repo. Bootstrap honors this allowlist.
   # Delete this file to restore the global set.
   skills:
     - deliver
     - shape
     - implement
     # ... one per line
   

   With --dry-run, emit the proposed list + justifications to stdout and stop — don't touch the file.

Invariants

• Committed file. .spellbook.yaml goes into git, not .gitignore. Every dev / agent session gets the same scoped set.
• Reversible. Deleting the file and re-running ./bootstrap.sh restores the global set. No migration.
• Agent judges. No scoring formula, no tier metadata, no tag filter. Description + repo context are enough signal.
• Justify each pick. One line per skill in stdout so the human reviewer sees the reasoning.
• Dry-run option. --dry-run proposes without writing.

Gotchas

• Externals show up in index.yaml with source: external. Named the same way in .spellbook.yaml. Prefer them only when the repo genuinely needs that tool (skill-creator for Docker-heavy repos, pptx for deck-producing repos, etc.).
• Dependency-sibling skills. If you pick a composer (/deliver, /flywheel), also name its phase skills (/shape, /implement, /code-review, /ci, /refactor, /qa). There is no declarative dependency graph — enumerate them yourself.
• Global composers almost always earn inclusion. harness, research, ceo-review — if the repo does anything AI-adjacent, include them.
• Index staleness. index.yaml is regenerated by scripts/generate-index.sh. If a chosen skill disappeared after regeneration, bootstrap prints a warning and skips it — the allowlist is intersected with what actually exists.
• Don't over-reduce. The goal is "fit for this repo," not "absolute minimum." Cutting 80% of noise is already the win; chasing smaller at the cost of utility is the failure mode.