claude-code-tradecraft
CLAUDE.md1 starsChanged 6 days agoMITView on GitHub
Prompt files for Claude Code, packaged as the tradecraft plugin (its own marketplace is claude-code-tradecraft). There is nothing to build, lint, or unit test. skills/<name>/SKILL.md are the slash commands, agents/*.md are subagent definitions, docs/ holds the sourced rules they are written against plus the flowcharts the README embeds, and prompts/ holds standalone prompts to paste into a session. The plugin does not load prompts/, and its files are exempt from the sourcing rule; prompts/README.md indexes them. Three layers, each checked…
- Commits and pushes
In this repository3 other files it gives its agents.
- leadSkill
- pr-reviewSkill
- pr-review-watchSkill
The file
We split this CLAUDE.md into the rules it gives an agent
2 rules. About 0 are common, 0 are distinctive, and 2 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈0
Distinctive · estimate
This author's own choices. Worth a look.
2
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 16
Commit scopes are the skill names: feat(pr-review), fix(pr-review-watch), feat(lead), docs(readme).
- Very specific: line 34
Every user-visible change adds a line under ## [Unreleased] in CHANGELOG.md.
≈ “Common” is an estimate: at least 1 in 5 of the 27,641 CLAUDE.md 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
CLAUDE.md
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
What this repo is
Prompt files for Claude Code, packaged as the tradecraft plugin (its own marketplace is claude-code-tradecraft). There is nothing to build, lint, or unit test. skills/<name>/SKILL.md are the slash commands, agents/*.md are subagent definitions, docs/ holds the sourced rules they are written against plus the flowcharts the README embeds, and prompts/ holds standalone prompts to paste into a session. The plugin does not load prompts/, and its files are exempt from the sourcing rule; prompts/README.md indexes them.
Working with the files
- Install:
/plugin install tradecraft --marketplace kchojn/claude-code-tradecraft. The installed plugin is a copy, so an edit here does nothing in an installed session./tradecraft:pr-review-watchruns the installed plugin's/tradecraft:pr-review, not the one in the working tree. - Development loop:
claude --plugin-dir /path/to/cloneloads the working tree as the plugin. - The only test is a real run:
/tradecraft:lead <task>,/tradecraft:pr-review <pr>(dry-run by default: prints findings and dropped candidates, touches nothing on GitHub),/tradecraft:pr-review-watch. Headless:claude -p "/tradecraft:pr-review <url>". - Watcher state lives in
~/.cache/pr-review-watch/(thelockdirectory and one result file per PR head); clone roots in~/.config/pr-review-watch/roots. - Frontmatter is the contract. Agents use
name,description,model,effort,tools,disallowedTools,omitClaudeMd,maxTurns. Skills usedescription,argument-hint,disable-model-invocation. Unknown fields are ignored silently, so a typo turns a rule off with no warning. An agentdescriptionis a routing rule: open with "Use for" or "Use when". - Commit scopes are the skill names:
feat(pr-review),fix(pr-review-watch),feat(lead),docs(readme). PRs land by squash merge, so the PR title is the commit. - ASCII only, no em dashes anywhere, including inside the prompts and the flowcharts.
How the pieces fit
Three layers, each checked against the one below it.
agents/fixes the roster and the model routing.scout(haiku) andqa-runner(haiku) never write or review code;implementer(sonnet) writes from a spec;reviewer(sonnet, high) finds or verifies defects read-only;deep-reasoner(opus) designs and debugs;oracle(fable) is a one-shot read-only decision call: a major design, a questiondeep-reasonercould not settle, or an escalation. Skills name agents and never passmodel, exceptmodel: opusto retry a failedimplementerphase; the frontmatter decides.scout,reviewer, andqa-runnersetomitClaudeMd: true, so a brief must restate any rule they have to follow.skills/are orchestrators that share one vocabulary. A brief is Goal, Inputs, Constraints, Permissions, Done when, Expected output. A report opens withDONE | DONE_WITH_CONCERNS | NEEDS_CONTEXT | BLOCKED. A failed phase retries on the same or a stronger model, goes tooracleonce after two failures or whendeep-reasonerreaches no conclusion, then to Codex, called directly through the plugin's companion script, when a verdict stays disputed. Parallel briefs to one agent type open with identical text so they share a prompt cache./tradecraft:pr-reviewadds a finder and verifier split (recall-biased finder, precision-biased verifier that must citefile:line), verdictsCONFIRMED | PLAUSIBLE | REFUTED, and keeps confidence (does the defect exist) apart from severity (does it block)./tradecraft:pr-review-watchis a scheduler only. It runs oneclaude -p "/tradecraft:pr-review <url> --publish"process per PR, because a subagent cannot spawn subagents, and it runs three at a time.docs/holds the rules with their sources.orchestration-best-practices.mdgoverns/tradecraft:leadand the agents;pr-review-research.mdgoverns/tradecraft:pr-reviewand/tradecraft:pr-review-watch;lead-review.mdmaps each practice to the line inskills/lead/SKILL.mdthat implements it.
Changing a skill
- Every rule traces to a cited source or a recorded run, or is listed as unmeasured in
docs/pr-review-research.mdsection 17. Add the rule to the matchingdocs/file with its source first, then change the command. A lesson from a real run goes in as a numbered section;pr-review-research.mdsections 7 to 10, 15, and 16 show the shape. - A change to
/tradecraft:leadmeans updating the table indocs/lead-review.md. - A change to a flow means editing
docs/<name>-flow.html(hand-written HTML with an inline SVG) and re-exportingdocs/<name>-flow.svg. - The Codex escalation sentence is duplicated in the lead and pr-review skills. Change it in both.
- The README flow paragraphs restate rules from the skills. A rule change updates the README.
- Every user-visible change adds a line under
## [Unreleased]inCHANGELOG.md. /tradecraft:pr-reviewsections refer to each other by number. Keep the numbers stable or fix every reference./tradecraft:pr-review-watchmust stay model-invocable:/loopfires a skill only withoutdisable-model-invocation.
Releasing
A merge to main that leaves entries under ## [Unreleased] gets a release in the same session, without asking. A merge that adds no changelog entry gets none.
- Pick the version from the entries.
### Addedor### Changedbumps minor;### Fixedalone bumps patch. Before 1.0 a breaking change (a renamed command, agent or state path) also bumps minor and its line says so. - On a
chore/release-vX.Y.Zbranch: move the entries to## [X.Y.Z] - YYYY-MM-DD, add its compare link at the foot ofCHANGELOG.mdand repoint the[Unreleased]link, and setversionin.claude-plugin/plugin.json. Commit aschore(release): vX.Y.Z, open a PR, squash-merge it. - Tag the squash commit
vX.Y.Z(annotated) and push the tag. Create the GitHub release from the changelog section:gh release create vX.Y.Z --title vX.Y.Z --notes-file <section>.
The marketplace entry has no version, so /plugin update follows main; the tag and release serve readers and the changelog links.
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.

