Every Skill, One Page

What a skill is — and what it isn't

A skill is a named contract: a domain, a description, and a body of standing instructions that Claude loads when triggered. It is not a function call. It is not a script. It is the way you tell Claude "this kind of work has an owner — and here's what that owner knows."

Three things make a skill different from "just code":

• It's descriptive, not imperative. The body is mostly prose explaining what to do, why, and what's load-bearing — not a step-by-step program.
• It's triggered by language. Claude reads the user's prompt, scans every skill's description, and decides which to activate.
• It owns a domain. Other skills defer to it for that domain. The writer doesn't ask doc-pdf for permission to write a 1-pager — but it also doesn't try to convert a deck to PDF on its own.

Heuristic. If something has a single deterministic command, write a Bash one-liner. If something has a clear API, call the API directly. A skill is what you reach for when the work needs judgment applied across a recurring set of situations.

The shape of a SKILL.md

Every skill is one Markdown file at skills/<name>/SKILL.md. Two parts matter — the frontmatter at the top and the body below it.

---
name: writer
description: "ALWAYS ACTIVE. Owns every client-facing deliverable: 1-pagers,
  CIMs, buyer lists, pitch decks. Triggers on: 'write a', 'draft a',
  '1-pager', 'teaser', 'CIM', 'pitch deck', 'follow-up', 'polish this'."
---

## Maxswarm Phase Contract
...

# The Writer — Document & Copy Gatekeeper
...

Frontmatter is the only thing Claude scans when deciding which skills to load. Treat it like a search ad: list the literal phrases the user is likely to say, and the domain the skill owns.

The body is the operating manual. Use H2 sections that announce themselves to a reader and to Claude on activation: ## When This Triggers, ## Source of Truth Files, ## Output Format, ## Maxswarm Phase Contract, ## Handoffs. Structure here is what gets you consistent execution across runs.

How skills get triggered

Three trigger paths, in order of authority:

1. Explicit slash. The user types /writer or /maxswarm. The skill activates immediately. Use this when you know exactly which capability you want.
2. Description match. Claude scans every skill's description against the prompt and activates the ones that match. This is why descriptions matter more than bodies for discoverability — a perfectly written body inside a vague description never fires.
3. ALWAYS ACTIVE. Flagged skills load on every turn. Reserve this for cross-cutting concerns — output formatting, communication style, deal-awareness — never for niche capabilities. Every always-active skill is a tax on every prompt.

Two skills with overlapping descriptions both activate. That's not always a bug — but it is always a design choice. If you don't want them both firing, tighten the description on the loser.

How to call a skill, and what to do once it's running

Once a skill is active, three rules:

• Don't fight it. If writer owns the deliverable, don't open a parallel writing process. The skill exists because it has the source of truth on voice, templates, registry. Ask the skill, don't bypass it.
• Hand off context up front. Skills can't read your mind. Tell it the deal, the audience, the deadline, the constraint. The first message you send a skill is the most expensive — make it count.
• Read its log. Skills that ship logs (write_log.jsonl, process_runs.json, the swarm notebooks) keep institutional memory. Check before re-doing work the system already did.

How to create a skill that earns its keep

The pattern that works:

1. Check the catalog first. Use the search above. Most "I need a new skill" instincts turn out to be "I forgot we already had one." If the existing skill is wrong, fix its description before forking.
2. Name it after the role, not the action. writer, not write-document. architect, not make-decisions. Roles are durable; verbs are not.
3. Write the description like an ad. List specific phrases the user will actually say. Name the domain. Be explicit about ALWAYS ACTIVE if it is.
4. Body sections in this order: purpose → triggers → source of truth files → operating procedure → output format → handoffs → known failure modes.
5. Ship before polishing. A skill at 70% used is worth more than one at 100% on the shelf. Real runs reveal what the body should say — and almost everything you guessed before shipping was wrong.
6. Register it. Add to inventory/skills.md, regenerate the catalog JSON, link it from related skills' bodies so they cross-reference.
7. Iterate from real runs. When a swarm notebook entry references a skill by name, that's a signal it's earning its keep. Skills that never get cited fade.

There's a skill-creator skill for exactly this workflow. It walks you through draft → eval → benchmark → optimize. Use it. The whole point of the catalog is that the catalog uses itself.

How skills nest, chain, and stack

Three patterns, in order of how often you'll use them:

1. Skill calling skill (by reference). cold-call-workflow ends with "once the call wraps, hand the transcript to transcript-extractor." That's nesting via reference — no orchestration layer, just a clean handoff named in the body. Most composition is this kind.

2. Swarms (orchestrated composition). maxswarm is itself a skill that orchestrates 11 others into one run. The orchestrator enforces a Phase Contract; each agent obeys it. This is how you get team intelligence out of single-agent skills. Use a swarm when one agent's blind spot is another agent's strength — and when the decision is too important to trust to a single perspective.

3. Meta-skills (gatekeepers). Some skills don't do the work — they make sure the right downstream skill loads first. deal-awareness-protocol activates before any deal-touching prompt and enforces "no deal-specific work without the deal-manager skill loaded." The meta-skill owns the routing, not the output.

The composition rule: a skill never silently rewrites another skill's output. If writer wrote it, writer owns it. tech-translator may polish it; it doesn't replace it. Audit-quality may flag it; it doesn't rewrite it. This is the rule that keeps the system from collapsing into one big tangled prompt.

When to reach for what

This is the call you make every day. Match the situation to the right tool:

Two questions to ask before anything gets written:

1. Does this already exist? Catalog above + inventory/skills.md.
2. Is this a skill, a script, or a one-time turn? Use the table above.

Most "I need to build something" moments end at question 1. The second-most common end at question 2 — with the answer being "this is a script, not a skill." The skill catalog is meant to grow slowly.

Why the catalog has eight buckets

The buckets aren't decoration. They tell you what layer of the system the skill lives at, and that layer determines who calls it and who it calls.

If a new skill doesn't fit any of these, the system level changed — talk to architect before forcing it into the closest bucket. New buckets are rare, but they happen, and they're worth a moment of design before you commit.

Anti-patterns we've actually hit

• The Greedy Description. A description that triggers on too many phrases swallows other skills' airtime. Fix it by listing the minimal set of trigger phrases — quality over coverage.
• The Stale Body. A SKILL.md that hasn't been updated in 8 weeks but still fires daily. Run git blame against it before you trust the body — half the rules may already be wrong.
• The Phantom Owner. A skill that claims to own a domain but never gets called. Either the description is wrong (most common) or the domain is being handled somewhere else (also common). Either way, audit before adding to it.
• The Bypass. Calling the underlying API directly when a skill exists for it. The skill knows things the API doesn't — templates, defaults, history, what the last 5 runs learned. Bypass once and you've broken the institutional memory.
• The Snowflake. A skill so specific it triggers once a quarter. If it doesn't fire, it doesn't learn — and a one-off script would have been cheaper to build, faster to read, and easier to delete.
• The Always-Active Slop. Marking a skill ALWAYS ACTIVE because it "should always run." Every always-active skill costs every other skill some attention budget. Justify it like a budget line.

The repair pattern is always the same: read 3 recent runs that should have used the skill, observe what it actually owned vs. what its description claimed, and rewrite the description first — body second.

Five SKILL.md files to read this week

If you read nothing else, read these. They're load-bearing for everything else in the catalog:

1. architect — the source of truth for what exists. Every infrastructure question routes through it.
2. writer — voice, brand, deliverable templates. Every client-facing artifact runs through it.
3. maxswarm — the swarm contract. Read before your first run, then again after.
4. quarterback — daily orchestration. The deal flow runs on it.
5. output-skill — how Claude communicates with Ewing. The reason responses look the way they look.

After those five, browse the catalog by category for whatever you're about to do. Read the skill before you call it the first time — it'll save you the dance of figuring out what it owns.