[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"skill:01M7E4HTVJ93Z1AMY2FXWB895W":3,"skill-same:01M7E4HTVJ93Z1AMY2FXWB895W":96},{"skillNo":4,"name":5,"nameZh":6,"description":7,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":16,"categories":17,"keywords":18,"publishedAt":19,"linkOnly":20,"markdownContent":21,"markdownBody":22,"frontMatter":23,"refName":26,"commitSha":27,"skillDirectory":28,"forksCount":29,"repositoryHtmlUrl":30,"repositoryHomepageUrl":6,"ownerHtmlUrl":31,"ownerBlogUrl":6,"ownerDescription":32,"updatedAt":33,"install":34,"resources":47},"01M7E4HTVJ93Z1AMY2FXWB895W","geppetto",null,"Designs, installs, audits and updates Claude Code subagents in .claude\u002Fagents, 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.","paureis\u002Fpau-skills","paureis","https:\u002F\u002Favatars.githubusercontent.com\u002Fu\u002F133926455?v=4","01M7E4HCQNKQ22F6VQFHRFHW8K","Alvaro Reis","01M7E4HCRJJ4EDXQHFJN1MW493",2,"MIT","https:\u002F\u002Fgithub.com\u002Fpaureis\u002Fpau-skills\u002Fblob\u002Fmain\u002Fskills\u002Fagent-orchestration\u002Fgeppetto\u002FSKILL.md",[],[],"2026-11-15 14:19:17",false,"---\nname: geppetto\ndescription: \"Designs, installs, audits and updates Claude Code subagents in .claude\u002Fagents, 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.\"\nargument-hint: \"[create | install | audit | update] [what the agent is for]\"\nallowed-tools: Read(\u002F${CLAUDE_SKILL_DIR}\u002F**)\n---\n\n# Geppetto\n\nGeppetto makes and looks after a project's agent files: the subagents Claude Code loads from `.claude\u002Fagents\u002F`. It\nhas four modes. **Create** designs one new agent. **Install** copies the bundled starter roster into the project.\n**Audit** checks the agents already there. **Update** merges a newer bundled roster into tuned copies.\n\nThe request: $ARGUMENTS\n\nBundled files, open each when its mode needs it:\n- `${CLAUDE_SKILL_DIR}\u002FCOVENANT.md`: the laws every agent carries, between two marker lines, and the roster version.\n- `${CLAUDE_SKILL_DIR}\u002FPRODUCTION-RULES.md`: the production rules block, between two marker lines, that agents which\n  change or review code carry.\n- `${CLAUDE_SKILL_DIR}\u002Fcheck-agents.mjs`: the audit script (Node 20+, standard library, read only). It prints what is\n  wrong with each agent file and exits 1 when there is an error. It imports `check-agents-yaml.mjs` and\n  `check-agents-checks.mjs`, which sit next to it; run only `check-agents.mjs`.\n- The roster: `${CLAUDE_SKILL_DIR}\u002Froster\u002Feng-lead.md`, `${CLAUDE_SKILL_DIR}\u002Froster\u002Fbuilder.md`,\n  `${CLAUDE_SKILL_DIR}\u002Froster\u002Freviewer.md`, `${CLAUDE_SKILL_DIR}\u002Froster\u002Fwriter.md` and\n  `${CLAUDE_SKILL_DIR}\u002Froster\u002Fsweeper.md`.\n- `${CLAUDE_SKILL_DIR}\u002Ftemplates\u002Fdesigner.md`: the starting point for a designer agent in Create. It is not part of\n  the roster, and Install does not copy it.\n\n## Rules for every mode\n\n- **Show before you write, and write on a yes.** Show each file in full before creating it, and the exact diff before\n  changing one: agent files, the `.gitignore` line, Audit fixes and Update merges alike. The covenant block and the\n  production rules block are the exceptions: each is the same in every file that carries it, so show it once in full\n  and name it where it goes in each file. One yes may cover a set you showed together; a partial yes (\"only\n  builder and reviewer\") covers only what it names. Approval of a plan or a report is not approval of a write.\n  Before the yes, the skill writes only in `.geppetto-draft\u002F`: the draft and its `.gitignore` (Create, step 4), or\n  the merge copies and the same `.gitignore` (Update, step 2). They are only for the check or the merge, and they are\n  never committed.\n- **Never overwrite an existing agent file.** Show the diff and merge on a yes instead.\n- **Project scope by default.** Write to the project's `.claude\u002Fagents\u002F`, to be committed so the agents work in cloud\n  sessions and on every computer. Write to `~\u002F.claude\u002Fagents\u002F` only when the user asks for it; cloud sessions start\n  with that folder empty.\n- **Writes under `.claude\u002F` ask twice.** Claude Code treats `.claude\u002F` as a protected path and asks again before each\n  write there, even in acceptEdits mode. Tell the user so before the first write, so the second prompt is no surprise.\n- **Commit nothing.** Say what to commit; the user commits.\n- **Offer `eng-lead`, never start it.** Starting it runs builders and reviewers, which costs far more than this skill.\n\n## Facts the design rests on\n\nChecked against the Claude Code docs (`sub-agents`, `tools-reference`, `worktrees`) on version 2.1.303:\n- An agent is a Markdown file: YAML frontmatter, then the body, which becomes its system prompt. Only `name` and\n  `description` are required. Claude Code ignores an unknown field without a word, and skips without a word a file\n  whose YAML does not parse, that has no `description`, or whose `name` has a colon. A file with no frontmatter is\n  documentation.\n- `.claude\u002Fagents\u002F` and `~\u002F.claude\u002Fagents\u002F` are read recursively. On a name clash the project wins over the user;\n  inside one folder Claude Code loads one of the two files, by read order. A new agents folder loads only after a\n  restart of Claude Code.\n- With a `tools` list, an agent has only those tools. On Linux and macOS, Glob and Grep are dropped when Bash is in\n  the list, so an agent with Bash searches with Bash.\n- `memory` gives the agent Read, Write and Edit, so it ends any read-only design.\n- `skills:` loads each named skill's full text at start-up. Claude Code skips a name that is not installed, with only\n  a debug-log line.\n- An agent with `isolation: worktree` works in a git worktree under `.claude\u002Fworktrees\u002F`, branched from the remote's\n  default branch (not the session's branch) unless `worktree.baseRef` is `head`.\n- Agents can start agents, three layers deep by default; `CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH` set to 1 turns that\n  off. Agents have no AskUserQuestion tool: an agent that needs a yes stops, returns, and is continued by a message.\n- An agent continued with SendMessage resumes in the background. The main session is told when it finishes; an agent\n  that sent the message has no tool to wait for it.\n\n## Pick the mode\n\nFrom the request: \"create\", \"make\" or \"design\" an agent is **Create**; the roster or the starter agents is\n**Install**; \"check\", \"audit\", \"clean up\" or a named problem with existing agents is **Audit**; \"update\" after the\nskill changed is **Update**. If you cannot tell, ask which one, in one line.\n\n## Create\n\n1. Do these in order. Read `${CLAUDE_SKILL_DIR}\u002FCOVENANT.md`, `${CLAUDE_SKILL_DIR}\u002FPRODUCTION-RULES.md` and, for a\n   designer, `${CLAUDE_SKILL_DIR}\u002Ftemplates\u002Fdesigner.md`: the skill's read grant may be gone in a later turn (it was\n   after a `--resume` in a headless run). Next look for `.geppetto-draft\u002F` at the project root. If it is there, an\n   earlier Create or Update left it: list its files and ask whether to remove it. If the user wants to keep it, stop:\n   the check reads every file in the folder. On a yes, run `rm -r .geppetto-draft` from the project root. Then ask a\n   few questions, one at a time, each with your suggested answer from what you can read in the project:\n   - What one job does it do, and what does it hand back?\n   - What must it never do (its anti-jobs)?\n   - Does it change files, run commands, or only read?\n   - Does it start or continue other agents?\n   - Does it need to remember anything between runs, and is that worth giving it Write and Edit?\n   - What stops it and sends it back for a human yes?\n2. Decide whether a new agent is the right answer. Make one only for a job with its own goal, tool set, way of\n   working, approval boundary or schedule. If an existing agent already covers it, propose a change to that agent\n   instead. A \"general helper\" is a sign to stop and narrow the job.\n3. Draft the file:\n   - `name`: lowercase words joined by hyphens, no colon.\n   - `description`: under 200 characters, saying when to pick this agent and not the others. The Agent tool lists\n     every description in every session.\n   - `tools`: the fewest that do the job. List Glob and Grep only on an agent without Bash. List Agent and SendMessage\n     when the body starts or continues agents.\n   - `model: inherit`. Set `effort` only with a reason, and say the reason.\n   - `memory` only when the agent writes files anyway or the user accepts that it can; never on a read-only agent.\n   - `isolation: worktree` when it changes code while other agents work in the same repository.\n   - `skills:` only for skills installed now (see Install, step 2), and a body that works without them.\n   - The body: its job, its anti-jobs, its steps, its report format, and last the covenant block copied from\n     `${CLAUDE_SKILL_DIR}\u002FCOVENANT.md` from marker line to marker line. Agent bodies cannot use `${CLAUDE_SKILL_DIR}`;\n     write any path they need in full.\n   - For an agent that changes or reviews code, paste the production rules block from\n     `${CLAUDE_SKILL_DIR}\u002FPRODUCTION-RULES.md`, from marker line to marker line, just before the covenant. Leave it\n     out of agents that plan, write prose or clean up.\n4. Check the draft in `.geppetto-draft\u002F` at the project root. The folder is inside the project, where acceptEdits\n   writes without asking (it refuses a path outside the project); it is not under `.claude\u002F`, which is protected, and\n   it is not a root `agents\u002F` folder, which a plugin rooted at the project would load. First write\n   `.geppetto-draft\u002F.gitignore` holding the one line `*`, so git never stages the folder, then the draft as\n   `.geppetto-draft\u002F\u003Cname>.md`. Run `node \"${CLAUDE_SKILL_DIR}\u002Fcheck-agents.mjs\" --dir .geppetto-draft` from the\n   project root. Its first line must count exactly 1 agent file. 0 agents means it ran in another folder or the draft\n   has no frontmatter; 2 or more means a stale draft is in the folder: remove that file, then run the check again.\n   Fix every error. Then the two checks the draft folder cannot do:\n   - If an agent in `.claude\u002Fagents\u002F` already has that `name`, run `rm -r .geppetto-draft` from the project root,\n     stop, and offer a merge (never overwrite).\n   - If the draft has `isolation: worktree` and `git check-ignore -q .claude\u002Fworktrees\u002Fx` fails, offer the\n     `.claude\u002Fworktrees\u002F` line for `.gitignore` as in Install, step 4.\n5. 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\n   write, run `rm -r .geppetto-draft` from the project root. If the write under `.claude\u002Fagents\u002F` is refused, keep the\n   folder, say so, and say how to allow the write; never copy or move the draft there with a shell command. After a\n   write, run the Audit's script on the project.\n\n### A designer\n\nFor an agent that extends a design system in code, start from `${CLAUDE_SKILL_DIR}\u002Ftemplates\u002Fdesigner.md`.\n1. Find the tokens file, the type and spacing scales, the components, the screens folder and the keyframe (the\n   finished screen that sets the look). Suggest each one from what you read in the project and confirm it with the\n   user.\n2. Fill \"The design system\" with those paths and names, never with values: the designer reads the values from the\n   files on every run.\n3. Only if the user names a design MCP server that already works in their sessions, add `mcpServers: [\u003Cname>]` to the\n   frontmatter, add the server's tools to `tools` as `mcp__\u003Cprefix>__*`, and name the tool under \"Design tool\". Read\n   the prefix from the tool names the session lists for that server, not from its name: a server named\n   `plugin:design:figma` lists its tools as `mcp__plugin_design_figma__...`. Say that this path is unproven.\n4. Add no production rules block: the designer writes no server code.\n\nThen check the draft and show it as in Create, steps 4 and 5.\n\n## Install\n\n1. Read the five roster files, `COVENANT.md` and `PRODUCTION-RULES.md`.\n2. Find the installed skills that an agent could preload. A skill counts as installed when it is in\n   `.claude\u002Fskills\u002F\u003Cname>\u002F`, `~\u002F.claude\u002Fskills\u002F\u003Cname>\u002F`, or synced from claude.ai at\n   `~\u002F.claude\u002Fskills\u002Fsynced\u002F*\u002F\u003Cname>\u002FSKILL.md`. If `tdd` is installed, add `skills:` with it to builder's\n   frontmatter, spelled the way the session's skill list shows it. Give reviewer no `skills:` line, even when\n   `evaluator` is installed: that skill runs in a forked context and stops when it gets no arguments, so preloading it\n   does nothing useful. Reviewer's body already carries the grading method.\n3. Look at what is there: list `.claude\u002Fagents\u002F` (it may not exist) and read every file in it, and run\n   `git check-ignore -q .claude\u002Fworktrees\u002Fx` to see whether `.claude\u002Fworktrees\u002F` is already ignored.\n4. Show the plan and every file:\n   - each roster file that is new, in full, with any `skills:` line you added (the covenant block and the production\n     rules block each shown once, as the rules above say);\n   - for each roster agent whose `name` is already in use, the diff between that file and the bundled one, and no\n     write (offer Update or a merge);\n   - the line `.claude\u002Fworktrees\u002F` to add to `.gitignore` when it is not ignored (builder works in worktrees there);\n   - a note that Claude Code will ask again for each write under `.claude\u002F`.\n   Then ask once.\n5. On a yes, write exactly what was approved: create `.claude\u002Fagents\u002F` if needed, write the files, and append the\n   `.gitignore` line.\n6. Run `node \"${CLAUDE_SKILL_DIR}\u002Fcheck-agents.mjs\" --project .` and show its result.\n7. Report: what was written, what was skipped and why, the check's result, and these next steps:\n   - Restart Claude Code if this created `.claude\u002Fagents\u002F`; the folder loads only after a restart.\n   - Commit `.claude\u002Fagents\u002F` and `.gitignore`.\n   - To use the roster: ask for `eng-lead` with the work to plan; it returns slices, briefs and a cost, and waits for\n     a yes. Continued with the yes, it starts the builders, then a reviewer per slice, and returns each slice's\n     branch, the review verdicts and a fix-round message addressed to that slice's builder. The main session sends\n     those messages, waits for each builder's reply, then merges and pushes. For one small change, use `builder` and\n     then `reviewer` directly. `writer` edits docs, `sweeper` frees disk space.\n   - A designer agent is not in the roster: ask for Create to make one from the project's design system.\n   Offer `eng-lead`; do not start it.\n\n## Audit\n\n1. Run `node \"${CLAUDE_SKILL_DIR}\u002Fcheck-agents.mjs\" --project .` (add `--json` to read it as data). It reads the\n   project's and the user's agents and reports errors and warnings; the comment at the top of the script lists every\n   check and the overlap score's threshold. When `claude` is installed, also run `claude plugin validate .claude\u002Fagents`\n   (and `claude plugin validate ~\u002F.claude\u002Fagents` for the user scope). It reads the files with Claude Code's own\n   parser: a parse error there is an error, since Claude Code skips that file, whatever the script said. The script\n   reports what it cannot parse as a warning and points at this command. Validate reads a folder of agents only at a\n   path ending in `.claude\u002Fagents`; any other folder (a `--dir` folder such as the bundled roster) fails with \"No\n   manifest found\". For such a folder, validate a copy, as the warning says: copy the folder to\n   `\u003Ca temporary folder>\u002F.claude\u002Fagents` and run `claude plugin validate` on that path. The script checks the\n   production rules block only on an agent that carries one: it must be closed, and at the bundle's roster version\n   word for word the one in `PRODUCTION-RULES.md`.\n2. Add what the script cannot judge, agent by agent, from the body. For a roster agent, first diff the installed\n   copy against its bundled file and judge only the lines that differ: the bundled settings (such as `effort: xhigh`\n   on eng-lead) are the design, not findings.\n   - Leftover tools: a tool in `tools` that no step of the body needs, or no `tools` list at all on an agent with a\n     narrow job (it then has every tool).\n   - One job: an agent with two unrelated jobs, or no anti-jobs.\n   - The description: does it say when to pick this agent and not another?\n   - A body that relies on a skill or a path that is not there.\n3. Show the findings, with a proposed fix for each as an exact diff. Never apply a fix in the same message as the\n   report.\n4. On a yes, apply the approved fixes, run the script again and show that the findings are gone.\n\n## Update\n\nEach roster file carries its version on the covenant's start marker line: `\u003C!-- covenant start: geppetto roster N -->`.\nThe audit warns when an installed copy carries an older number than the bundle.\n\n1. For each agent under `roster\u002F`, find the installed copy by its `name` (any file in the scope, any file name) and\n   read its version. Same version and same text: nothing to do. No copy: offer to install it as in Install. An\n   installed agent that no file under `roster\u002F` names was made by Create, a designer included. Replace only its\n   covenant block and its production rules block, if it has one, with the new ones, and show that as a diff.\n   `templates\u002Fdesigner.md` is never a merge base: a merge against it puts the bracket placeholders back over the\n   project's design system.\n2. For a copy from an older bundle, separate the bundle's change from the user's tuning. If git history holds the\n   copy as it was first installed (`git log --diff-filter=A --format=%H -- \u003Cfile>`, then\n   `git show \u003Ccommit>:\u003Cfile>`), use that as the base for a three-way merge:\n   `git merge-file -p \u003Cinstalled copy> \u003Cold bundled copy> \u003Cnew bundled copy>`, run on copies in `.geppetto-draft\u002F`\n   (with the same `.gitignore`), removed as in Create, step 5. Before the first write there, look for a leftover\n   `.geppetto-draft\u002F` and ask about it as in Create, step 1; if the user wants to keep it, stop.\n   Without that history, show the diff between the installed copy and the new bundle, section by section, and say\n   which parts look tuned.\n3. Show the merged file and the diff from the installed copy. The covenant block and the production rules block\n   always become the new ones; every other tuned line stays unless the user says otherwise. A `skills:` line in the\n   installed copy stays too: Install added it, and the bundled file has none, so the three-way merge drops it without\n   a conflict; put it back before you show the merge. Conflicts are shown, never resolved silently.\n4. On a yes, write the merged file. Then run the audit's script.\n\n## Next steps\n\nOffer to run the Audit after Create, Install or Update if it did not run. If the user wants a skill rather than an\nagent, say this skill writes agents only; offer to run `skill-creator` if it is installed.\n","# Geppetto\n\nGeppetto makes and looks after a project's agent files: the subagents Claude Code loads from `.claude\u002Fagents\u002F`. It\nhas four modes. **Create** designs one new agent. **Install** copies the bundled starter roster into the project.\n**Audit** checks the agents already there. **Update** merges a newer bundled roster into tuned copies.\n\nThe request: $ARGUMENTS\n\nBundled files, open each when its mode needs it:\n- `${CLAUDE_SKILL_DIR}\u002FCOVENANT.md`: the laws every agent carries, between two marker lines, and the roster version.\n- `${CLAUDE_SKILL_DIR}\u002FPRODUCTION-RULES.md`: the production rules block, between two marker lines, that agents which\n  change or review code carry.\n- `${CLAUDE_SKILL_DIR}\u002Fcheck-agents.mjs`: the audit script (Node 20+, standard library, read only). It prints what is\n  wrong with each agent file and exits 1 when there is an error. It imports `check-agents-yaml.mjs` and\n  `check-agents-checks.mjs`, which sit next to it; run only `check-agents.mjs`.\n- The roster: `${CLAUDE_SKILL_DIR}\u002Froster\u002Feng-lead.md`, `${CLAUDE_SKILL_DIR}\u002Froster\u002Fbuilder.md`,\n  `${CLAUDE_SKILL_DIR}\u002Froster\u002Freviewer.md`, `${CLAUDE_SKILL_DIR}\u002Froster\u002Fwriter.md` and\n  `${CLAUDE_SKILL_DIR}\u002Froster\u002Fsweeper.md`.\n- `${CLAUDE_SKILL_DIR}\u002Ftemplates\u002Fdesigner.md`: the starting point for a designer agent in Create. It is not part of\n  the roster, and Install does not copy it.\n\n## Rules for every mode\n\n- **Show before you write, and write on a yes.** Show each file in full before creating it, and the exact diff before\n  changing one: agent files, the `.gitignore` line, Audit fixes and Update merges alike. The covenant block and the\n  production rules block are the exceptions: each is the same in every file that carries it, so show it once in full\n  and name it where it goes in each file. One yes may cover a set you showed together; a partial yes (\"only\n  builder and reviewer\") covers only what it names. Approval of a plan or a report is not approval of a write.\n  Before the yes, the skill writes only in `.geppetto-draft\u002F`: the draft and its `.gitignore` (Create, step 4), or\n  the merge copies and the same `.gitignore` (Update, step 2). They are only for the check or the merge, and they are\n  never committed.\n- **Never overwrite an existing agent file.** Show the diff and merge on a yes instead.\n- **Project scope by default.** Write to the project's `.claude\u002Fagents\u002F`, to be committed so the agents work in cloud\n  sessions and on every computer. Write to `~\u002F.claude\u002Fagents\u002F` only when the user asks for it; cloud sessions start\n  with that folder empty.\n- **Writes under `.claude\u002F` ask twice.** Claude Code treats `.claude\u002F` as a protected path and asks again before each\n  write there, even in acceptEdits mode. Tell the user so before the first write, so the second prompt is no surprise.\n- **Commit nothing.** Say what to commit; the user commits.\n- **Offer `eng-lead`, never start it.** Starting it runs builders and reviewers, which costs far more than this skill.\n\n## Facts the design rests on\n\nChecked against the Claude Code docs (`sub-agents`, `tools-reference`, `worktrees`) on version 2.1.303:\n- An agent is a Markdown file: YAML frontmatter, then the body, which becomes its system prompt. Only `name` and\n  `description` are required. Claude Code ignores an unknown field without a word, and skips without a word a file\n  whose YAML does not parse, that has no `description`, or whose `name` has a colon. A file with no frontmatter is\n  documentation.\n- `.claude\u002Fagents\u002F` and `~\u002F.claude\u002Fagents\u002F` are read recursively. On a name clash the project wins over the user;\n  inside one folder Claude Code loads one of the two files, by read order. A new agents folder loads only after a\n  restart of Claude Code.\n- With a `tools` list, an agent has only those tools. On Linux and macOS, Glob and Grep are dropped when Bash is in\n  the list, so an agent with Bash searches with Bash.\n- `memory` gives the agent Read, Write and Edit, so it ends any read-only design.\n- `skills:` loads each named skill's full text at start-up. Claude Code skips a name that is not installed, with only\n  a debug-log line.\n- An agent with `isolation: worktree` works in a git worktree under `.claude\u002Fworktrees\u002F`, branched from the remote's\n  default branch (not the session's branch) unless `worktree.baseRef` is `head`.\n- Agents can start agents, three layers deep by default; `CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH` set to 1 turns that\n  off. Agents have no AskUserQuestion tool: an agent that needs a yes stops, returns, and is continued by a message.\n- An agent continued with SendMessage resumes in the background. The main session is told when it finishes; an agent\n  that sent the message has no tool to wait for it.\n\n## Pick the mode\n\nFrom the request: \"create\", \"make\" or \"design\" an agent is **Create**; the roster or the starter agents is\n**Install**; \"check\", \"audit\", \"clean up\" or a named problem with existing agents is **Audit**; \"update\" after the\nskill changed is **Update**. If you cannot tell, ask which one, in one line.\n\n## Create\n\n1. Do these in order. Read `${CLAUDE_SKILL_DIR}\u002FCOVENANT.md`, `${CLAUDE_SKILL_DIR}\u002FPRODUCTION-RULES.md` and, for a\n   designer, `${CLAUDE_SKILL_DIR}\u002Ftemplates\u002Fdesigner.md`: the skill's read grant may be gone in a later turn (it was\n   after a `--resume` in a headless run). Next look for `.geppetto-draft\u002F` at the project root. If it is there, an\n   earlier Create or Update left it: list its files and ask whether to remove it. If the user wants to keep it, stop:\n   the check reads every file in the folder. On a yes, run `rm -r .geppetto-draft` from the project root. Then ask a\n   few questions, one at a time, each with your suggested answer from what you can read in the project:\n   - What one job does it do, and what does it hand back?\n   - What must it never do (its anti-jobs)?\n   - Does it change files, run commands, or only read?\n   - Does it start or continue other agents?\n   - Does it need to remember anything between runs, and is that worth giving it Write and Edit?\n   - What stops it and sends it back for a human yes?\n2. Decide whether a new agent is the right answer. Make one only for a job with its own goal, tool set, way of\n   working, approval boundary or schedule. If an existing agent already covers it, propose a change to that agent\n   instead. A \"general helper\" is a sign to stop and narrow the job.\n3. Draft the file:\n   - `name`: lowercase words joined by hyphens, no colon.\n   - `description`: under 200 characters, saying when to pick this agent and not the others. The Agent tool lists\n     every description in every session.\n   - `tools`: the fewest that do the job. List Glob and Grep only on an agent without Bash. List Agent and SendMessage\n     when the body starts or continues agents.\n   - `model: inherit`. Set `effort` only with a reason, and say the reason.\n   - `memory` only when the agent writes files anyway or the user accepts that it can; never on a read-only agent.\n   - `isolation: worktree` when it changes code while other agents work in the same repository.\n   - `skills:` only for skills installed now (see Install, step 2), and a body that works without them.\n   - The body: its job, its anti-jobs, its steps, its report format, and last the covenant block copied from\n     `${CLAUDE_SKILL_DIR}\u002FCOVENANT.md` from marker line to marker line. Agent bodies cannot use `${CLAUDE_SKILL_DIR}`;\n     write any path they need in full.\n   - For an agent that changes or reviews code, paste the production rules block from\n     `${CLAUDE_SKILL_DIR}\u002FPRODUCTION-RULES.md`, from marker line to marker line, just before the covenant. Leave it\n     out of agents that plan, write prose or clean up.\n4. Check the draft in `.geppetto-draft\u002F` at the project root. The folder is inside the project, where acceptEdits\n   writes without asking (it refuses a path outside the project); it is not under `.claude\u002F`, which is protected, and\n   it is not a root `agents\u002F` folder, which a plugin rooted at the project would load. First write\n   `.geppetto-draft\u002F.gitignore` holding the one line `*`, so git never stages the folder, then the draft as\n   `.geppetto-draft\u002F\u003Cname>.md`. Run `node \"${CLAUDE_SKILL_DIR}\u002Fcheck-agents.mjs\" --dir .geppetto-draft` from the\n   project root. Its first line must count exactly 1 agent file. 0 agents means it ran in another folder or the draft\n   has no frontmatter; 2 or more means a stale draft is in the folder: remove that file, then run the check again.\n   Fix every error. Then the two checks the draft folder cannot do:\n   - If an agent in `.claude\u002Fagents\u002F` already has that `name`, run `rm -r .geppetto-draft` from the project root,\n     stop, and offer a merge (never overwrite).\n   - If the draft has `isolation: worktree` and `git check-ignore -q .claude\u002Fworktrees\u002Fx` fails, offer the\n     `.claude\u002Fworktrees\u002F` line for `.gitignore` as in Install, step 4.\n5. 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\n   write, run `rm -r .geppetto-draft` from the project root. If the write under `.claude\u002Fagents\u002F` is refused, keep the\n   folder, say so, and say how to allow the write; never copy or move the draft there with a shell command. After a\n   write, run the Audit's script on the project.\n\n### A designer\n\nFor an agent that extends a design system in code, start from `${CLAUDE_SKILL_DIR}\u002Ftemplates\u002Fdesigner.md`.\n1. Find the tokens file, the type and spacing scales, the components, the screens folder and the keyframe (the\n   finished screen that sets the look). Suggest each one from what you read in the project and confirm it with the\n   user.\n2. Fill \"The design system\" with those paths and names, never with values: the designer reads the values from the\n   files on every run.\n3. Only if the user names a design MCP server that already works in their sessions, add `mcpServers: [\u003Cname>]` to the\n   frontmatter, add the server's tools to `tools` as `mcp__\u003Cprefix>__*`, and name the tool under \"Design tool\". Read\n   the prefix from the tool names the session lists for that server, not from its name: a server named\n   `plugin:design:figma` lists its tools as `mcp__plugin_design_figma__...`. Say that this path is unproven.\n4. Add no production rules block: the designer writes no server code.\n\nThen check the draft and show it as in Create, steps 4 and 5.\n\n## Install\n\n1. Read the five roster files, `COVENANT.md` and `PRODUCTION-RULES.md`.\n2. Find the installed skills that an agent could preload. A skill counts as installed when it is in\n   `.claude\u002Fskills\u002F\u003Cname>\u002F`, `~\u002F.claude\u002Fskills\u002F\u003Cname>\u002F`, or synced from claude.ai at\n   `~\u002F.claude\u002Fskills\u002Fsynced\u002F*\u002F\u003Cname>\u002FSKILL.md`. If `tdd` is installed, add `skills:` with it to builder's\n   frontmatter, spelled the way the session's skill list shows it. Give reviewer no `skills:` line, even when\n   `evaluator` is installed: that skill runs in a forked context and stops when it gets no arguments, so preloading it\n   does nothing useful. Reviewer's body already carries the grading method.\n3. Look at what is there: list `.claude\u002Fagents\u002F` (it may not exist) and read every file in it, and run\n   `git check-ignore -q .claude\u002Fworktrees\u002Fx` to see whether `.claude\u002Fworktrees\u002F` is already ignored.\n4. Show the plan and every file:\n   - each roster file that is new, in full, with any `skills:` line you added (the covenant block and the production\n     rules block each shown once, as the rules above say);\n   - for each roster agent whose `name` is already in use, the diff between that file and the bundled one, and no\n     write (offer Update or a merge);\n   - the line `.claude\u002Fworktrees\u002F` to add to `.gitignore` when it is not ignored (builder works in worktrees there);\n   - a note that Claude Code will ask again for each write under `.claude\u002F`.\n   Then ask once.\n5. On a yes, write exactly what was approved: create `.claude\u002Fagents\u002F` if needed, write the files, and append the\n   `.gitignore` line.\n6. Run `node \"${CLAUDE_SKILL_DIR}\u002Fcheck-agents.mjs\" --project .` and show its result.\n7. Report: what was written, what was skipped and why, the check's result, and these next steps:\n   - Restart Claude Code if this created `.claude\u002Fagents\u002F`; the folder loads only after a restart.\n   - Commit `.claude\u002Fagents\u002F` and `.gitignore`.\n   - To use the roster: ask for `eng-lead` with the work to plan; it returns slices, briefs and a cost, and waits for\n     a yes. Continued with the yes, it starts the builders, then a reviewer per slice, and returns each slice's\n     branch, the review verdicts and a fix-round message addressed to that slice's builder. The main session sends\n     those messages, waits for each builder's reply, then merges and pushes. For one small change, use `builder` and\n     then `reviewer` directly. `writer` edits docs, `sweeper` frees disk space.\n   - A designer agent is not in the roster: ask for Create to make one from the project's design system.\n   Offer `eng-lead`; do not start it.\n\n## Audit\n\n1. Run `node \"${CLAUDE_SKILL_DIR}\u002Fcheck-agents.mjs\" --project .` (add `--json` to read it as data). It reads the\n   project's and the user's agents and reports errors and warnings; the comment at the top of the script lists every\n   check and the overlap score's threshold. When `claude` is installed, also run `claude plugin validate .claude\u002Fagents`\n   (and `claude plugin validate ~\u002F.claude\u002Fagents` for the user scope). It reads the files with Claude Code's own\n   parser: a parse error there is an error, since Claude Code skips that file, whatever the script said. The script\n   reports what it cannot parse as a warning and points at this command. Validate reads a folder of agents only at a\n   path ending in `.claude\u002Fagents`; any other folder (a `--dir` folder such as the bundled roster) fails with \"No\n   manifest found\". For such a folder, validate a copy, as the warning says: copy the folder to\n   `\u003Ca temporary folder>\u002F.claude\u002Fagents` and run `claude plugin validate` on that path. The script checks the\n   production rules block only on an agent that carries one: it must be closed, and at the bundle's roster version\n   word for word the one in `PRODUCTION-RULES.md`.\n2. Add what the script cannot judge, agent by agent, from the body. For a roster agent, first diff the installed\n   copy against its bundled file and judge only the lines that differ: the bundled settings (such as `effort: xhigh`\n   on eng-lead) are the design, not findings.\n   - Leftover tools: a tool in `tools` that no step of the body needs, or no `tools` list at all on an agent with a\n     narrow job (it then has every tool).\n   - One job: an agent with two unrelated jobs, or no anti-jobs.\n   - The description: does it say when to pick this agent and not another?\n   - A body that relies on a skill or a path that is not there.\n3. Show the findings, with a proposed fix for each as an exact diff. Never apply a fix in the same message as the\n   report.\n4. On a yes, apply the approved fixes, run the script again and show that the findings are gone.\n\n## Update\n\nEach roster file carries its version on the covenant's start marker line: `\u003C!-- covenant start: geppetto roster N -->`.\nThe audit warns when an installed copy carries an older number than the bundle.\n\n1. For each agent under `roster\u002F`, find the installed copy by its `name` (any file in the scope, any file name) and\n   read its version. Same version and same text: nothing to do. No copy: offer to install it as in Install. An\n   installed agent that no file under `roster\u002F` names was made by Create, a designer included. Replace only its\n   covenant block and its production rules block, if it has one, with the new ones, and show that as a diff.\n   `templates\u002Fdesigner.md` is never a merge base: a merge against it puts the bracket placeholders back over the\n   project's design system.\n2. For a copy from an older bundle, separate the bundle's change from the user's tuning. If git history holds the\n   copy as it was first installed (`git log --diff-filter=A --format=%H -- \u003Cfile>`, then\n   `git show \u003Ccommit>:\u003Cfile>`), use that as the base for a three-way merge:\n   `git merge-file -p \u003Cinstalled copy> \u003Cold bundled copy> \u003Cnew bundled copy>`, run on copies in `.geppetto-draft\u002F`\n   (with the same `.gitignore`), removed as in Create, step 5. Before the first write there, look for a leftover\n   `.geppetto-draft\u002F` and ask about it as in Create, step 1; if the user wants to keep it, stop.\n   Without that history, show the diff between the installed copy and the new bundle, section by section, and say\n   which parts look tuned.\n3. Show the merged file and the diff from the installed copy. The covenant block and the production rules block\n   always become the new ones; every other tuned line stays unless the user says otherwise. A `skills:` line in the\n   installed copy stays too: Install added it, and the bundled file has none, so the three-way merge drops it without\n   a conflict; put it back before you show the merge. Conflicts are shown, never resolved silently.\n4. On a yes, write the merged file. Then run the audit's script.\n\n## Next steps\n\nOffer to run the Audit after Create, Install or Update if it did not run. If the user wants a skill rather than an\nagent, say this skill writes agents only; offer to run `skill-creator` if it is installed.\n",{"name":5,"description":7,"allowed-tools":24,"argument-hint":25},"Read(\u002F${CLAUDE_SKILL_DIR}\u002F**)","[create | install | audit | update] [what the agent is for]","main","2817107c191e822dfe71d6aff5d286cc8211c592","skills\u002Fagent-orchestration\u002Fgeppetto",0,"https:\u002F\u002Fgithub.com\u002Fpaureis\u002Fpau-skills","https:\u002F\u002Fgithub.com\u002Fpaureis","AI engineer | building multi-tenant products end to end","2026-11-12 06:02:49",{"source":8,"skillName":5,"commands":35,"prompt":45,"zipAvailable":46},[36,39,42],{"tool":37,"command":38},"npx","npx skills add paureis\u002Fpau-skills --skill geppetto",{"tool":40,"command":41},"bunx","bunx skills add paureis\u002Fpau-skills --skill geppetto",{"tool":43,"command":44},"pnpm","pnpm dlx skills add paureis\u002Fpau-skills --skill geppetto","安装技能，技能地址：https:\u002F\u002Fgithub.com\u002Fpaureis\u002Fpau-skills\u002Fblob\u002Fmain\u002Fskills\u002Fagent-orchestration\u002Fgeppetto\u002FSKILL.md",true,[48,54,58,62,68,72,76,80,84,88,92],{"path":49,"resourceType":50,"resourceTypeDesc":51,"sizeBytes":52,"sourceHtmlUrl":53},"check-agents-checks.mjs","SCRIPT","脚本",15852,"https:\u002F\u002Fgithub.com\u002Fpaureis\u002Fpau-skills\u002Fblob\u002Fmain\u002Fskills\u002Fagent-orchestration\u002Fgeppetto\u002Fcheck-agents-checks.mjs",{"path":55,"resourceType":50,"resourceTypeDesc":51,"sizeBytes":56,"sourceHtmlUrl":57},"check-agents-yaml.mjs",12351,"https:\u002F\u002Fgithub.com\u002Fpaureis\u002Fpau-skills\u002Fblob\u002Fmain\u002Fskills\u002Fagent-orchestration\u002Fgeppetto\u002Fcheck-agents-yaml.mjs",{"path":59,"resourceType":50,"resourceTypeDesc":51,"sizeBytes":60,"sourceHtmlUrl":61},"check-agents.mjs",11543,"https:\u002F\u002Fgithub.com\u002Fpaureis\u002Fpau-skills\u002Fblob\u002Fmain\u002Fskills\u002Fagent-orchestration\u002Fgeppetto\u002Fcheck-agents.mjs",{"path":63,"resourceType":64,"resourceTypeDesc":65,"sizeBytes":66,"sourceHtmlUrl":67},"COVENANT.md","REFERENCE","参考文档",2018,"https:\u002F\u002Fgithub.com\u002Fpaureis\u002Fpau-skills\u002Fblob\u002Fmain\u002Fskills\u002Fagent-orchestration\u002Fgeppetto\u002FCOVENANT.md",{"path":69,"resourceType":64,"resourceTypeDesc":65,"sizeBytes":70,"sourceHtmlUrl":71},"PRODUCTION-RULES.md",7749,"https:\u002F\u002Fgithub.com\u002Fpaureis\u002Fpau-skills\u002Fblob\u002Fmain\u002Fskills\u002Fagent-orchestration\u002Fgeppetto\u002FPRODUCTION-RULES.md",{"path":73,"resourceType":64,"resourceTypeDesc":65,"sizeBytes":74,"sourceHtmlUrl":75},"roster\u002Fbuilder.md",7700,"https:\u002F\u002Fgithub.com\u002Fpaureis\u002Fpau-skills\u002Fblob\u002Fmain\u002Fskills\u002Fagent-orchestration\u002Fgeppetto\u002Froster\u002Fbuilder.md",{"path":77,"resourceType":64,"resourceTypeDesc":65,"sizeBytes":78,"sourceHtmlUrl":79},"roster\u002Feng-lead.md",8211,"https:\u002F\u002Fgithub.com\u002Fpaureis\u002Fpau-skills\u002Fblob\u002Fmain\u002Fskills\u002Fagent-orchestration\u002Fgeppetto\u002Froster\u002Feng-lead.md",{"path":81,"resourceType":64,"resourceTypeDesc":65,"sizeBytes":82,"sourceHtmlUrl":83},"roster\u002Freviewer.md",7362,"https:\u002F\u002Fgithub.com\u002Fpaureis\u002Fpau-skills\u002Fblob\u002Fmain\u002Fskills\u002Fagent-orchestration\u002Fgeppetto\u002Froster\u002Freviewer.md",{"path":85,"resourceType":64,"resourceTypeDesc":65,"sizeBytes":86,"sourceHtmlUrl":87},"roster\u002Fsweeper.md",3332,"https:\u002F\u002Fgithub.com\u002Fpaureis\u002Fpau-skills\u002Fblob\u002Fmain\u002Fskills\u002Fagent-orchestration\u002Fgeppetto\u002Froster\u002Fsweeper.md",{"path":89,"resourceType":64,"resourceTypeDesc":65,"sizeBytes":90,"sourceHtmlUrl":91},"roster\u002Fwriter.md",2674,"https:\u002F\u002Fgithub.com\u002Fpaureis\u002Fpau-skills\u002Fblob\u002Fmain\u002Fskills\u002Fagent-orchestration\u002Fgeppetto\u002Froster\u002Fwriter.md",{"path":93,"resourceType":64,"resourceTypeDesc":65,"sizeBytes":94,"sourceHtmlUrl":95},"templates\u002Fdesigner.md",6194,"https:\u002F\u002Fgithub.com\u002Fpaureis\u002Fpau-skills\u002Fblob\u002Fmain\u002Fskills\u002Fagent-orchestration\u002Fgeppetto\u002Ftemplates\u002Fdesigner.md",[97,104,109,116,122,129],{"skillNo":98,"name":99,"nameZh":6,"description":100,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":101,"categories":102,"keywords":103,"publishedAt":19},"01M7E4SRKNACXVPZYJ6HX2PQXY","tidy-notes","Tidy a plain text list: sort the lines and remove repeated ones. Use when the user types \u002Ftidy-notes.","https:\u002F\u002Fgithub.com\u002Fpaureis\u002Fpau-skills\u002Fblob\u002Fmain\u002Ftests\u002Ffixtures\u002Fskill-eval\u002Fvariant-b\u002FSKILL.md",[],[],{"skillNo":105,"name":99,"nameZh":6,"description":100,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":106,"categories":107,"keywords":108,"publishedAt":19},"01M7E4SMEGAVM1547Y611T38SM","https:\u002F\u002Fgithub.com\u002Fpaureis\u002Fpau-skills\u002Fblob\u002Fmain\u002Ftests\u002Ffixtures\u002Fskill-eval\u002Fvariant-a\u002FSKILL.md",[],[],{"skillNo":110,"name":111,"nameZh":6,"description":112,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":113,"categories":114,"keywords":115,"publishedAt":19},"01M7E4SGSPHAJKYR8RX45ZKH3F","other-notes","A skill with a different name, for the refusal case.","https:\u002F\u002Fgithub.com\u002Fpaureis\u002Fpau-skills\u002Fblob\u002Fmain\u002Ftests\u002Ffixtures\u002Fskill-eval\u002Fother-name\u002FSKILL.md",[],[],{"skillNo":117,"name":99,"nameZh":6,"description":118,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":119,"categories":120,"keywords":121,"publishedAt":19},"01M7E4SCTQ7AR5MGPJ3YRXSF06","Tidy a plain text list: sort the lines and remove repeated ones. Use when the user asks to tidy notes.","https:\u002F\u002Fgithub.com\u002Fpaureis\u002Fpau-skills\u002Fblob\u002Fmain\u002Ftests\u002Ffixtures\u002Fskill-eval-triggers\u002Fskills\u002Ftidy-notes\u002FSKILL.md",[],[],{"skillNo":123,"name":124,"nameZh":6,"description":125,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":126,"categories":127,"keywords":128,"publishedAt":19},"01M7E4S920AVTNN4W61JQY4X9Z","pack-boxes","Plan how to pack boxes for a move, room by room. Use when the user asks to pack for a move.","https:\u002F\u002Fgithub.com\u002Fpaureis\u002Fpau-skills\u002Fblob\u002Fmain\u002Ftests\u002Ffixtures\u002Fskill-eval-triggers\u002Fskills\u002Fpack-boxes\u002FSKILL.md",[],[],{"skillNo":130,"name":131,"nameZh":6,"description":132,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":133,"categories":134,"keywords":135,"publishedAt":19},"01M7E4S4ZXZWND0TGQ1E4N39KP","renamed-skill","A skill whose folder name differs from its name. Use when the user asks to rename something.","https:\u002F\u002Fgithub.com\u002Fpaureis\u002Fpau-skills\u002Fblob\u002Fmain\u002Ftests\u002Ffixtures\u002Fskill-eval-triggers\u002Frenamed\u002Fsome-folder\u002FSKILL.md",[],[]]