geppetto
Skill2 starsChanged 24 days agoMITView on GitHub
Designs, installs, audits and updates Claude Code subagents in .claude/agents, with a starter roster: eng-lead, builder, reviewer, writer, sweeper. Use when the user says 'create an agent', 'install the agent roster', 'audit my agents' or 'update my agents', or when agents overlap or carry leftover tools. Writes agents, not skills.
In this repository38 other files it gives its agents.
- CLAUDE.mdCLAUDE.md
- arenaSkill
- codebase-oracleSkill
- lean-subagent-devSkill
- methodologySkill
- overnight-runSkill
- parallel-worktreesSkill
- dependency-security-auditSkill
- dependency-upgradeSkill
- rule-to-hookSkill
- safe-mergeSkill
- agent-friendly-auditSkill
- architectSkill
- brainstormSkill
- engineering-principlesSkill
- grill-meSkill
- improve-codebase-architectureSkill
- sharpenSkill
- to-issuesSkill
- to-prdSkill
- handoffSkill
- instructions-auditSkill
- project-setupSkill
- retrospectiveSkill
- session-closeSkill
- which-skillSkill
- bug-fixSkill
- ci-cost-and-cadenceSkill
- evaluatorSkill
- flaky-test-huntSkill
- hillclimbSkill
- launch-readinessSkill
- migration-reviewSkill
- mutation-testSkill
- review-triageSkill
- skill-evalSkill
- tddSkill
- verify-appSkill
The file
Show its rules and text
We split this skill into the rules it gives an agent
14 rules. About 0 are common, 1 is distinctive, and 13 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈1
Distinctive · estimate
This author's own choices. Worth a look.
13
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- could be automatic: a setting could enforce it
- Very specific: line 36
Before the yes, the skill writes only in .geppetto-draft/: the draft and its .gitignore (Create, step 4), or the merge copies and the same …
- Very specific: line 40
Project scope by default: Write to the project's .claude/agents/, to be committed so the agents work in cloud sessions and on every …
- Very specific: line 78
Do these in order. Read ${CLAUDE_SKILL_DIR}/COVENANT.md, ${CLAUDE_SKILL_DIR}/PRODUCTION-RULES.md and, for a designer, …
- Very specific: line 109
Check the draft in .geppetto-draft/ at the project root.
- Very specific: line 117
If an agent in .claude/agents/ already has that name, run rm -r .geppetto-draft from the project root, stop, and offer a merge (never …
- Very specific: line 119
If the draft has isolation: worktree and git check-ignore -q .claude/worktrees/x fails, offer the .claude/worktrees/ line for .gitignore as …
- Very specific: line 134
Only if the user names a design MCP server that already works in their sessions, add mcpServers: [<name>] to the frontmatter, add the …
- Distinctive: line 138
Add no production rules block: the designer writes no server code.
- Very specific: line 144
Read the five roster files, COVENANT.md and PRODUCTION-RULES.md.
- Very specific: line 151
Look at what is there: list .claude/agents/ (it may not exist) and read every file in it, and run git check-ignore -q .claude/worktrees/x …
- Very specific: line 163
Run node "${CLAUDE_SKILL_DIR}/check-agents.mjs" --project .
- Very specific: line 166
Commit .claude/agents/ and .gitignore.
- Very specific: line 177
Run node "${CLAUDE_SKILL_DIR}/check-agents.mjs" --project .
- Very specific: line 188
Add what the script cannot judge, agent by agent, from the body.
≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill 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
Geppetto
Geppetto makes and looks after a project's agent files: the subagents Claude Code loads from .claude/agents/. It
has four modes. Create designs one new agent. Install copies the bundled starter roster into the project.
Audit checks the agents already there. Update merges a newer bundled roster into tuned copies.
The request: $ARGUMENTS
Bundled files, open each when its mode needs it:
${CLAUDE_SKILL_DIR}/COVENANT.md: the laws every agent carries, between two marker lines, and the roster version.${CLAUDE_SKILL_DIR}/PRODUCTION-RULES.md: the production rules block, between two marker lines, that agents which change or review code carry.${CLAUDE_SKILL_DIR}/check-agents.mjs: the audit script (Node 20+, standard library, read only). It prints what is wrong with each agent file and exits 1 when there is an error. It importscheck-agents-yaml.mjsandcheck-agents-checks.mjs, which sit next to it; run onlycheck-agents.mjs.- The roster:
${CLAUDE_SKILL_DIR}/roster/eng-lead.md,${CLAUDE_SKILL_DIR}/roster/builder.md,${CLAUDE_SKILL_DIR}/roster/reviewer.md,${CLAUDE_SKILL_DIR}/roster/writer.mdand${CLAUDE_SKILL_DIR}/roster/sweeper.md. ${CLAUDE_SKILL_DIR}/templates/designer.md: the starting point for a designer agent in Create. It is not part of the roster, and Install does not copy it.
Rules for every mode
- Show before you write, and write on a yes. Show each file in full before creating it, and the exact diff before
changing one: agent files, the
.gitignoreline, Audit fixes and Update merges alike. The covenant block and the production rules block are the exceptions: each is the same in every file that carries it, so show it once in full and name it where it goes in each file. One yes may cover a set you showed together; a partial yes ("only builder and reviewer") covers only what it names. Approval of a plan or a report is not approval of a write. Before the yes, the skill writes only in.geppetto-draft/: the draft and its.gitignore(Create, step 4), or the merge copies and the same.gitignore(Update, step 2). They are only for the check or the merge, and they are never committed. - Never overwrite an existing agent file. Show the diff and merge on a yes instead.
- Project scope by default. Write to the project's
.claude/agents/, to be committed so the agents work in cloud sessions and on every computer. Write to~/.claude/agents/only when the user asks for it; cloud sessions start with that folder empty. - Writes under
.claude/ask twice. Claude Code treats.claude/as a protected path and asks again before each write there, even in acceptEdits mode. Tell the user so before the first write, so the second prompt is no surprise. - Commit nothing. Say what to commit; the user commits.
- Offer
eng-lead, never start it. Starting it runs builders and reviewers, which costs far more than this skill.
Facts the design rests on
Checked against the Claude Code docs (sub-agents, tools-reference, worktrees) on version 2.1.303:
- An agent is a Markdown file: YAML frontmatter, then the body, which becomes its system prompt. Only
nameanddescriptionare required. Claude Code ignores an unknown field without a word, and skips without a word a file whose YAML does not parse, that has nodescription, or whosenamehas a colon. A file with no frontmatter is documentation. .claude/agents/and~/.claude/agents/are read recursively. On a name clash the project wins over the user; inside one folder Claude Code loads one of the two files, by read order. A new agents folder loads only after a restart of Claude Code.- With a
toolslist, an agent has only those tools. On Linux and macOS, Glob and Grep are dropped when Bash is in the list, so an agent with Bash searches with Bash. memorygives the agent Read, Write and Edit, so it ends any read-only design.skills:loads each named skill's full text at start-up. Claude Code skips a name that is not installed, with only a debug-log line.- An agent with
isolation: worktreeworks in a git worktree under.claude/worktrees/, branched from the remote's default branch (not the session's branch) unlessworktree.baseRefishead. - Agents can start agents, three layers deep by default;
CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTHset to 1 turns that off. Agents have no AskUserQuestion tool: an agent that needs a yes stops, returns, and is continued by a message. - An agent continued with SendMessage resumes in the background. The main session is told when it finishes; an agent that sent the message has no tool to wait for it.
Pick the mode
From the request: "create", "make" or "design" an agent is Create; the roster or the starter agents is Install; "check", "audit", "clean up" or a named problem with existing agents is Audit; "update" after the skill changed is Update. If you cannot tell, ask which one, in one line.
Create
- Do these in order. Read
${CLAUDE_SKILL_DIR}/COVENANT.md,${CLAUDE_SKILL_DIR}/PRODUCTION-RULES.mdand, for a designer,${CLAUDE_SKILL_DIR}/templates/designer.md: the skill's read grant may be gone in a later turn (it was after a--resumein a headless run). Next look for.geppetto-draft/at the project root. If it is there, an earlier Create or Update left it: list its files and ask whether to remove it. If the user wants to keep it, stop: the check reads every file in the folder. On a yes, runrm -r .geppetto-draftfrom the project root. Then ask a few questions, one at a time, each with your suggested answer from what you can read in the project:- What one job does it do, and what does it hand back?
- What must it never do (its anti-jobs)?
- Does it change files, run commands, or only read?
- Does it start or continue other agents?
- Does it need to remember anything between runs, and is that worth giving it Write and Edit?
- What stops it and sends it back for a human yes?
- Decide whether a new agent is the right answer. Make one only for a job with its own goal, tool set, way of working, approval boundary or schedule. If an existing agent already covers it, propose a change to that agent instead. A "general helper" is a sign to stop and narrow the job.
- Draft the file:
name: lowercase words joined by hyphens, no colon.description: under 200 characters, saying when to pick this agent and not the others. The Agent tool lists every description in every session.tools: the fewest that do the job. List Glob and Grep only on an agent without Bash. List Agent and SendMessage when the body starts or continues agents.model: inherit. Seteffortonly with a reason, and say the reason.memoryonly when the agent writes files anyway or the user accepts that it can; never on a read-only agent.isolation: worktreewhen it changes code while other agents work in the same repository.skills:only for skills installed now (see Install, step 2), and a body that works without them.- The body: its job, its anti-jobs, its steps, its report format, and last the covenant block copied from
${CLAUDE_SKILL_DIR}/COVENANT.mdfrom marker line to marker line. Agent bodies cannot use${CLAUDE_SKILL_DIR}; write any path they need in full. - For an agent that changes or reviews code, paste the production rules block from
${CLAUDE_SKILL_DIR}/PRODUCTION-RULES.md, from marker line to marker line, just before the covenant. Leave it out of agents that plan, write prose or clean up.
- Check the draft in
.geppetto-draft/at the project root. The folder is inside the project, where acceptEdits writes without asking (it refuses a path outside the project); it is not under.claude/, which is protected, and it is not a rootagents/folder, which a plugin rooted at the project would load. First write.geppetto-draft/.gitignoreholding the one line*, so git never stages the folder, then the draft as.geppetto-draft/<name>.md. Runnode "${CLAUDE_SKILL_DIR}/check-agents.mjs" --dir .geppetto-draftfrom the project root. Its first line must count exactly 1 agent file. 0 agents means it ran in another folder or the draft has no frontmatter; 2 or more means a stale draft is in the folder: remove that file, then run the check again. Fix every error. Then the two checks the draft folder cannot do:- If an agent in
.claude/agents/already has thatname, runrm -r .geppetto-draftfrom the project root, stop, and offer a merge (never overwrite). - If the draft has
isolation: worktreeandgit check-ignore -q .claude/worktrees/xfails, offer the.claude/worktrees/line for.gitignoreas in Install, step 4.
- If an agent in
- Show the file and the check's output, ask, and write it on a yes. After the final write, or after a no to the
write, run
rm -r .geppetto-draftfrom the project root. If the write under.claude/agents/is refused, keep the folder, say so, and say how to allow the write; never copy or move the draft there with a shell command. After a write, run the Audit's script on the project.
A designer
For an agent that extends a design system in code, start from ${CLAUDE_SKILL_DIR}/templates/designer.md.
- Find the tokens file, the type and spacing scales, the components, the screens folder and the keyframe (the finished screen that sets the look). Suggest each one from what you read in the project and confirm it with the user.
- Fill "The design system" with those paths and names, never with values: the designer reads the values from the files on every run.
- Only if the user names a design MCP server that already works in their sessions, add
mcpServers: [<name>]to the frontmatter, add the server's tools totoolsasmcp__<prefix>__*, and name the tool under "Design tool". Read the prefix from the tool names the session lists for that server, not from its name: a server namedplugin:design:figmalists its tools asmcp__plugin_design_figma__.... Say that this path is unproven. - Add no production rules block: the designer writes no server code.
Then check the draft and show it as in Create, steps 4 and 5.
Install
- Read the five roster files,
COVENANT.mdandPRODUCTION-RULES.md. - Find the installed skills that an agent could preload. A skill counts as installed when it is in
.claude/skills/<name>/,~/.claude/skills/<name>/, or synced from claude.ai at~/.claude/skills/synced/*/<name>/SKILL.md. Iftddis installed, addskills:with it to builder's frontmatter, spelled the way the session's skill list shows it. Give reviewer noskills:line, even whenevaluatoris installed: that skill runs in a forked context and stops when it gets no arguments, so preloading it does nothing useful. Reviewer's body already carries the grading method. - Look at what is there: list
.claude/agents/(it may not exist) and read every file in it, and rungit check-ignore -q .claude/worktrees/xto see whether.claude/worktrees/is already ignored. - Show the plan and every file:
- each roster file that is new, in full, with any
skills:line you added (the covenant block and the production rules block each shown once, as the rules above say); - for each roster agent whose
nameis already in use, the diff between that file and the bundled one, and no write (offer Update or a merge); - the line
.claude/worktrees/to add to.gitignorewhen it is not ignored (builder works in worktrees there); - a note that Claude Code will ask again for each write under
.claude/. Then ask once.
- each roster file that is new, in full, with any
- On a yes, write exactly what was approved: create
.claude/agents/if needed, write the files, and append the.gitignoreline. - Run
node "${CLAUDE_SKILL_DIR}/check-agents.mjs" --project .and show its result. - Report: what was written, what was skipped and why, the check's result, and these next steps:
- Restart Claude Code if this created
.claude/agents/; the folder loads only after a restart. - Commit
.claude/agents/and.gitignore. - To use the roster: ask for
eng-leadwith the work to plan; it returns slices, briefs and a cost, and waits for a yes. Continued with the yes, it starts the builders, then a reviewer per slice, and returns each slice's branch, the review verdicts and a fix-round message addressed to that slice's builder. The main session sends those messages, waits for each builder's reply, then merges and pushes. For one small change, usebuilderand thenreviewerdirectly.writeredits docs,sweeperfrees disk space. - A designer agent is not in the roster: ask for Create to make one from the project's design system.
Offer
eng-lead; do not start it.
- Restart Claude Code if this created
Audit
- Run
node "${CLAUDE_SKILL_DIR}/check-agents.mjs" --project .(add--jsonto read it as data). It reads the project's and the user's agents and reports errors and warnings; the comment at the top of the script lists every check and the overlap score's threshold. Whenclaudeis installed, also runclaude plugin validate .claude/agents(andclaude plugin validate ~/.claude/agentsfor the user scope). It reads the files with Claude Code's own parser: a parse error there is an error, since Claude Code skips that file, whatever the script said. The script reports what it cannot parse as a warning and points at this command. Validate reads a folder of agents only at a path ending in.claude/agents; any other folder (a--dirfolder such as the bundled roster) fails with "No manifest found". For such a folder, validate a copy, as the warning says: copy the folder to<a temporary folder>/.claude/agentsand runclaude plugin validateon that path. The script checks the production rules block only on an agent that carries one: it must be closed, and at the bundle's roster version word for word the one inPRODUCTION-RULES.md. - Add what the script cannot judge, agent by agent, from the body. For a roster agent, first diff the installed
copy against its bundled file and judge only the lines that differ: the bundled settings (such as
effort: xhighon eng-lead) are the design, not findings.- Leftover tools: a tool in
toolsthat no step of the body needs, or notoolslist at all on an agent with a narrow job (it then has every tool). - One job: an agent with two unrelated jobs, or no anti-jobs.
- The description: does it say when to pick this agent and not another?
- A body that relies on a skill or a path that is not there.
- Leftover tools: a tool in
- Show the findings, with a proposed fix for each as an exact diff. Never apply a fix in the same message as the report.
- On a yes, apply the approved fixes, run the script again and show that the findings are gone.
Update
Each roster file carries its version on the covenant's start marker line: <!-- covenant start: geppetto roster N -->.
The audit warns when an installed copy carries an older number than the bundle.
- For each agent under
roster/, find the installed copy by itsname(any file in the scope, any file name) and read its version. Same version and same text: nothing to do. No copy: offer to install it as in Install. An installed agent that no file underroster/names was made by Create, a designer included. Replace only its covenant block and its production rules block, if it has one, with the new ones, and show that as a diff.templates/designer.mdis never a merge base: a merge against it puts the bracket placeholders back over the project's design system. - For a copy from an older bundle, separate the bundle's change from the user's tuning. If git history holds the
copy as it was first installed (
git log --diff-filter=A --format=%H -- <file>, thengit show <commit>:<file>), use that as the base for a three-way merge:git merge-file -p <installed copy> <old bundled copy> <new bundled copy>, run on copies in.geppetto-draft/(with the same.gitignore), removed as in Create, step 5. Before the first write there, look for a leftover.geppetto-draft/and ask about it as in Create, step 1; if the user wants to keep it, stop. Without that history, show the diff between the installed copy and the new bundle, section by section, and say which parts look tuned. - Show the merged file and the diff from the installed copy. The covenant block and the production rules block
always become the new ones; every other tuned line stays unless the user says otherwise. A
skills:line in the installed copy stays too: Install added it, and the bundled file has none, so the three-way merge drops it without a conflict; put it back before you show the merge. Conflicts are shown, never resolved silently. - On a yes, write the merged file. Then run the audit's script.
Next steps
Offer to run the Audit after Create, Install or Update if it did not run. If the user wants a skill rather than an
agent, say this skill writes agents only; offer to run skill-creator if it is installed.
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.

