forge

name	forge
description	Designs Claude Code harness artifacts. One triage ladder picks the right surface (skill, hook, path-scoped rule, CLAUDE.md or AGENTS.md entry, workflow script, subagent, MCP); the stance holds the bar every artifact must clear (a gap between the model's default and what the owner wants — a new idea or source worth operationalizing, a miscommunication to prevent, or an observed failure — plus a nameable attention shift); per-surface mechanics live in references. Use for creating, reviewing, or refactoring any of these, for distilling articles or docs into one, for skills that under- or over-trigger, hooks that don't fire or fire too often, bloated CLAUDE.mds, and for deciding which surface a behavior belongs on. Triggers on any work on a skill, hook, rule, CLAUDE.md, AGENTS.md, or workflow orchestration script, including debugging triggering or firing semantics and packaging a /command or plugin.
paths	["**/.claude/skills/**","**/.claude/hooks/**","**/.claude/rules/**","**/.claude/agents/**","**/.claude/workflows/**","**/.claude/settings.json","**/.claude/settings.local.json","**/CLAUDE.md","**/CLAUDE.local.md","**/AGENTS.md"]

forge

A skill transplants expertise. Its only measure is the work it makes the agent produce — judged at the output, against the standard of the best practitioner alive in the domain. Surfaces, triggering, token cost, lifecycle — everything else in this file — is plumbing that gets that expertise in front of the agent at the right moment. A flawlessly-packaged artifact encoding mediocre expertise is worthless; a roughly-packaged one encoding genuine expertise is valuable. Optimize in that order, always.

So the first question is never what surface? or what will this cost? — it is what does world-class output in this domain actually look like, and what must I put in front of the agent to reach it? If you can't describe exemplary output — the non-obvious moves, the trade-offs an expert weighs, the traps between game-changing and merely competent — you are not yet qualified to write the artifact. Acquire the standard first: read the current state of the practice, fetch primary sources, find or write an exemplar. Expertise you don't hold cannot be transplanted.

Forge is a working draft, not the authority — the output is. These rules are conveniences that have paid off before; when another approach produces better work (a rigorous, eval-driven skill-creator can, and has), it is right and forge is wrong. Defer to what produces the best output, learn from it, and cut any rule here that doesn't serve output quality. Forge improves by absorbing what beats it.

An artifact earns its existence on three bars, heaviest first:

1. It encodes expertise the model lacks — it beats the default. A frontier model's unaided output is competent across most domains; restating that competence is dead weight at recurring cost. The artifact earns its place only with the delta a senior practitioner adds and the model would not produce unprompted: the non-obvious move, the trade-off and its reasoning, the failure mode, the verified current specific. This bar decides whether the work is worth doing at all — and it is the one most easily faked with confident-sounding floor, so verify the delta as an action, not an intention: for anything fast-moving or version-specific, fetch the canonical source and cite it; recall ships deprecated specifics in a confident tone. The delta has only a few durable sources — the owner's taste and intent made operational, local truths of a repo or team the model cannot know, verified post-cutoff currency, and failures actually observed. An artifact drawing on none of these is competing with the model's own training data and will be absorbed within a release or two; write it expecting to delete it.
2. It is earned. A gap between the model's default and what you actually want: a raw idea or source worth operationalizing (a spec, a researched methodology, hard-won domain knowledge, not a hot take), a miscommunication worth preventing (the output missed your intent, or the same correction landed three times — the harvest skill mines transcripts for exactly these), or a failure you observed (the agent did the wrong thing). The everyday means are the idea and the miscommunication; failure is one of them, not the main one. If none, stop: the cheapest artifact is the one not written.
3. It shifts attention, nameably. What should the agent attend to that it doesn't — or stop attending to? From what, to what, in one sentence. Name it, or you have material, not yet a design.

The test of kind is additive vs transformative — and it is about the work, not the token bill. An additive artifact lists steps and changes nothing foreground; the agent still attends to mechanics. A transformative one pushes mechanics into the background and elevates the real question (should we ship?, is this result trustworthy?, is this even the right problem?) — it changes what the agent can think about. Aim transformative. Cost discipline — lean bodies, tight descriptions, the right surface — is real and lives below; it is how you afford the expertise, never what you trade it for.

Every non-trivial artifact carries a one-line pin — <!-- Earned against: <model>, <YYYY-MM-DD>, <CC version> --> — recording the earning event only; rationale, sunset triggers, re-test verdicts, and revision notes go to CHANGELOG.md, never into the artifact. Appended re-tested/revised clauses are history wearing the pin's format — they pass as pin material because they too are models and dates, and that is exactly how pins re-bloat. Artifacts never reference the conversation that produced them. A pinned model can be withdrawn, not just superseded; re-pin to the period's durable default so the trigger stays runnable.

Scope: build in-repo, never reach into machine scope. Every artifact forge writes lands inside the current repository. Machine-scope surfaces — anything under ~/.claude/, user or enterprise settings.json, global enabledPlugins/skillOverrides, user-scope hooks — are read for context but never written, staged, or offered for apply, even during an audit and even when the fix is one obvious line. Installing or enabling an artifact machine-wide is the owner's action to take; report it, don't perform it. A hard boundary, not a default to weigh.

Triage — pick the surface

Run the ladder in order; first match wins. A refined harness trends toward fewer artifacts, each doing what only it can.

The behavior is...	Surface
A guarantee that must hold every time ("never edit .env", "lint after every edit")	Hook — fires deterministically; a skill is interpreted and can be talked out of. references/hooks.md
Just "this tool — or this tool-call shape — can't be used here", no logic needed	permissions.deny in settings — matches command content and parameters (Bash(rm *), Agent(model:opus)), so a block that looks conditional often needs no hook
Reaching a system the harness can't see (database, tracker, private API)	MCP server — a skill can teach using it well; it can't replace the connection
A side investigation that would flood the main context	Subagent, or a skill with context: fork that runs as one
A fact every session should hold ("we use pnpm")	CLAUDE.md — references/always-on.md
A convention that only matters for some files	Path-scoped rule — or a path-scoped skill if it must also be manually invocable. references/always-on.md
Deterministic orchestration of many agents — large fan-out, classify-then-route, branching, or a run that must reproduce	Workflow script — see Workflows below. A single delegated task that itself splits (reviewer → a verifier per finding) may only need a nested subagent
None of the above, reusable across sessions	Skill — references/skills.md

Two orthogonal notes:

• When it fires is not where it lives. Work that runs on a schedule or fires on an event with no human in the session is a Routine (/schedule) running the artifact; an artifact can't schedule itself.
• Surfaces combine. A skill can bundle a hook scoped to its own lifetime (frontmatter hooks:) — guidance and guarantee in one artifact. An MCP connection plus a skill that teaches its good use is another common pair.

When triage moves the work somewhere other than what was asked for, name the redirect in one line and confirm before building ("this looks like a rule, not a skill, because X — proceed?"). Announce, confirm, carry through; never silently switch.

Skills

The two failure modes are a bad subject (restates the model's defaults) and bad anatomy (never triggers, fires wrong, dies at compaction). Subject first; anatomy in its service.

• Don't reinvent. Search the ecosystem before drafting (npx skills find <query>, skills.sh, or the find-skills skill if present), then read the strongest candidate and judge it yourself — install counts are a prior, not a verdict. Use as-is, fork and sharpen, or build new, deliberately.
• Distill, don't transcribe. From a source, SKILL.md is the table of contents and references/<topic>.md the chapters opened on demand. Cut what the model already knows; keep what is specific to this source and this codebase — and above all the expert's judgment: what they'd reach for and why, the call they'd make at the fork, the trap they'd sidestep, not a procedure any competent generalist could already follow.
• Blast radius of one skill. Ingesting material into a skill never adds content or back-references to a neighboring skill. A skill does its job alone; at most it carries a soft, optional, one-directional pointer ("if x is available, use it alongside this"). Coupling two skills so each leans on the other breaks both the moment one is missing.
• Craft. Match freedom to fragility (prose for judgment-laden work, exact steps only for fragile procedures). Explain the why — the model generalizes from a reason where it can't from a bare MUST. One worked example conveys altitude more cheaply than a paragraph, and costs ~3× a rule, so use one. One default with an escape hatch, one term per concept, and cut any line the model would do without — the context window is a public good.
• Encode the discovery, not the facts. When truth exists at runtime — a token file, a config, a schema, a vendor CLI's info command, a vendor's llms.txt — teach the skill to read it first instead of freezing today's values ("read globals.css for the theme before writing classNames"). Frozen facts are the fastest-rotting content a skill can carry, and vendor facts (package names, attribute idioms, config-field values, version-keyed claims) rot worst: they invert from stale to actively wrong — a skill greps for a renamed package and silently concludes the stack is absent, or teaches state selectors that match nothing at runtime. The discovery survives every drift the snapshot dies in. Where a bare vendor fact must appear anyway (an example, a trap note), it is a re-test liability the probe file should cover.
• The description is the only trigger surface. Describe the class of requests, then anchor it — matching is semantic, and an enumerated phrase list reads as exhaustive, so the unlisted case looks out of scope. Job + scope + strongest distinct triggers lands at 600–900 chars; the 1,536-char cap is a truncation guard, not a target.
• The body is recurring cost. Standing instructions, not one-time steps; once invoked it stays in context unread-from-disk until compaction.
• A rule the model read and still violated needs its trigger moved from concept to shape. When the same correction recurs in sessions where the skill was demonstrably loaded, the deficit is wording and salience, not triggering — more triggers or a louder principle change nothing. Rewrite the rule as its concrete failure shapes: name the exact wrong artifacts the model produces (the parallel component beside the source it should have edited, the bracket value that was already on the scale) and lead the skill with the highest-recurrence shape.
• The verdict is the output against an expert bar — not whether it fired. Establish the exemplar first: what a senior practitioner's output on a real task in this domain looks like. That is the standard you grade against — per Anthropic's eval guidance, a good task is one where two domain experts would independently reach the same verdict, proven solvable by a reference solution before you grade anything. Run the real task in a fresh session without the skill — the gap from exemplar to that output is the spec — then with it, and judge whether the output closed the gap, reading the transcript not just the result ("didn't trigger" and "triggered but didn't steer" look identical from outside). Three opt-in harnesses back this (real tokens — confirm before firing): evals/trigger-eval.js (text proxy for a description's discriminating power) and evals/invocation-eval.js (live claude -p ground truth for whether it fires; run with node, not Workflow) settle the secondary fire/no-fire question; evals/depth-eval.js, a blind panel, settles the one that decides worth — does the body produce expert work. When the depth judge is unreliable because the model is weak in-domain, calibrate it against your exemplar or a human expert; never retreat to craft/anatomy as "the trustworthy signal." Triggering and anatomy are pass/fail hygiene; depth is the grade. And calibrate the bar to the skill's kind: expertise grades against the domain's best practitioner; taste — a voice, an aesthetic — grades against its owner, where a generic judge panel is a category error. Named tells give taste a mechanical floor; the owner's ear stays the ceiling.

Mechanics — listing budgets, frontmatter fields, compaction rules, kinds, naming collisions, YAML traps: references/skills.md.

Hooks

A skill redirects attention; a hook removes the concern from the model's reach entirely. The strongest surface, with the narrowest fit.

• Earned by an incident, not a worry. "Might go wrong" is CLAUDE.md territory; a hook answers what already went wrong.
• Strictness is earned by precision, not importance. Block / warn / log is a spectrum, and after the skill/hook confusion, over-blocking is the most common design mistake: a blocking hook with false positives trains the user to disable it, which costs the guarantee and their trust in the hooks layer. Most hooks that feel like blocks want to warn.
• Exit 2 blocks; nothing else does — not exit 1. Stderr on exit 2 is fed to the model: write it to teach (the why, and the alternative), not to deny. A flat "rejected" gets retried or argued with; a reasoned block gets compliance.
• Success silent, failure verbose. A hook that prints on every pass pollutes every downstream turn.
• Hooks gate tool inputs, not returned prose. SubagentStop carries no result text and PostToolUse truncates large results — don't reach for a hook to police what a fork returned; enforce that in the dispatch contract instead.

Events, matchers, handler types, exit and JSON semantics, placement: references/hooks.md.

CLAUDE.md and rules

The always-on surfaces: every line is paid for every turn (CLAUDE.md) or whenever the glob matches (rules).

• Never current state. The code says what the code is; restating it pays tokens to go stale on the next commit. What survives a refactor: intent, spirit, durable harness traps, pointers, framing caveats.
• Verify every fact-claim against its source (filesystem, configs, scripts, settings) before writing or keeping it. Intent voice does not protect against a wrong mechanism inside it.
• The ceilings are empirical. Past ~14 top-level rules, compliance drops sharply; examples cost ~3× a rule and induce overfitting; "be careful" adverbs do roughly nothing. Reasoned rules beat bare directives by a wide margin — give the Why where the rule isn't its own reason.
• A rule is earned by three corrections on the same convention in the same slice, and verified against the slice — if the files don't already follow the convention, the rule is wishful and will contradict the code. Write condition-shaped bullets, not principles ("when X genuinely needs Y, do Z" beats "Y before Z"); phrase capability-agnostically; add a respect-the-framework preamble where the rule overlaps an opinionated framework's territory.

Filters, the goes-elsewhere table, voice and the Why pattern, AGENTS.md-primary mode, glob discipline: references/always-on.md.

Workflows

The Workflow tool's own in-session description is the authoritative, current contract for the API and the orchestration patterns (pipeline vs parallel, schemas, budget scaling, adversarial verification) — author from it, not from memory. What it doesn't cover:

• The surface line. A handful of parallel reads synthesized once is a prose-dispatched skill (/ingest); a single delegated task that itself fans out — a reviewer spawning a verifier per finding — is a nested subagent, where only the top summary returns and there's no runtime opt-in; reach for the workflow runtime when the corpus is large, control flow branches, or the run must reproduce.
• Packaging. The documented reuse path is .claude/workflows/<name>.js as a /command. Shipping workflow files inside a skill folder is blog-asserted only — usable knowingly, not something to depend on.
• Opt-in. Workflows cost real tokens and the runtime requires explicit user opt-in. Design the script; don't fire it unasked.

Authoring footgun — the loader trigger sequences

The skill loader pre-processes every file in a skill directory at load time, scanning for two literal byte sequences and replacing them with command output — ignoring markdown context (inline code, fences, and block quotes offer no protection):

• an exclamation mark immediately followed by a backtick;
• three backticks immediately followed by an exclamation mark.

If either appears anywhere in the tree, the loader runs what follows as a shell command; an off-allowlist or malformed command fails the whole skill to load. Any file that must describe injection (a tutorial, this file) does it in words, uses an [INJECT: <command>] placeholder in example bodies, and points at https://code.claude.com/docs/en/skills for a rendered example. After writing, grep the tree (patterns backslash-escaped so this file stays load-safe):

grep -rn -e '!\`' -e '\`\`\`!' .claude/skills/<your-skill>/

Zero matches means it will load.

Ship, then let it die well

• bin/preship-check before commit (the kitchen's PreToolUse gate runs it on git commit anyway).
• Pin the artifact; log rationale and sunset trigger in CHANGELOG.md. A stack-keyed sunset trigger includes vendor default flips, package renames, and idiom changes, not just version majors — a stack can break a skill without ever incrementing one.
• Ship the death test with the skill. Expertise and taste skills carry evals/probes.md — the earning gap as runnable fixtures: verbatim prompt, the unaided default it diverges from, pass criterion, per-model baseline verdicts. Deletion needs all probes passing unaided; models absorb the easy case first, and a single-probe pass once nearly killed a still-earning skill. Process and workflow skills are exempt — their value is the owner wanting the procedure, which a release can't absorb. Mechanics: references/skills.md.
• On each major model release (or newly adopted working model), replay each artifact's probe file — prose reconstruction only where none exists yet. No longer reproduces → delete; shifted → rewrite against the new gap rather than layering on the old. And record the keeps: when a skill-withheld trial reproduces the gap, that's a dated KEPT in the baseline table and the changelog — without positive evidence, every audit can only ever argue for removal.
• The trajectory of a refined harness is fewer artifacts, not more.

See also

• references/skills.md — skill mechanics: listing, frontmatter, lifecycle, kinds, naming, eval.
• references/hooks.md — hook mechanics: events, matchers, handlers, exit codes, placement.
• references/always-on.md — CLAUDE.md, AGENTS.md, and rule mechanics.
• Canonical docs (trust over this skill when details move): code.claude.com/docs/en/skills, /docs/en/hooks, /docs/en/memory, /docs/en/workflows.