Engineering a System of Skills · Methodology Guide

What this guide is — and isn't

This is not a guide to writing a good single skill — progressive disclosure, description fields, degrees of freedom: Anthropic's official best-practices covers that thoroughly.

This guide addresses the layer above: how a collection of skills and multiple agents forms a coherent system. Think of each skill as a module, its trigger as an interface, its output as a contract, and the core prompt as the kernel. When modules multiply and agents start orchestrating each other, piece-level correctness no longer implies system-level correctness. That's when you need systems engineering: coverage, orthogonality, interface contracts, regression, end-to-end verification. The seven principles below handle static coherence; the evaluation loop handles empirical verification.

Running Example

You're building a coding agent: write-tests, review-diff, debug, commit, refactor — with a planner skill orchestrating them via workflow. Each skill looks fine in isolation. Together, things break. The six principles below use this system to show exactly how and why.

Core Principles

Seven Principles

These seven aren't independent rules — they're an interlocking system. Each answers one fundamental design question.

Where Does It Live · Persistence Gradient

Always-on → On-demand → Reference material

Where knowledge lives is determined by frequency of use, not importance. What must be present every turn goes in the core prompt (Kernel); what's only needed for a specific role or scenario goes in a skill; what's only needed for certain sub-tasks within a skill goes in reference/ or scripts/.

The test is not "how important is this?" but "how often is this needed?" A very important rule that's only needed in specific scenarios doesn't belong in the prompt — it belongs in a skill. Wrong layer = either burning context every turn or creating knowledge that's unreachable when needed.

❌ Typical mistake: "Must run tests before committing" and "never commit secrets" — constitutional rules written into the commit skill. But refactor and review-diff subagents never see commit, so they skip tests and commit dirty code.
✓ Fix: Constitutional rules belong in Kernel. The commit skill only covers the mechanics of how to commit.

Overall Quality · System Coherence

prompt + skills + scripts form one unified intent

Good parts don't guarantee a good system. Every layer — core prompt, each skill, each reference file, each script — must serve the same north star and form a self-consistent reasoning chain. Any piece whose intent contradicts the system will produce unpredictable behavior at its boundary.

Test: pick any skill in the system. Can you find one sentence in it that traces its existence back to a specific principle in the core prompt? If not → the skill is floating. Either add the missing Kernel anchor, or delete the skill.

When to Build · Regime Gating

User × Scenario determines whether to design a skill

A skill's identity is defined by two dimensions: who uses it (agent/role) and in what scenario (trigger/scene). If either dimension changes → consider an independent skill. If neither changes → merge, demote to reference, or delete. In multi-agent systems: one planner skill handles orchestration; each agent has its own independent skill — never share a SKILL.md.

Most common mistake: building a skill because the content "feels related." The right question: "Is this (user × scenario) combination fundamentally different from existing skills?" If not → don't build.

❌ Typical mistake: You add a review-security skill because "security review feels related to code review." Now review-diff and review-security triggers overlap — the same diff fires both, the agent receives two contradictory authorities.
✓ Fix: Security review is a mode of review-diff, not a separate regime. Merge it or demote to a reference file.

Completeness · Orthogonal Coverage

No overlap, no gaps, explicit boundaries

For a given agent, all its skills should satisfy: any system state triggers exactly one skill — no more, no less. Two skills triggering on the same state → conflict, fix the trigger. Some state has no skill to handle it → gap, fill it or explicitly record as "intentionally uncovered." Every skill ends with Not for X → [[sibling]] to declare its boundary.

Note: skills are inherently composable — multiple can be mounted at runtime. "Exactly one" is a disambiguation design ideal — preventing the wrong skill from firing or a needed skill from staying silent — not a hard runtime law. Orthogonality makes selection deterministic, not composition forbidden.

❌ Typical mistake: You have write-tests and run-tests, but no skill handles "CI is red and I don't know why." The agent improvises every time — different approach each run, impossible to predict or debug.
✓ Fix: Enumerate all real scenarios. Find uncovered cells — explicitly fill or record as "intentionally uncovered."

Precise Triggers + Intent First · Flow

Trigger is a precise entry point; SKILL.md leads with intent

The trigger (description field) is an observable, definite condition — not a descriptive label. It must support a yes/no decision for any concrete system state. Inside the skill: lead with "why this role exists / what good work looks like," then methodology. This creates flow: intent establishes direction, methodology emerges naturally within that direction — rather than wielding a tool looking for problems.

A skill that leads with methodology traps the agent in mechanical execution. A skill that leads with intent lets the agent act purposefully — making reasonable judgments even when the methodology doesn't have explicit coverage. Trust the model's intelligence; constrain less, direct more.

Intent is direction; pressure is fuel. "Intent first + trust the model" is not enough — a skill owns only method, while the agent's posture and responsibility must live independently of any skill, present every turn (it belongs in the Kernel). Without it, the agent will use a skill's craft to wave real defects through elegantly. Four things to max out responsibility:

① Make the cost of failure concrete, not an abstract warning. One specific scene: "paged at 03:14 → the data dump is on a forum nobody can remove → the lawyer and regulator are on the phone." The bill arrives in production, not in the review transcript.
② You are the defendant in a post-mortem that hasn't happened yet. Your name is in the git blame and the review log. You sign off on what you do not flag — silence on a plausible defect is signing off on it.
③ Ban the self-soothing phrases. These are not seasoned judgment; they are the exact thought that preceded every shipped defect this industry has post-mortemed. Catch yourself thinking one, and re-examine the line you were about to wave through:

❌ Banned: "probably fine" · "looks ok at a glance" · "the tests would catch it" · "the caller would never pass that" · "this is just a refactor" · "the existing code already does this elsewhere" · "the team probably already knows" · "the validator will catch it" · "leave it for the next pass" · "the diff is too small for a serious bug"
✓ Don't lower severity to make a finding comfortable: a confidence=low + severity=critical finding is a valid and required output. Thin evidence means lower the confidence and flag the false-positive risk — but do not lower the severity to hide the candidate. Lowering severity to bury a finding is the real failure of this role.

→ Deep read: skill/reference/responsibility.md (the full posture system prompt, including the three-state accountability model for skipped lenses). A skill decides how to audit a category; that document decides whether to audit it — the latter is not governed by a skill body.

Skill Size · Granularity Discipline

One skill clearly says one thing

Granularity should match the regime it serves. Too coarse: one skill tries to cover everything, trigger becomes vague, content conflicts → split by regime. Too thin: content can't sustain an independent regime → merge into parent skill or demote to reference file. Right granularity: reading the description tells you clearly "when to use this"; reading SKILL.md tells the agent "how to act in this regime." Measure by density, not line count — substantive, tight, and clear is the standard.

Test: show this skill's description to someone unfamiliar with the system. Can they judge "does this situation call for this skill?" If they need a lot of context first → either the trigger is imprecise or the skill is too coarse.

The Skill Checks Itself · Self-Contained Verification

An executable self-check ships with every skill

A skill that cannot check itself ships silent failures. Every skill carries an executable self-check — a script, fixture, or output invariant — probing its own trigger precondition, output contract, and evidence trail; it runs with the system evaluation loop and the CI gate. Prose self-assessment does not count: eval work shows plain-text claims are exactly where automated verification breaks down, and most real defects live at the boundary between declared intent and implementation — the self-check is the tripwire parked on that boundary, firing on every run.

Keep the check thin — one test file or one verification step, never an essay (aligns with Granularity Discipline). And be honest about the limit: a skill that genuinely cannot be mechanically probed must declare that in its "Not for" boundary, so the absence of a check is a recorded decision, not an oversight.

❌ Typical failure: a SKILL.md that ends with "always verify your output" — a prose promise no gate can execute. Three weeks later the skill silently no-ops and nobody notices, because the eval loop only asked "does the piece exist and trigger?", never "is the piece still true?"
✓ Fix: ship scripts/selfcheck.py (or a fixture + expected output) next to SKILL.md and wire it into the eval loop; a red self-check blocks the change at the gate — not at 02:00 in production.

Principle 1 — Deep Dive · Three Buckets

Where Does Each Piece of Knowledge Belong?

Layer by frequency of use, not importance. Important knowledge that's only needed on demand shouldn't live in the prompt.

Kernel / Core Prompt

Always present

This content is in context regardless of which role is active

Put here if:

"Would this need to be present even when the agent is completely idle, with no task running?"

Yes: north star goal · lifecycle state machine · constitutional constraint pointers

No: any role-specific methodology, any scenario-specific rule

Skill

Mounted by regime

Only loaded when the specific role/scenario is active; otherwise not in context

Put here if:

"Is this only needed when a particular role is doing a particular thing?"

Yes: role's reason to exist · standard of good work · wisdom and experience patterns · boundary declarations

No: code · domain facts · deep methodology detail (→ reference)

reference / scripts

Probabilistic access

Read by the agent on encountering specific sub-tasks; not every time

Put here if:

"Given the skill is already active, is this only needed in certain sub-cases?"

reference/: deep methodology, decision trees, routing tables, domain facts
scripts/: executable scripts, tool code, data processing

Higher importance + higher use probability → closer to SKILL.md body

Gradient principle: the reference folder has its own gradient — high-frequency methodology files first, low-frequency last. The whole skill directory is a knowledge funnel from near to far, high-frequency to low.

Principle 3 — Deep Dive · Decision Matrix

User × Scenario: When to Build a New Skill

Operational definition of regime (the central decision predicate of this whole methodology — pin it down before reading the matrix): two candidate skills are the same regime iff they share trigger conditions AND share a standard of good work — otherwise they are different regimes. "Content feels related" does not count; security review and code review share a trigger (the same diff), so they are two modes of one regime, not separate skills.

User ↓ · Scenario →

Scenario changed

Same scenario

User changed

Build 2 independent skills

Both dimensions changed. Write separate skills, each with its own trigger, Kernel anchor, and boundary declaration. Never share SKILL.md.

Build 2 independent skills

Same scenario but different user. Purpose, wisdom, and output differ — sharing SKILL.md gives both agents the wrong context.

Same user

Single skill multi-mode, or sub-skill

Same agent, different scenario. First consider a "phase-aware" single skill (multi-mode); only split to sub-skill if the scenario difference is large enough.

Don't build a new skill

This is supplementary material, not a new regime. Merge into existing skill's reference/ or delete. Building one only creates trigger conflicts.

Multi-agent coordination: one planner skill (orchestration, routing, lifecycle) + N agent sub-skills (each with its own intent and methodology). Planner manages scheduling, not execution. Constitutional rules shared by all agents → Kernel, not duplicated into each sub-skill.

Principle 5 — Deep Dive · SKILL.md Anatomy

SKILL.md Structure: Intent First, Methodology Second

SKILL.md holds text and methodology only. Code → scripts/, decision trees and domain facts → reference/. (Short inline examples are fine.)
Note: Anthropic's official format only requires name and description. Fields marked "required" below are this methodology's conventions for system coherence — not platform hard requirements.

Req

Trigger

description: Use when…

Observable, definite entry condition. Yes/no decision for any concrete state. Must include exclusion: Not for X (→ [[sibling]]). This is a machine-readable contract, not descriptive text.

Req

Kernel anchor

**Kernel anchor:** `id`

Traces to a specific principle in the core prompt. Without this, the skill is floating — reviewers and agents can't verify system coherence.

Req

Intent

## Why This Role Exists

1–3 sentences. Why this role exists. Written as a standard of reasoning quality, not a step list. This is the skill's soul — the agent builds direction from here; then methodology becomes meaningful.

Req

Boundary

## Not for

Explicit exclusions: → not doing X → [[sibling skill]]. This is the interface contract. Without it, orthogonality can't be verified and scope creep is invisible.

Opt

Standard of good work

## What Good Work Looks Like

Describes success from externally observable output quality. Lets the agent self-evaluate without human judgment. Written as "good work should…", not "which steps were completed."

Opt

Wisdom & experience

## Experience & Wisdom

Accumulated patterns and pitfalls. Must be labeled "reference, not constraint." Constitutional invariants (write≠call, freeze-before-results…) get their own section, explicitly labeled as law. Never mix the two.

Opt

Reference table

## Tools & References

Scenario → file path. Text only, no code. Every listed file must exist and have content. Skill is the index; depth lives in reference/. High-frequency first, low-frequency last.

Diagnostics · Six Failure Modes

What Goes Wrong

Make the cost concrete before the taxonomy — the bill arrives in production, not in a design doc. Trigger conflict: two skills both fire on the same turn; at 02:00 the agent picks the wrong one, emits the wrong handoff artifact, and the planner builds a plan on a misread intent — by morning the system has taken hundreds of actions on a false premise; the post-mortem names whoever let the triggers overlap. Coverage gap: Friday 17:00, under release pressure, the agent hits a real state no skill owns; it reaches for "probably fine / leave it for the next pass," improvises an answer, and the deploy ships — Monday the regression suite catches it, but the Friday deploy already reached users; whoever left that matrix cell without an owner signed off on it. Floating skill: a skill that can't be traced to a Kernel principle has nothing tying it down; you delete a sibling's reference, this skill's trigger still points at the deleted file, and three weeks later an audit shows it has been silently no-op'ing on every call since — whoever demoted the reference without checking inbound pointers owns that downtime. You sign off on the gaps and overlaps you don't surface — carry that.

Vague trigger

description can fire in multiple different states; no deterministic judgment possible.

Rewrite trigger as an observable condition. Add exclusion declarations. Every concrete state must yield a clear yes or no.

Trigger conflict

Two skills can both trigger in the same system state — agent faces two authorities.

Draw the state diagram. Ensure every state triggers at most one skill. Add mutual-exclusion declarations in both descriptions.

Two roles sharing one SKILL.md

Two different agents use the same skill file — different intent, wisdom, and output forced to merge.

Split by role. Shared methodology → reference file. Shared rules → Kernel or constitutional skill.

Wrong layer

Cross-role constitutional rules buried in one role's L1 skill (others can't see it). Or role-specific content in Kernel (wasting context every turn).

Needed by all roles → Kernel. Only this role → L1 skill. Only for specific sub-tasks → reference.

Heavy code in SKILL.md

Skill file contains implementation code, decision trees, technical schema. Methodology intent drowned by detail; skill becomes brittle (code changes = skill changes).

Code → scripts/. Decision trees → reference/routing-table.md. Schema → reference/. Short inline examples are fine.

Coverage gap

A real system state exists but no skill owns it. Agent enters this state with no guidance — improvises.

List all meaningful system states. Find an owner for each. Gaps must be filled or explicitly recorded as "intentionally uncovered."

Pre-publish Checklist · Static Coherence

Seven Questions Before You Ship

Does each skill map to a unique (user, scenario) pair?

If two skills serve the same agent with the same trigger conditions, merge them. Same regime = no need for two skills.

Can every skill be traced to a specific principle in the Kernel?

Each skill should complete: "This skill serves Kernel principle [X] because…" Can't complete it → either Kernel is missing the node, or the skill doesn't belong in this system.

Is triggering unambiguous for any system state?

Put all skill descriptions side by side and look for overlaps. Have overlaps → trigger conflict, fix exclusion declarations. Complete state space covered? Have gaps → add a skill or explicitly document.

Is SKILL.md free of heavy code or implementation details?

Scan for code blocks, decision trees, data schema (short examples are fine). Found some → move to scripts/ or reference/. SKILL.md is a methodology document, not an implementation document.

Does every reference file have a skill pointing to it?

Search every SKILL.md for each reference filename. Zero hits = orphan file, agent will never find it. Add to some skill's reference table, or delete.

Are wisdom (reference) and law (inviolable) labeled separately?

Constitutional constraints must be labeled as inviolable. Experience patterns must be labeled "reference, not constraint." Mixed together → agent doesn't know what's flexible and what's a hard line. This guide's own reference items (labeled per this question): "building a skill because content feels related is the most common mistake" is a high-frequency observation, not part of the regime definition; "weaker models surface trigger ambiguity" reverses as models change; "no official eval runner exists" is time-sensitive (skill-creator v2, 2026-03, partially supersedes it) — none of these are laws; re-verify them periodically.

Does each skill's granularity clearly say one thing?

Read the description — can someone unfamiliar with the system judge "does this situation call for this skill?" Needs a lot of context → trigger imprecise or skill too coarse. Content too thin to stand alone → demote to reference file. Standard: substantive, not line count.

Empirical Verification · Beyond Static Design

The Seventh Thing: Evaluate the System, Not Just the Parts

The six principles and seven questions audit static design coherence — it reads right, but it might not run right. Whether the system truly covers the state space, whether triggering is truly deterministic, whether changing one thing breaks another — you only know by running it on real inputs.
Single-skill evaluation asks "does this piece work?" System-level evaluation asks "do all pieces together cover the space, trigger unambiguously, survive changes, and run end-to-end?"

Kill the skill, run it anyway: establish a baseline

To verify a skill is truly useful, remove it from the system first. Run the agent on the same tasks without it. Record where it fails and how. That failure is the baseline — and the justification for the skill's existence. No reproducible failure baseline = no basis for building a skill.

Trigger disambiguation regression: selection must be deterministic

Feed all skill descriptions as detection inputs across boundary and ambiguous scenarios. For each input: which skill actually fired? One state fires two → trigger ambiguity. Should have fired, didn't → trigger failure. Observation recipe: for each test input, require the agent to emit the single skill name it would activate before acting, and record that name as the firing observation — this reconciles "which should fire" (model-graded judge) with "which actually fired in the harness" (runtime selection), with no in-harness hook needed. Lock this detection set as a rerunnable regression suite. Run it on every description change — you'll miss overlaps reading them by hand. This step also tests whether responsibility holds: inject pressure scenarios (time pressure / sunk cost / authority pressure) and watch whether the agent reaches for a banned phrase ("probably fine" / "leave it for the next pass" / "diff is too small") to wave through a skill that should have fired — a trigger that survives pressure is a trigger that's truly deterministic.

Coverage gap detection: no black holes in the state space

Enumerate real combinations across the user × scenario matrix. For each cell: what does the system do with a request that lands here? Cells where no skill takes over are coverage gaps. How (don't enumerate infinitely): reuse step 2's probing technique — collect each skill's declared trigger predicate, probe the overlap boundary for every skill pair, then give each skill one "must fire" and one "must not fire" input. Any input where 0 skills fire = coverage gap; where multiple fire = conflict. Stopping rule: enumeration ends when every matrix cell either has a skill owner or is explicitly recorded as "intentionally uncovered" — the boundary is set by declared triggers, not by an infinite state space. List gaps explicitly — either fill with a skill or record as "intentionally uncovered." This is a regression item, not a one-time check.

Cross-agent output contract tests: verify artifacts, not process

Agents communicate via fixed artifacts (agreed paths, fields, formats) — these are the system's interface contracts. Write tests that only check artifacts: does the upstream output satisfy the structure and fields the downstream declared it needs? Contracts are the rare part that can be hard-asserted; most behavioral evals use natural-language rubrics graded by model.

Change one, test everything: system-wide regression suite

Skills couple through Kernel, shared reference, trigger boundaries, and output contracts — changing one quietly breaks another. Combine baseline, disambiguation, coverage, and contract tests into one regression suite. Run the whole suite after any skill change, not just the changed skill's cases. System-level defects look exactly like "every piece is right, the combination is wrong."

End-to-end + multi-model (Haiku / Sonnet / Opus)

Finally, run the full pipeline: give a real task requiring multiple agents, let the planner orchestrate from start to final output. Assert the whole chain — routing, lifecycle, north star alignment. Run the same scenarios on Haiku / Sonnet / Opus: weaker models amplify ambiguous triggers and imprecise intent. A system that runs reliably on the weakest model is a truly deterministic system.

Provenance note: "Baseline without skill, evaluations are your source of truth, multi-model testing" comes from Anthropic's official best-practices. "No failing test before writing a skill (RED → GREEN → REFACTOR), pressure scenarios to surface rationalization" comes from superpowers' writing-skills. Both address only single-skill evaluation — extending to trigger disambiguation, coverage, cross-agent contracts, system-wide regression, and end-to-end orchestration is this methodology's extrapolation. On the eval-runner landscape (mid-2026): Anthropic's best-practices page still states verbatim that there is "not currently a built-in way to run these evaluations"; however, skill-creator v2 (2026-03) added Create / Eval / Improve / Benchmark modes, whose Eval mode does should_trigger=true/false regression + blind A/B — an official in-skill eval workflow (still a meta-skill, and single-skill only). Extending to system-level regression (trigger disambiguation, coverage, cross-agent contracts, end-to-end) remains this document's extrapolation. Evals mostly use natural-language rubrics graded by model — not strict assertion-style unit tests.

Going Deeper

Design a skill collection as a coherent system

Seven Principles

Where Does Each Piece of Knowledge Belong?

User × Scenario: When to Build a New Skill

SKILL.md Structure: Intent First, Methodology Second

What Goes Wrong

Seven Questions Before You Ship

The Seventh Thing: Evaluate the System, Not Just the Parts

Further Reading