/skill-creation

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

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 1.5: Situate the skill in its flow

With the type chosen, place the skill before you structure it: where it lives in a flow, and what it can affect. Treat these as one gate with two coupled facets -- position is what sets blast radius.

• **Position.** Is the skill *standalone* (a self-contained process run from a clean start), or does it run *mid-flow* -- sometimes after many skills have already executed -- with an upstream that hands it state and a downstream that consumes what it emits?
• **Blast radius.** What does the skill's output touch or trigger? A standalone technique's reach ends at its own result; a mid-flow skill's is amplified, because its output becomes the next step's input.

The consequence is why the gate exists. A mid-flow skill inherits state and assumptions from upstream; write it as though it started clean and it either redoes work already settled or emits what the next step cannot consume -- and because that output is consumed downstream, the break propagates instead of staying local. A wrong position mis-scopes everything the skill's process assumes and produces.

The gate is **conditional on the type from Step 1**, not universal:

• **Protocol** -- load-bearing: position is the substrate, since a protocol cannot sequence its state machine without knowing where in the larger flow it stands, what the prior turn settled, and what the next needs.
• **Technique / Domain** -- relevant only when the skill runs inside a pipeline; skip it for a self-contained one.
• **Reference** -- irrelevant: a lookup table has no position in a flow. Forcing this gate on a pure Reference skill is itself the "generic without consequence" anti-pattern.

When position is load-bearing **and** the flow is not determinable from the context you were given, ask the user where the skill sits before writing -- do not guess; when the context fixes it or the type makes it irrelevant, do not ask.

A unit of work has a past that set it up and a future that consumes it. At the agent-turn level that is `agent-protocol` principle 3, "Ground yourself before acting": what a turn receives is a claim to check, and a procedure it hands on for an object it does not own is an impact, not a step.

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, see `reference.md`.

Step 3.5: Start from the raw source, end at an outside judge

A skill whose process produces an artifact -- code, a document, a plan, a