claude-skills
CLAUDE.md0 starsChanged 40 days agoMITView on GitHub
Emilio's workbench for his user-level Claude Code config: improving existing agents and skills, drafting new ones, and keeping a history of every change and why it was made. It is the source of truth. ~/.claude/ holds deployed copies (not symlinks) and is changed only through scripts/sync.sh. Everything here is Markdown except the scripts in scripts/; there is no build. scripts/lint.sh checks the conventions and contracts below that can be checked mechanically; behavior is smoke-tested by hand with tests.md. Don't confuse…
In this repository7 other files it gives its agents.
- main-agent/CLAUDE.mdCLAUDE.md
- followupSkill
- implementSkill
- impl-planSkill
- milestoneSkill
- sketchSkill
- walkthroughSkill
The file
We split this CLAUDE.md into the rules it gives an agent
4 rules. About 0 are common, 0 are distinctive, and 4 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.
4
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 15
Don't confuse main-agent/CLAUDE.md (the global instructions being authored) with this file (guidance for working on the repo).
- Very specific: line 21
Log it: Add an entry to CHANGELOG.md under today's date (newest first): - <agent/skill/global> — what changed and why.
- Very specific: line 31
Every file it overwrites is first backed up to .sync-backup/<timestamp>/{live,repo}/ (gitignored), and it never deletes anything.
- Very specific: line 67
A skill's directory name: must match its frontmatter name, which is the /command users type.
≈ “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
Emilio's workbench for his user-level Claude Code config: improving existing agents and skills, drafting new ones, and keeping a history of every change and why it was made. It is the source of truth. ~/.claude/ holds deployed copies (not symlinks) and is changed only through scripts/sync.sh. Everything here is Markdown except the scripts in scripts/; there is no build. scripts/lint.sh checks the conventions and contracts below that can be checked mechanically; behavior is smoke-tested by hand with tests.md.
| Repo path | Deployed to | Role |
main-agent/CLAUDE.md | ~/.claude/CLAUDE.md | Global instructions loaded into every session |
agents/<name>.md | ~/.claude/agents/ | Subagent definitions |
skills/<name>/ | ~/.claude/skills/<name>/ | Skills (SKILL.md + any supporting files) |
Don't confuse main-agent/CLAUDE.md (the global instructions being authored) with this file (guidance for working on the repo).
Workflow
- Pull first. Tools like
/agents,claude-md-improver, andrevise-claude-mdedit~/.claudedirectly. Runscripts/sync.shbefore starting; if it reportslive-newerorlive-onlyitems,scripts/sync.sh pull(with--globalif the global CLAUDE.md is among them) and log them in the changelog as outside edits. - Edit here, keeping the cross-file contracts below consistent. If a skill's expected behavior changes, update its checks in
tests.mdin the same commit. Runscripts/lint.shbefore committing. - Log it. Add an entry to
CHANGELOG.mdunder today's date (newest first):- **<agent/skill/global>** — what changed and why. The why is the point. Commit the changelog entry together with the change, one agent or skill per commit where practical. - Deploy:
scripts/sync.sh apply— add--globalwhenmain-agent/CLAUDE.mdchanged. Changes load in new sessions only.applynever deletes: a file removed from the repo must be deleted from~/.claudeby hand, or step 1 will report itlive-onlyand pull it back. - Smoke-test skill and agent changes with
tests.md— its coverage table says which tests to rerun; each runs in a new session in a scratch project, started withscripts/smoke.sh <n>. Record the run in its log (scripts/check-test.shprints the row); a failure means a fix commit and a rerun. Tests that run against private repos live in an untrackedtests.local.md.
scripts/sync.sh (Git Bash) modes: status (default) · diff · apply [--force] [--global] · pull [--force] [--global].
applyandpullleavemain-agent/CLAUDE.mdalone unless--globalis passed, so a clone on another machine can't swap global instructions in either direction.statusmarks that row[--global].applyrefuses to overwrite live files that are newer than the repo copy.pullskips repo files that are newer than live or that have uncommitted changes.--forceoverrides either check.- Every file it overwrites is first backed up to
.sync-backup/<timestamp>/{live,repo}/(gitignored), and it never deletes anything.
The newer/older check compares file timestamps, so it can't tell when both sides changed. If apply overwrites a live edit that way, recover it from .sync-backup/. The script ignores ~/.claude/skills/synced/ (managed by claude.ai) and .trash/. It targets $CLAUDE_CONFIG_DIR if that is set, so point that at a scratch copy to test it.
scripts/lint.sh enforces: skill and agent names match their paths, descriptions of at most 500 characters, every agent has a color, the reviewer and writing-agent rules below, every ${CLAUDE_SKILL_DIR}/… path exists, the reviewer roster, and a coverage row in tests.md per skill. It also fails on any tracked file matching a pattern in .lint-deny (gitignored, one regex per line) — that is what keeps private project names out; without the file that check is skipped.
scripts/archive-transcripts.ps1 is machine setup too: it mirrors ~/.claude/projects (every session transcript, with its subagents) into an archive folder without ever deleting, so transcripts outlive Claude Code's retention sweep (cleanupPeriodDays, 90 days here). -Register installs it as a daily scheduled task; sync.sh never deploys it.
scripts/defender-dev-exclusions.ps1 is machine setup, not config: run it yourself in an elevated pwsh (-WhatIf first, -Remove undoes) to exclude dev folders from Defender's real-time scan. sync.sh never deploys it.
To trial a draft agent or skill without deploying it globally, copy it into a test project's .claude/agents/ or .claude/skills/; project-local definitions shadow global ones.
.gitattributes pins LF line endings. System git has autocrlf=true, and CRLF conversion would make every file differ from the deployed copy.
Cross-file contracts
Files reference each other by name. When you rename or change one, update the others:
- Reviewer roster. Three places name
csharp-reviewer/react-reviewer/vulkan-reviewer/python-reviewer: the global CLAUDE.md "Agents" section, thereviewer.mddescription, and the React rule in the global "Project CLAUDE.md Authoring" section.react-reviewer.md's description points back at the global CLAUDE.md. A new stack-specific reviewer means updating all of these.skills/implementdeliberately names no stack reviewer — it defers to the global "Agents" section and falls back to the genericrevieweronly when there is none, so it needs no update. Follow-up ledger. Shared by the Documentation Workflow rule (
skills/impl-plan/reference/claude-md-section.md— the global CLAUDE.md only points at it, to keep that text out of every session),agents/doc-sync.md, andskills/followup/SKILL.md:- one file per entry,
docs/fu/FU-NNN.md, with flat front matterid / title / status / kind / areas / files / revisit / originand a body of What / Why accepted / Impacts bullets plus dated Update bullets - sequential
FU-NNNids; Kind ∈deferred | decision | compromise | limitation; Why accepted required forcompromise/limitation,revisit:required fordeferred(a bare milestone id there blocks that milestone from landing) - status
open→done (<sha> or PR #N, YYYY-MM-DD)/dropped (reason); entries never deleted or renamed docs/follow-ups.mdis a generated index for the user (skills/followup/scripts/fu-index.ps1), regenerated after every entry change and never read by agents — they grepdocs/fu/- a ledger still kept as one file is not supported:
/followupstops and points atskills/followup/scripts/fu-migrate.ps1, which converts it
The entry format and the grep queries live only in
followup/SKILL.md.doc-syncmaintains the ledger but never creates it;/impl-plan,/milestone,/implementand/walkthroughwrite to it only by invoking/followup(in swarm runs only the coordinator does, one at a time — workers proposeFU-TBD-*placeholders).- one file per entry,
- Plan/milestone docs. Shared by
skills/impl-plan,skills/milestone,skills/implement,agents/doc-sync.md, and the Documentation Workflow rule (claude-md-section.md);skills/walkthroughalso reads it, records milestone decisions (the overview'sD<n>bullets — same format as refresh, only forproposed/approveddocs, never touching Status) and draft-plan §Decisions, and owns the walkthrough log dir (defaultdocs/reviews/), which doc-sync never edits. The canonical copy is inskills/impl-plan/reference/, split by reader so/implementand doc-sync don't load authoring rules:doc-model.md(doc roles, layout, status words, who changes what, execution modes — read by everything),doc-authoring.md(convention detection, defaults, header fields incl.Written against, links, content rules — read only by/impl-plan,/milestoneand their subagents) anddoc-sync-plan.md(doc-sync's own transitions, read by the agent only in projects with a plan);milestone,implementandwalkthroughread them via${CLAUDE_SKILL_DIR}/../impl-plan/, so the four skills must deploy — and be trialled — together. Key invariants: milestone docs are folders (overview.mdaiming for 12 KB and 16 KB at most, oneWP<id>.md≤ 6 KB per work package,as-built.md) so each reader opens only its slice — landed single-file docs are frozen history and nothing writes that layout any more; docs are always swarm-ready (every WP hasAfter:,Model:,Review:, exclusive file ownership, hotspots inWP<n>.0) and hold only what something reads — verification is not a WP, the as-built record lists deviations only, and a section marked Optional is left out when empty; andExecution: guided | swarmonly changes how a milestone is implemented; the plan holds gates plus one status line per milestone; the milestone's as-built record is append-only and the doc is frozen once landed; doc-sync never creates or edits pre-written future milestone docs (it reportsneeds /milestone refresh <id>); a milestone with no doc when/implementreaches it is written by a writer agent that follows/milestone's single-doc path (implement/reference/jit.md— Sonnet at least; it hands back a quick scan so the user's questions arrive within minutes, then writes while they answer; no recheck, approved by/implement, implemented in the same session);/implementwrites only the routine progress markers (in progress, WP☑ landed/⛔ blocked) and invokes refresh,/followupand doc-sync for everything else — doc-sync once per milestone in guided mode (at landing, from the WP commits'Deviation:lines) and once per merged wave in swarm. - doc-sync vs docs-writer.
doc-synconly updates existing docs and reports gaps. Writing new docs belongs todocs-writer, except plans and milestone docs, which come from/impl-planand/milestone.
Authoring conventions
descriptiondrives auto-delegation and skill triggering. Say when to use the agent or skill, including trigger phrases — in at most 500 characters, since every description loads in every session; mode syntax belongs inargument-hintand the skill body. "Use proactively …" marks agents Claude should launch unprompted.- Reviewers don't change anything:
tools: Read, Grep, Glob, Bash, where Bash is only for reading git (diff/show/log/status) — their shared "Getting the change" section says so and sets the review depth (full/light). They omitmodel, so they inherit the main model — except under/implement, which launches them with an explicit one (Review: full→ Opus,light→ Sonnet). They share one shape: getting the change → categorized checks → rules → fixed output format → "What NOT to do". - Agents that write files (
doc-sync,docs-writer,refactorer,test-writer,wp-worker) getmodel: sonnetplus Write/Edit, and Bash where they need git or test runs./implementoverrideswp-workerto Opus per work package (Model: opusin the WP) and retries a Sonnet worker whose code failed on Opus. (The Haiku-worker trial, 2026-10-07 to 10-19, ended: at today's codebase size Haiku took more turns and retries and was no longer cheaper.) - Every agent has a
color. - A skill's directory name must match its frontmatter
name, which is the/commandusers type. - Heavy user-triggered skills that write many files use
disable-model-invocation: true(e.g.impl-plan); leave it off when Claude should be able to chain into the skill (e.g.milestone, whichimpl-planhands off to and Claude runs asrefreshbefore implementing).implementis model-invocable too, behind a gate in its own hard rules: self-invoked, it runs guided on one milestone and asks before the first commit; swarm/ranges need the user's explicit/implement. - Skills keep hard rules at the top of
SKILL.mdand push templates and long reference material into supporting files: after compaction only the start of a skill is re-attached.
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.

