---
name: skill-creation
description: Use when creating a new skill, improving an existing skill, or deciding what a skill should contain and how it should be structured
metadata:
  user-invocable: false
  type: technique
---

# Skill Creation

## What is a skill?

Injected procedural knowledge -- the "how" for agents. The agent brings identity and domain knowledge. The skill brings process and protocol. They never duplicate each other.

## Step 1: Choose the type

Type determines structure. Choose before writing anything.

| Type | Purpose | When it applies |
|------|---------|-----------------|
| **Discipline** | Enforces rules the agent will rationalize around under pressure | command-execution, execution |
| **Technique** | How to think about or approach a class of problem | investigation, approval |
| **Reference** | Lookup tables, classifications, format specifications | security-tiers, fast-queries, git-conventions |
| **Domain** | Project-specific patterns for a technical area | gaia-patterns |
| **Protocol** | System operating contract -- state machines, mandatory formats | agent-protocol |

## Step 2: Apply the type structure

**Discipline:** Iron Law -> Mental Model -> Rules -> Traps -> Anti-patterns. Each trap and anti-pattern names a *principle of failure* -- one row per failure mode, not one row per concrete instance. If three rows are subcases of the same principle, one row that names the principle teaches more than three rows that enumerate.

**Technique:** Overview (core principle + when to use) -> Process (numbered steps) -> Anti-patterns.

**Reference:** Quick-scan table at top -> Examples -> Edge cases / special rules.

**Domain:** Conventions (naming, structure) -> Examples/snippets -> Key rules -> links to reference files.

**Protocol:** State machine / flow -> Mandatory format -> State transitions -> Error handling.

## Step 2.5: Open self-contained

The first sentence states what the skill IS and does, in its own terms. Never open by contrast ("this is NOT X"): that forces the reader to already know X, so the skill stops being self-contained. If you must disambiguate from a sibling skill, do it *after* the self-definition and frame it as a pointer for continuation ("for the universal envelope see agent-protocol"), not as the definition.

Cross-referencing another skill for *flow continuation* (handoff, "see X for the next step") is correct and avoids duplication. Defining your skill *by contrast* with another ("unlike X, this...") is not -- the first keeps you self-contained, the second couples your meaning to a skill the reader may not have loaded.

See `examples.md` for a before/after of each prose failure mode.

## Step 3: Write for judgment, not compliance

A rule without context ("ALWAYS do X") carries almost no weight in the LLM's reasoning -- the model has no reason to prioritize it over competing signals. An explanation with consequences carries enough weight to influence decisions even under pressure. Every line competes for attention; earn each one with reasoning the model can use.

The dual test: for each row in a Traps or Anti-patterns table, ask -- is this a separate principle, or is it the same principle as a row already there? If the latter, fold it in. Specificity competes with itself: five rows that share a principle each carry one-fifth the weight of one row that names the principle, because the model spreads attention across them.

The test: for each rule, ask -- if the agent saw enough examples of this going wrong, would it reach the same conclusion? If yes, you are capturing genuine wisdom. If no, it needs more context.

For detailed guidance on tone by type and connection to the gaia-patterns design philosophy, see `reference.md`.

## Step 4: Write the description field

Triggering conditions only -- describing the process causes the agent to follow the description and skip reading the content. See `agent-creation/SKILL.md` Step 4 for the bad/good example pattern.

## Step 5: Respect the line budget

| Injection method | Budget | Reason |
|-----------------|--------|--------|
| Frontmatter (always loaded) | < 100 lines | Loaded on every agent call |
| On-demand (read from disk) | < 500 lines | Loaded only when explicitly needed |

Size is not the only criterion. The canonical contract/schema that IS the skill's purpose belongs in SKILL.md even when large; `reference.md` holds the *deep mechanics* (internals, walkthroughs, edge cases) that a reader needs only occasionally. Ask "is this the primary thing the skill exists to state?" before "is this big?".

Heavy reference material -> `reference.md` (on-demand). Concrete examples -> `examples.md`. Executable tools -> `scripts/`.

```
skill-name/
├── SKILL.md          <- main content (always loaded)
├── reference.md      <- heavy docs (on-demand)
├── examples.md       <- concrete examples (on-demand)
└── scripts/          <- executable tools
```

## When to create vs update

**Create new skill:** Distinct behavioral concern not covered by existing skills. Domain knowledge inline in an agent that applies to multiple agents.

**Update existing skill:** Agent ignores a rule the skill already defines -> strengthen with traps. Skill is missing a type-appropriate section.

**Put elsewhere:** Project-specific config -> CLAUDE.md or agent inline. Single-agent-only behavior -> keep inline. Knowledge the LLM covers well from training -> not needed.

**When creating a new skill:** Also update `skills/README.md` to add the new skill to the index. Load Skill('readme-writing') to do this correctly.

## Anti-Patterns

- **Description summarizes process** -- agent follows the description and skips reading the skill body.
- **Discipline without traps OR with too many traps** -- agents rationalize around bare rules; agents also dilute their attention across overlapping traps. A trap row earns its place by capturing a failure mode the existing rows do not. If you can describe a new trap by adjusting the wording of an existing trap, the existing row is what needed strengthening, not a new neighbor.
- **Generic without consequence** -- "be careful with commands" teaches nothing because it has no consequence attached. The fix is naming what goes wrong when you violate the rule, not enumerating instances of the rule. A principle with one consequence outweighs five examples without one.
- **Duplicates agent content** -- two sources of truth both become stale; pick one place.
- **Single responsibility violated** -- if a skill covers two distinct behaviors, split it.
- **Opening by negation** -- defining the skill by what it is not ("this is NOT agent-protocol"). The reader must already hold the other concept to parse yours. State what it IS first; disambiguate after.
- **Phantom / unanchored reference** -- naming a field, tag, or module that does not exist by that name in code, OR anchoring to line numbers that drift on every edit. Anchor to symbols (`activate_db_pending_by_prefix`), not line ranges (`approval_grants.py:1679-1955`) -- a symbol survives edits, a line number does not. For Reference skills especially, every named artifact must be verifiable -- cite the file and symbol. Verify before you assert.
- **Inflated prose** -- restates the heading or hedges without adding a decision the reader can act on. If removing the sentence does not change what the agent does, cut it.
