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
In this repository38 other files it gives its agents.
- claude/CLAUDE.mdCLAUDE.md
- author-skillSkill
- drift-auditSkill
- drift-handoffSkill
- drift-updateSkill
- test-skillSkill
- triageSkill
- fabric-iqSkill
- fabric-catalog-governanceSkill
- fabric-deploySkill
- fabric-rest-apiSkill
- fabric-securitySkill
- fabric-variable-librarySkill
- fabric-databaseSkill
- fabric-dataflowSkill
- fabric-data-pipelineSkill
- fabric-sparkSkill
- fabric-warehouse-monitoringSkill
- fabric-warehouseSkill
- fabric-activatorSkill
- fabric-eventhouseSkill
- fabric-event-schema-setSkill
- fabric-eventstreamSkill
- fabric-realtime-dashboardSkill
- learnSkill
- fabric-semantic-model-auditSkill
- fabric-tmdlSkill
- pbip-project-structureSkill
- pbir-report-workflowSkill
- linkedin-highlightsSkill
- msix-packagingSkill
- code-reviewSkill
- commitSkill
- find-sessionSkill
- landSkill
- prune-branchesSkill
- recreate-repoSkill
- run-briefsSkill
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 110
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 …
- Very specific: line 151
Read loads its .claude/rules/ guidance first, an Edit or Write after the change, sed or heredoc never, silently.
≈ “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
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, -ApplyNever 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 path | Deployed to | Mechanism | Live 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 scope | none; no deploy script touches them | in 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, mcp | directory copy (scripts/link-claude.ps1) | after scripts/link-claude.ps1 |
claude/CLAUDE.md | ~/.claude/CLAUDE.md | plain copy | after scripts/link-claude.ps1 -Force |
claude/settings.json | ~/.claude/settings.json | key-level merge: target-only keys kept, shared keys replaced whole | after scripts/link-claude.ps1 -Force |
claude/mcp/.mcp.global.template.json | ~/.claude.json (top-level mcpServers only) | single-key reconcile, prunes | after scripts/link-claude.ps1 -GlobalMcp |
copilot/instructions/ | <repo>/.github/instructions | file 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./learndeploys, like/commit,/code-reviewand/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 theirsWith 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,sedor 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.mdandskill-overrides.md. - Long detail goes in a skill's own
references/, not itsSKILL.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 ascripts/link-<tool>.ps1that leaves the tool's home real, tool-owned. - Both
CLAUDE.mdfiles hold only what a session needs before any Read, andscripts/lint-claude-md.pycaps them:editing-claude-md.mdsays what moves where.claude/CLAUDE.mddeploys 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.
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.

