using-the-kit
Skill0 starsChanged 4 months agoMITView on GitHub
The kit's dispatcher — consult this before starting any task and before responding. Scan its trigger index and invoke any skill whose row matches what you are about to do. Contains the trigger index and the red-flags table of rationalizations to reject.
- Commits and pushes
In this repository29 other files it gives its agents.
- adopt-existing-projectSkill
- adrSkill
- branch-conflict-checkSkill
- ci-watchSkill
- compound-learningsSkill
- config-auditSkill
- cost-checkSkill
- coverage-ratchetSkill
- doc-syncSkill
- eval-harnessSkill
- flaky-triageSkill
- followup-trackingSkill
- incident-captureSkill
- kit-doctorSkill
- kit-updateSkill
- logging-initSkill
- migration-checkSkill
- new-project-bootstrapSkill
- nightly-auditSkill
- observability-checkSkill
- parallel-workSkill
- perf-budgetSkill
- pr-babysitterSkill
- pre-prSkill
- prompt-regressionSkill
- releaseSkill
- session-handoffSkill
- sync-healthSkill
- writing-kit-skillsSkill
The file
We split this skill into the rules it gives an agent
3 rules. About 0 are common, 3 are distinctive, and 0 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈3
Distinctive · estimate
This author's own choices. Worth a look.
0
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 29
When more than one skill applies, run them in this order:
- Distinctive: line 41
If you catch yourself thinking any of these, stop: it is the signal that a skill applies, not a reason to skip it.
- Distinctive: line 105
No report block — this skill's output is the *other* skill you invoke.
≈ “Common” is an estimate: at least 1 in 5 of the 350,495 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Using the Kit
The kit's gates only protect the repo if they actually fire. Every skill in the kit exists because skipping it once cost a real project real money, a red CI queue, or a silent production failure. This skill is the dispatcher that makes sure the right one runs at the right moment.
When to check
Scan the trigger index below before acting — before writing code, before
running commands, and before responding, including before asking clarifying
questions. If a row's condition matches what you are about to do, invoke
that skill. The check is cheap: a skill whose capability toggle is off in
.claude/kit.yaml reports N/A in seconds. Reporting N/A is fine. Skipping the
check silently is not.
Priority order
When more than one skill applies, run them in this order:
- Isolation first — if you are about to edit files and are not in a
worktree,
parallel-workcomes before everything else. The hook will block you anyway; don't fight it. - Gates before actions —
pre-prbeforegh pr create,migration-checkbefore a migration lands,config-auditbefore committing.claude/changes. - Capture last —
followup-tracking,compound-learnings,doc-sync, andsession-handoffrun when the work is done, not before.
Red flags — rationalizations to reject
If you catch yourself thinking any of these, stop: it is the signal that a skill applies, not a reason to skip it.
| Rationalization | Reality |
| "This is just a small change" | Small changes skip gates; gates exist because small changes broke things. Run pre-pr anyway — most steps will be fast or N/A. |
| "I'll run the checks after I open the PR" | That is exactly the red-CI-on-arrival the kit exists to prevent. The gate runs before gh pr create. |
| "The user is in a hurry" | A blocked queue or a leaked secret costs more time than any gate. Speed is not a reason to skip; it is a reason to run the gate early. |
| "This migration is obviously safe" | migration-check exists because "obviously safe" migrations dropped columns. Two minutes of checking beats an irreversible op on the primary. |
| "I'll remember this deferred decision" | You won't; the session ends. followup-tracking — 90 seconds. |
| "This debugging insight is too specific to write down" | Specific is exactly what compound-learnings wants. The next agent hits the same wall without it. |
| "The capability is probably off for this repo" | Then the skill reports N/A in seconds. Check .claude/kit.yaml; don't guess. |
| "I only changed a prompt string, not code" | Prompt changes are behavior changes. prompt-regression gates them for exactly this reason. |
| "I'm just editing config, not code" | .claude/ config is the attack surface. config-audit before committing changes to it. |
Trigger index
| The moment | Skill / agent to invoke |
| Starting any stream of work that edits files | parallel-work — get a worktree; never work on main |
About to run gh pr create | pre-pr — the full local gate |
| Just opened or pushed to a PR | ci-watch — watch CI to green, fix failures |
| Change adds/edits a DB migration | migration-check |
| Change touches a prompt template or model config | prompt-regression |
| Change touches auth, secrets, user input, or external calls | security-reviewer agent (via pre-pr step 5) |
| Change alters behavior described in docs or the spec | doc-sync |
| Made a non-obvious design choice | adr |
| Finishing a unit of work with deferred decisions or accepted drift | followup-tracking |
| Solved a non-obvious problem (gnarly bug, tricky integration, workaround) | compound-learnings |
| Session ending mid-task, or handing off to another agent | session-handoff |
| A test failed, then passed with no code change | flaky-triage |
Repo logs via print/console.log or ad-hoc logging, or logging.initialized is false | logging-init |
Editing .claude/settings.json, hooks, CLAUDE.md, or MCP config | config-audit before committing |
| Writing or modifying a kit skill | writing-kit-skills |
| After install, profile edit, or a hook silently stopped firing | kit-doctor |
| Asked to check spend or before an expensive LLM run | cost-check |
| Multiple PRs open and someone must keep the queue moving | pr-babysitter / branch-conflict-check |
| New to this repo | codebase-onboarder agent |
Capability-gated skills (migration-check, prompt-regression, perf-budget,
sync-health, cost-check, …) read their toggle from .claude/kit.yaml and
report N/A when disabled — invoking a capability-gated skill costs only a quick
N/A check when its toggle is off.
Model routing
Route by the shape of the step, not by which skill you are in. The profile's
models.* keys in .claude/kit.yaml hold the project's choices; the defaults
below apply when the block is absent or a value is empty.
| Step shape | Role key | Default | Effort |
| Writing or changing code — edits, fixes, migrations, generated artifacts | models.code | claude-opus-5 (models.code_light, claude-sonnet-5, for small diffs) | high |
Planning and validation — adr, session-handoff, spec and design decisions, and the review agents (security-reviewer, test-gap-analyzer, observability-reviewer, spec-drift-checker) | models.plan | claude-fable-5 | high; xhigh for a full-diff security pass |
Mechanical checks — file existence, greps, manifest diffs, kit-doctor's wiring checks | models.mechanical | claude-haiku-4-5, or claude-sonnet-5 at low effort | low |
This applies whenever you choose which agent or model runs a step: a subagent
spawn, a cron entry (nightly-audit, pr-babysitter), or a CI job. When you
do not control it, run the step where you are and say nothing. In skill bodies
write the role key, not a bare model ID; never a date-suffixed ID and never a
retired claude-3-* ID.
Output
No report block — this skill's output is the other skill you invoke. If you checked the index and genuinely nothing applies, proceed; you do not need to announce that.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.