agentleFS
nshopiknshopik/dream-team/CLAUDE.md

dream-team

CLAUDE.md2 starsChanged 19 days agoMITView on GitHub

- Write skill rules as atomic - bullets, one condition and one action each; never as prose paragraphs. - Add a skill or agent rule only for a failure seen in a real run or eval; never for a hypothetical one. - Prefer editing or deleting an existing rule over adding a new one. - Before editing a SKILL.md or agents/*.md description:, apply each of these: - Write it in the third person: "Writes …", not "Write …". - Say…

The file

Show its rules and text

We split this CLAUDE.md into the rules it gives an agent

24 rules. About 0 are common, 8 are distinctive, and 16 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈8

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 16

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    Write skill rules as atomic - bullets, one condition and one action each.

    line 3
  2. Distinctive:

    Add a skill or agent rule only for a failure seen in a real run or eval.

    line 5
  3. Distinctive:

    Prefer editing or deleting an existing rule over adding a new one.

    line 7
  4. Very specific:

    Before editing a SKILL.md or agents/*.md description:, apply each of these:

    line 8
  5. Distinctive:

    Write it in the third person: "Writes …", not "Write …".

    line 9
  6. Distinctive:

    Keep it to 1,024 characters, with no XML tags.

    line 12
  7. Very specific:

    Before adding a skill or agent, or changing a SKILL.md's other sections or files or an agents/*.md prompt, read …

    line 13
  8. Distinctive:

    Keep rules out of README.md.

    line 17
  9. Very specific:

    Keep standing contributor facts the code and paths don't show in MAINTAINING.md, one home each.

    line 18
  10. Very specific:

    Update a MAINTAINING.md fact in the MR that changes it.

    line 20
  11. Very specific:

    Update the skills/ask-team/WORKFLOW.md diagram in the same MR as a change to the flow it draws.

    line 21
  12. Very specific:

    Put a change's detail the code doesn't show in the commit, a spec or a topic doc, never in a SKILL.md or agent prompt.

    line 22
  13. Very specific:

    Run a skills/*/evals/ runner with --plugin-dir ..

    line 28
  14. Very specific:

    Run the hook tests as python3 <file> each, never python3 -m unittest.

    line 34
  15. Very specific:

    Call a plugin workflow by its prefixed name (dream-team:<name>), never by scriptPath.

    line 36
  16. Very specific:

    Before editing CHANGELOG.md, read references/changelog-style.md.

    line 38
  17. Very specific:

    Commit skills/*/evals/ (cases, fixtures, runner) except skills/scope-*/evals/.

    line 43
  18. Very specific:

    Commit top-level evals/ except evals/results/.

    line 45
  19. Very specific:

    Run the top-level evals/ cases with claude plugin eval .

    line 46
  20. Distinctive:

    Before changing who does a step in a skill, read the skill's top-level role rules (e.g.

    line 50
  21. Very specific:

    Check skill triggering with skills/scope-commit/evals/run_trigger.sh (unnamed prompts).

    line 54
  22. Distinctive:

    Keep research findings mined from local session data (workflow journals, run counts) out of the repo and its issues.

    line 59
  23. Distinctive:

    Before filing a follow-up issue, list the milestone's open issues.

    line 66
  24. Very specific:

    Start an interactive session in this repo without --plugin-dir ..

    line 68

≈ “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.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
CLAUDE.md

CLAUDE.md

  • Write skill rules as atomic - bullets, one condition and one action each; never as prose paragraphs.
  • Add a skill or agent rule only for a failure seen in a real run or eval; never for a hypothetical one.
  • Prefer editing or deleting an existing rule over adding a new one.
  • Before editing a SKILL.md or agents/*.md description:, apply each of these:
    • Write it in the third person: "Writes …", not "Write …".
    • Say what it does first, then when to use it.
    • Name the key terms a request or command for it would contain.
    • Keep it to 1,024 characters, with no XML tags.
  • Before adding a skill or agent, or changing a SKILL.md's other sections or files or an agents/*.md prompt, read https://platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices.md and follow it.
  • Fix one failure with one rule; never add a rule for adjacent cases the issue did not hit.
  • Keep rules out of README.md; it points at the skills instead of restating them.
  • Keep standing contributor facts the code and paths don't show in MAINTAINING.md, one home each.
  • Update a MAINTAINING.md fact in the MR that changes it.
  • Update the skills/ask-team/WORKFLOW.md diagram in the same MR as a change to the flow it draws.
  • Put a change's detail the code doesn't show in the commit, a spec or a topic doc, never in a SKILL.md or agent prompt.
  • Name a milestone YY.MM, its target month.
  • Version milestones release in flow mode.
  • From 2026-12-15 to the 26.12 due date, merge only bug issues and changes that do not alter skill or agent behaviour (docs, evals, CI).
  • Run a skills/*/evals/ runner with --plugin-dir .; without the flag it measures the installed plugin cache, not the working tree.
  • In hooks/test_body_cap.py, match an over-cap deny on -word ceiling, not ceiling; the skill text the hook quotes back contains the bare word.
  • Judge a scope-mr change on in-repo runs too (REPO=<checkout> in run_baseline.sh); diff-only runs lack the context real sessions read and hide what the skill does there.
  • Run the hook tests as python3 <file> each, never python3 -m unittest; they are plain scripts and unittest exits 5 with NO TESTS RAN.
  • Call a plugin workflow by its prefixed name (dream-team:<name>), never by scriptPath; skill text does not expand ${CLAUDE_PLUGIN_ROOT}; a plugin agent body does.
  • Before editing CHANGELOG.md, read references/changelog-style.md.
  • Fence a chat-output layout in a skill, so the model reproduces its markdown; show example skill output in docs or evals as rendered markdown, where a fence hides the bold labels judged.
  • Lay out a skill's chat output for a monospace terminal: tight - **Label:** bullets, no blank lines between items; paragraph spacing wastes fixed-height lines.
  • Commit skills/*/evals/ (cases, fixtures, runner) except skills/scope-*/evals/; those and runs/ are ignored.
  • Commit top-level evals/ except evals/results/.
  • Run the top-level evals/ cases with claude plugin eval . --trust-plugin --model opus --threshold 0.6.
  • Give a small or pass-through skill or workflow phase stub-agent tests only; add a paid headless-claude eval runner only for a large skill or a failure seen in a real run.
  • Before changing who does a step in a skill, read the skill's top-level role rules (e.g. build-issue's "You do not write the change" edit list) and update them in the same change.
  • A change to a SKILL.md, its reference/ files or an agents/*.md prompt → check every other line of those files for a contradiction with the change.
  • Check skill triggering with skills/scope-commit/evals/run_trigger.sh (unnamed prompts); the other evals name the skill in the prompt and cannot see a description change. Keep its fixture repo consistent with each prompt, or the agent stops before loading any skill.
  • In a headless claude -p run, pipe the prompt on stdin or put it before --allowed-tools; that flag is variadic and swallows a trailing prompt ("Input must be provided").
  • Keep research findings mined from local session data (workflow journals, run counts) out of the repo and its issues; report them in chat only, even when build-issue's research tier says to post a findings comment.
  • Delegate grading of eval reports against a ledger to a subagent (Agent tool); the main session only reads the scores and the marks file.
  • Cite an outside pull request in commits, PRs, issues and notes in plain words ("unbound pull request 1525"), never #1525; GitHub links #N to this repo.
  • Before filing a follow-up issue, list the milestone's open issues; a matching one gets a comment with the new evidence, not a new issue (#231 duplicated #226).
  • Start an interactive session in this repo without --plugin-dir .; with it, every Write and Edit here prompts even in accept-edits mode. Keep the flag for headless evals.
  • Give a headless pi -p run without piped input < /dev/null; under a Claude Bash call it waits forever on the harness stdin socket, 0% CPU, empty output.

Download now (ZIP)

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
What did you use it for? e.g. Reviewing pull requests in a Rails app

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.