setup-craft-skills

Setup Craft Skills

The failure mode this fixes

The craft skills are generic by default — and generic is the failure: name-things proposing vocabulary your team doesn't use, delete-this not knowing your webhook registry resolves handlers by string, fit-in guessing at conventions the team settled years ago. Without shared context, every skill re-detects (or mis-guesses) these per run. This skill captures the project's vocabulary, conventions, and untouchables once, in a file all the other skills read.

When to Use This Skill

• First time using the craft-skills plugin in a repository
• The project's domain vocabulary or conventions have changed and CONTEXT.md is stale

Run this once per repo (recommended, not required) before explain-back, name-things, delete-this, seams, loud-errors, boyscout, why-comments, or fit-in. Those skills read the file this creates if it's present — so their output matches your codebase instead of generic defaults. Skip it and the skills still work; they just fall back to detecting conventions on the fly.

What it creates

A CONTEXT.md at the repo root capturing the shared context the craft skills consume:

• Domain glossary — the real nouns of the product, so name-things uses your vocabulary
• Language & stack — so examples and idioms match (TS vs Go vs Python conventions differ)
• Conventions — testing style, error-handling style, file layout, what "done" means
• Untouchables — public APIs, plugin surfaces, and dynamically-referenced code that delete-this must never remove

Instructions

1. Detect, don't interrogate

Inspect the repo first — read package.json / go.mod / pyproject.toml, the test setup, a few representative source files, and any existing README/CONTRIBUTING. Infer the stack, test runner, and layout. Only ask the human about things you genuinely cannot detect.

2. Extract the domain glossary

Pull the recurring domain nouns from the code and docs (the entities, not the framework terms). Present the list and let the human correct or canonicalize names. This is what name-things aligns to. For each term capture:

• What it means — one line, in the team's words.
• Avoid — the near-synonyms that should not be used for it (this becomes a project-specific ban list for name-things: e.g. "Issue tracker — avoid: backlog, backlog backend").
• Relationships — how the core entities relate ("an Order has many LineItems"), so explanations and names stay consistent.
• Flagged ambiguities — any word that was being used for two different things, and the resolution. Recording the resolved split is what stops the codebase from drifting back into two vocabularies.