Skill Build

Design and build a complete new skill from a blank page, in your own house style. The skill lifecycle is build (this skill), then audit (skill-audit), then publish (your publishing step, if you share skills); this skill owns the build stage and hands off to the next.

Adapted from skill-engineer-master by Antony Evans (edge-brain-lite, https://github.com/antonyevans/edge-brain-lite, CC BY 4.0). Modified: decoupled from the edge-brain research and persistence layer and the public skill marketplaces, re-targeted to a house style the builder records from your own existing skills, and the always-mandatory evals, Gotchas, learnings, and edge-cases requirements demoted to recommendations.

What this builds

A skill folder under ~/.claude/skills/<name>/ that matches how your existing skills are built: frontmatter Claude Code actually reads (name, description, and usually when_to_use), numbered steps with their reasoning, reference files one level deep, scripts only for genuinely mechanical steps, and the conditional sections your skills use (a session log, an independent audit agent, a writing-voice prerequisite, a report-only contract). Read references/house-style.md for the house-style spec and references/skill-design-framework.md for the design principles.

Phase 0: Survey the existing suite (do this first, always)

Before designing anything, check whether a skill for this already exists or whether an existing skill should be extended instead of adding a new one. Weight the merge instinct heavily; do not entrench a needless separation.

1. List ~/.claude/skills/, and read your skill index if you keep one.
2. Grep the skill descriptions and the closest one or two SKILL.md files for the proposed capability.
3. If an existing skill already covers it or substantially overlaps, stop and recommend extending that skill rather than building a new one. Present the finding and ask before proceeding.
4. If references/house-style.md has not been filled in yet, fill it in now: read three to five of your existing skills and record their conventions under that file's section headings. Every later phase reads it.

WHY: a duplicated or near-duplicated skill drifts from its twin and creates routing ambiguity. The cheapest skill is the one not built. And a house style inferred once from real skills beats one guessed at on every build.

Phase 1: Intake

Ask only the questions whose answers change the design. Skip any already answered.

1. Task: what workflow should this skill execute, in one sentence.
2. Trigger: what user input should activate it, and what should NOT (the negative cases).
3. Tools and connectors: what MCPs, APIs, or scripts it needs; any navigation notes.
4. Human-in-the-loop points: where a human must approve, choose, or verify before the skill continues.
5. Output: what a successful run produces (artifact type, format, destination).
6. Failure baseline: what Claude does wrong on this task today without a skill. If unknown, predict the failure modes now and verify them in Phase 4.
7. Frontmatter choices: does it pin model/effort (ask once; the default is to inherit the session model), and who may invoke it: both the user and the model (default), the model only (user-invocable: false, for a helper other skills call), or the user only (disable-model-invocation: true, for a skill that sends, publishes, or deletes; see the shorthand caveat in references/house-style.md section 3).

Phase 2: Design (present, get approval before any writes)

Read references/skill-design-framework.md and references/house-style.md. Work through the design and present a full summary for approval. Build nothing until the design is approved: present, then wait.

Cover in the design summary:

• Identity: the name, the single-line description, and the when_to_use sentence. Invest most of the effort in the description; it is the routing signal that decides whether the skill fires. Draft it, and any internal agent prompts, with a prompt-writing step (a prompt-writing skill if you have one). The description names the artifact, uses outcome language for triggers, includes negative triggers, and stays on one line.
• Output contract: what it produces, what it does not, what it enables, and what consumes the output next.
• Process steps: each step with its reasoning principle, not just the procedure, so the skill generalizes past the cases you foresaw.
• Script inventory: classify every step as reason or execute. Ship a script for each execute step (an HTTP or API call, a repeatable file transform, a loop over more than about three items, an exact-format output, a credential touch, a schema or rubric check, or a state append). Start scripts from scripts/archetypes/. List the scripts in a table.
• Conditional sections (from references/house-style.md section 3): a session log section if the skill does project-folder work; an independent audit agent step if the skill produces rendered or quality-sensitive output (used in place of an evals folder); a writing-voice prerequisite if the skill produces prose in your voice (if you have no voice layer yet, create one first; see writing-voice-guide); a report-only contract if the skill is advisory. If the skill creates, populates, or writes rules into a project folder, apply references/house-style.md section 9 as well.
• Recommended, not mandatory: offer a ## Gotchas section (at least two real symptom, cause, and fix entries) and a small evals/evals.json. Both are good practice; recommend them, do not force them.

Phase 3: Build

Generate the folder following references/house-style.md. Use the prompt-writing step for the description and any agent prompts. Keep SKILL.md a routing layer (steps and pointers); push dense rules, templates, and domain knowledge into references/, one level deep. Ship the scripts from the inventory, started from scripts/archetypes/. Copy assets/skill-template.md as the SKILL.md skeleton.

Phase 4: Validate

Two steps:

1. Run the preflight script and fix every hard fail:

   python3 ~/.claude/skills/skill-build/scripts/preflight.py ~/.claude/skills/<name>

   It hard-fails on the invariants a skill needs to load and be read: SKILL.md present, name matches the directory, a single-line non-folded description at most 1536 characters (the point where the skill listing truncates silently), SKILL.md at most 500 lines, no nested reference chains, and no CHANGELOG.md in the skill root. It warns (does not fail) on a description over 500 characters, a missing negative trigger, a missing when_to_use, a triggers: or category: key Claude Code does not read, a body over 150 lines, a missing ## Gotchas, and a README.md in the skill root. An optional name-prefix warning is off by default; scripts/preflight.py explains how to turn it on.
2. Run the semantic checklist the script cannot judge: read references/preflight-checklist.md and apply it.

Phase 5: Register routing (approval gate)

A new skill is not done until it is discoverable. Most skills need nothing here, because the description is the routing signal and reaches every session on its own. Editing ~/.claude/CLAUDE.md changes always-loaded global context, so any edit to it is a hard approval gate, not an automatic step.

1. If you keep a routing table in your CLAUDE.md, draft a row only where the description cannot carry the routing: a command word you type, a tie-break with a neighboring skill, or a default.
2. If you keep a skill index, add the new skill the way that index is maintained. If the index is generated from frontmatter, set the field it reads and regenerate it; never hand-edit a generated index, because the next regeneration wipes the row. references/house-style.md section 7 has the checklist.
3. Present every diff verbatim and wait for explicit approval. On approval, apply them.
4. Consider a headless variant only if the skill is meant to run unattended in batch.

Phase 6: Test and hand off

Give the user a cold-start test plan: a fresh session with the skill installed runs it on two or three real tasks while the user watches for files read in the wrong order, missed references, or an overused section. Then offer the handoff: skill-audit to review it against recent friction once it has been used, and your publishing step if you share an anonymized version.

Gotchas

• Symptom: the new skill never fires; the user has to name it by hand. Cause: a timid or vague description, the default undertriggering failure. Fix: rewrite the description to name the artifact in the outcome language a request would use. Widen it by naming what it covers, not by lengthening it, and add the negative triggers that keep the widening from stealing a neighboring skill's requests; in a large suite, a wrong fire costs what a missed fire costs.
• Symptom: the description renders on two lines and the skill behaves erratically. Cause: a multi-line or YAML-folded description; Claude reads only the first line. Fix: keep description: a single flat line, never description: >. The preflight script hard-fails this.
• Symptom: trigger phrases were written down but the skill still does not fire on them. Cause: they were put in a triggers: key, which Claude Code never reads. Fix: move every phrase that must route into description. The preflight script warns on a triggers: key.
• Symptom: the built skill works but does not look like the rest of your suite (no session log, no audit agent, no voice prerequisite). Cause: the generic template was followed instead of the house style. Fix: apply the conditional sections in references/house-style.md for the skill's type before shipping.
• Symptom: a near-duplicate of an existing skill ships and the two drift apart. Cause: Phase 0 was skipped. Fix: always survey the suite first; recommend extending the existing skill when one overlaps.

Rules

• Never write skill files before the Phase 2 design is approved (the new skill's files; filling in references/house-style.md in Phase 0 is exempt).
• Never auto-edit ~/.claude/CLAUDE.md; present the diff and wait (Phase 5). Never hand-edit a generated skill index; set the field it reads and regenerate.
• Never put domain knowledge, style guides, or long examples in SKILL.md; use reference files one level deep.
• Default to inheriting the session model; pin model/effort on the new skill only when the user asks.
• Ship a script for every execute step; argue the case in one sentence if a step that looks mechanical is genuinely reason-not-execute.
• Carry the CC BY 4.0 attribution into any skill adapted from third-party material, and wire your writing-voice prerequisite into any skill that produces prose in your voice.
• Deletion is a valid outcome: if a workflow is retired, remove its skill rather than leave it to misroute.
• Never put a real client organization or a real private person into a skill, anywhere, including fixtures, test data, code comments, and a rule's stated provenance. Examples and fixtures are fictitious. Public companies that are the subject of a teaching case, and published authors cited as sources, are not covered by this and stay; the rule is about paid engagements and people who are not public figures. The way this gets broken is rarely by typing a client name on purpose. It happens by building a fixture from a real delivered artifact, or by justifying a rule with the incident that produced it and naming the engagement. Both are natural, and both embed the client in the skill.