agentleFS
wardawgmalviciouswardawgmalvicious/agent-config/CLAUDE.md

agent-config

CLAUDE.md1 starsChanged 34 days agoMITView on GitHub

The source of the user's coding-agent configuration, written for and validated against Claude Code; other tools may cherry-pick it, untested. README.md has the full picture. Evidence for each rule here or in .claude/rules/ is in docs/evidence/root-claude-md.md, under its heading: read it before changing a rule, not before following one. Root CLAUDE.md is project scope, never deployed, and no mirror of claude/CLAUDE.md, the user-scope payload. It is the only project-scope instruction file that loads at startup, and .claude/rules/ holds what a…

  • Commits and pushes

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
  1. Very specific:

    Every file of a linked skill in a deployed group (ls below) is live machine-wide, committed or not, as is any git switch, stash, reset or …

    line 110
  2. Very specific:

    Read loads its .claude/rules/ guidance first, an Edit or Write after the change, sed or heredoc never, silently.

    line 151

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

agent-config: repo instructions

The source of the user's coding-agent configuration, written for and validated against Claude Code; other tools may cherry-pick it, untested. README.md has the full picture. Evidence for each rule here or in .claude/rules/ is in docs/evidence/root-claude-md.md, under its heading: read it before changing a rule, not before following one.

Root CLAUDE.md is project scope, never deployed, and no mirror of claude/CLAUDE.md, the user-scope payload. It is the only project-scope instruction file that loads at startup, and .claude/rules/ holds what a file here triggers. Add no parallel file for another tool: a copilot-instructions.md and an AGENTS.md each drifted and were deleted. <tool>/ names a payload's format, not its only consumer: claude/ holds Claude Code's formats; copilot/, payload for other repos, exists only because applyTo and paths: differ; skills/ is top-level as no one tool owns its format. This repo's own config sits where each tool looks: .mcp.json, which VS Code reads too, and .claude/settings.json.

.claude/skills/ (ls -d .claude/skills/*/) holds skills that act only on this repo: project scope, deployed nowhere, reached by no deploy script (2026-09-09), since elsewhere they only spend listing budget. Payload upkeep that must also run in client repos goes in skills/meta/ (learn), whose .no-copilot marker keeps it from Copilot and lets it pin model: (copilot-payload.md). .claude/settings.json collapses every platform skill description to name-only here, so none can match by description in this repo: a miss here is no trigger bug. lint-skill-overrides.py checks coverage; a new group goes in its PLATFORM_GROUPS or BEHAVIOURAL_GROUPS.

Commands

pre-commit run --all-files            # every pre-commit-stage check, as CI runs it on push and PR to main
pre-commit run <hook-id> --all-files  # one hook, by its id in .pre-commit-config.yaml
uv run scripts/lint-claude-md.py      # cap every CLAUDE.md, and place nested ones; a path lints a scratch copy
uv run --with pyyaml scripts/skill-status.py --stale  # which skills need a retest, from the stamps
uv run --with pyyaml scripts/skill-status.py --stamp <skill> --phase activation,behaviour  # or real-use
uv run scripts/handoff-status.py      # every repo's open briefs and inbox notes; reads only
for t in tests/scripts/*/test-*.sh; do echo "$t: $(bash "$t" | tail -n 1)"; done  # every negative-case suite
scripts/bootstrap-pre-commit          # a clone: install pre-commit and wire all three hook stages
ls ~/.claude/skills | grep -E '^(fabric|pbir|pbid|pbip|powerbi|msix)-'  # after any deploy: must print nothing
./scripts/link-claude.ps1 -SkillGroups workflow,social,meta -Force  # default; -Force adds claude/CLAUDE.md, settings.json
./scripts/link-claude.ps1 -SkillGroups workflow,social,meta         # same, when neither of those changed
./scripts/link-claude.ps1 -SkillGroups workflow,social,meta -GlobalMcp  # prune ~/.claude.json's MCP servers; after Docker Desktop
./scripts/copy-copilot.ps1 -CopilotDir <repo>/.github -SkillGroups fabric-core,fabric-engineering,power-bi  # committable, for a client repo
./scripts/copy-copilot.ps1 -CopilotDir ~/.copilot -SkillGroups workflow  # Copilot's user scope: never social; meta refused
./skills/workflow/recreate-repo/scripts/repo-settings.ps1  # GitHub settings vs .github/repo-settings.json; -Export, -Apply

Never run link-claude.ps1 without -SkillGroups, bare or with -Force alone: it re-links every platform skill, undoing the prune with no error, just Linked lines and Done. Payload verified …; the later tell is platform skills back in the listing (2026-08-31). Check by name with the grep above, never by count. -SkillGroups prunes each group it omits from user scope, which serves client repos too, so a stale workflow,social deletes meta: restore one on purpose.

How this repo is structured

Repo pathDeployed toMechanismLive when
skills/<group>/~/.claude/skills/<name>one junction per skill (scripts/link-claude.ps1)immediately — same files
.claude/skills/<name>/, .claude/rules/nowhere — read in place at project scopenone; no deploy script touches themin sessions here only: skills immediately, a rule at the next Read, Write or Edit of a file it matches
claude/agents/, claude/hooks/, claude/rules/, claude/mcp/~/.claude/agents, hooks, rules, mcpdirectory copy (scripts/link-claude.ps1)after scripts/link-claude.ps1
claude/CLAUDE.md~/.claude/CLAUDE.mdplain copyafter scripts/link-claude.ps1 -Force
claude/settings.json~/.claude/settings.jsonkey-level merge: target-only keys kept, shared keys replaced wholeafter scripts/link-claude.ps1 -Force
claude/mcp/.mcp.global.template.json~/.claude.json (top-level mcpServers only)single-key reconcile, prunesafter scripts/link-claude.ps1 -GlobalMcp
copilot/instructions/<repo>/.github/instructionsfile copy (scripts/copy-copilot.ps1)in a teammate's clone, once committed there

skills/ is the only junction (2026-09-02): edit-to-live is the skill authoring loop, while a junction elsewhere made every uncommitted state live machine-wide, a half-written hook included. Never turn a copy into a link: a symlinked ~/.claude/settings.json broke upstream three times in 2026. Copilot takes only CLAUDE.md from ~/.claude, where a profile turns on chat.useClaudeMdFile; copy-copilot.ps1 routes the rest (copilot-payload.md, README).

How the pieces trigger

A skill fires on its description and when_to_use (its whole model trigger), on /<name>, or on a paths: glob, which hides it from the listing until a Read, Write or Edit matches it: until then /<name> is Unknown command (2026-09-02). A rule carries only paths: and loads the same way. A hook edit is not live until link-claude.ps1 runs; the old copy runs on, silently. Test identity-guard with tests/hooks/identity-guard/ on the repo copy, then on the deployed one.

Working on this repo

  • /author-skill: a new skill, to a brief and a linted draft.
  • /test-skill: a skill's fixtures, activation contract and tests.
  • /drift-audit → /drift-handoff → /drift-update → /commit, in order.
  • /learn deploys, like /commit, /code-review and /land; it edits the payload here and writes an inbox note anywhere else.

docs/audits/ is a dated ledger (README). Each brief in docs/handoffs/execute/ holds its state in frontmatter, and handoff-status.py prints the queue: run it first. Notes from other repos land in ~/handoff-inbox/agent-config/ (see ~/handoff-inbox/README.md) and wait for /triage, run on the user's word. They are raw: copy nothing out verbatim, cite client evidence by kind, and delete one only once it has landed and the user has said yes.

Branching and concurrent sessions

Every file of a linked skill in a deployed group (ls below) is live machine-wide, committed or not, as is any git switch, stash, reset or rebase that changes one, pre-commit's own stash/restore around a commit included. Commit straight to main; branch only when an intermediate state would break while deployed (settled 2026-09-02), or to work a brief (below). This overrides when claude/CLAUDE.md § "Branch naming" says to branch, not how to name one: edit the two together. A platform skill is deployed only where a -ClaudeDir run linked it (2026-09-24). Integrate by fast-forward, as the repo owner, as /land does: squash collapses /commit's split and rebase-merge rewrites its SHAs.

ls skills/workflow skills/social skills/meta   # the deployed groups
git switch main && git merge --ff-only <branch> && git push origin main
git show HEAD:<path> | grep -n "<target>"      # nothing back: the line is theirs

With another session live in this tree, sequencing outranks branching: stay on main, commit small complete units, stage explicit paths, and never git checkout or git switch, which moves their tree too. Re-read a file they may be editing, a hand-kept list above all, right before editing it, or your write drops their rows silently (2026-09-02); a target not in HEAD is theirs: leave it, and note the fix in your commit message. In one tree, only a commit isolates your work: the index is shared, so an uncommitted change can vanish, staged or not, as git status looks innocent (2026-09-12). /commit § "When another session shares this tree" has the procedure; change it there, not here. Work every brief in a worktree named after it, by EnterWorktree or claude --worktree with its name less .md, or the queue never marks it in flight (2026-09-29). Land it as docs/handoffs/CLAUDE.md says: link-claude.ps1, bar a probe root, and git refuse a worktree (2026-09-29). .claude/settings.json branches a worktree from local HEAD; the default, fresh, drops unpushed commits unannounced. A worktree buys no payload isolation for the deployed groups (2026-09-02), but loads only its own .claude/skills/, .claude/rules/ and CLAUDE.md. Its guard stops Write and git -C into the main checkout, not a Bash write or PowerShell's git -C; a cd out runs, then every command is refused, cd back too, until EnterWorktree (probed 2026-09-24, 2.1.282).

Editing conventions

  • Read a file before changing it, and change it with Edit or Write: the Read loads its .claude/rules/ guidance first, an Edit or Write after the change, sed or heredoc never, silently. For a new file, Read a sibling.
  • Rules here: editing-skills.md, editing-rules.md, copilot-payload.md, editing-claude-md.md, deploy-scripts.md, hooks-and-agents.md, pre-commit-hooks.md, activation-testing.md and skill-overrides.md.
  • Long detail goes in a skill's own references/, not its SKILL.md.
  • Adding a harness: what only that tool reads goes under <tool>/, promoted to the root only when a second tool reads it, and deploys via a scripts/link-<tool>.ps1 that leaves the tool's home real, tool-owned.
  • Both CLAUDE.md files hold only what a session needs before any Read, and scripts/lint-claude-md.py caps them: editing-claude-md.md says what moves where. claude/CLAUDE.md deploys with the default above.

Validating a change

Pre-commit gates what .pre-commit-config.yaml lists; tests/scripts/ has negative-case suites, one per script, that no hook or CI runs; behaviour is checked by hand against tests/. skill-status.py says what an edit needs retested (paths:, description, when_to_use or a behavioural body, never references/), so keep no "untested" list.

This paragraph is the manual test procedure for a rule, subagent or enforcement hook (a skill has /test-skill, plus any tests/skills/<name>/README.md); tests/agents/security-reviewer/README.md works one through. Run in a fresh session. Baseline with claude --safe-mode, typed, never wired into config; it strips this file too, so for this repo's skills see /test-skill step 8. For a false-positive guard it is the wrong control, silently, since the base model passes by never asking: ablate every reference to the guard instead (2026-09-03). Compare with expected_findings.md, which says what must not be caught too. Exercise both the documented invocation and the refusal modes: a subagent that does the right thing but ignores its scope guard has failed. Run git status afterwards: a run that edits its fixtures invalidates every later comparison.

The two tests/skills/*-triggers/expected_activations.md assert every conditional skill. Never restate their total: read it there, or run grep -l '^paths:' skills/*/*/SKILL.md | wc -l. The static check, test-activation.ps1 -Set fabric -StaticOnly then -Set pbip, holds the tables to the globs. Activation keys on Read, Write and Edit, not cat or Grep: a probe pins --allowedTools Read --disallowedTools Bash …, and the transcript is the witness (.claude/rules/activation-testing.md).

Line endings

This repo auto-normalizes text and pins Windows scripts to CRLF and shell scripts to LF in .gitattributes. The Fabric portal-serialization guidance in claude/rules/fabric-git-serialization.md applies to Fabric Git-synced repos, not to this one.

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.