Building AI Skills

Short answer: A skill is a named, reusable package of instructions that loads only when it is relevant. It is how you stop re-explaining your standards in every conversation — and how you get the same output whether it is Tuesday or six months from now.

Related guides: Designing an Agent Harness covers the loop a skill runs inside. AI Tooling & MCP covers giving the model real capabilities rather than just better instructions.

---

What a Skill Actually Is

Strip away the tooling differences and every implementation is the same three things:

1. A trigger — a description that tells the system when this applies
2. A body — the instructions, standards, examples, and edge cases
3. Optional attachments — reference files, templates, or scripts loaded on demand

The trigger is the part everyone underestimates. A brilliant skill with a vague description never fires, which means it does not exist.

Term you might see	Same idea
Skill	Named instruction package with a load condition
Custom instruction / system preamble	Always-on version of the same thing
Playbook / SOP	The human-readable ancestor
Rule file (.cursorrules, AGENTS.md, CLAUDE.md)	Project-scoped, always-on skill

---

Skill vs. Prompt vs. Tool vs. Agent

Picking the wrong one is the most common early mistake.

You want to…	Use
Change how a task is done, consistently	Skill
Do one thing, once, right now	Prompt
Let the model reach real data or take an action	Tool
Let the model decide the sequence of steps	Agent

A skill cannot fetch your analytics. A tool cannot teach taste. People routinely try to solve tool problems with better prose, and it never works — if the model cannot see the data, no amount of instruction produces accurate numbers.

---

Anatomy of a Good Skill

---
name: quarterly-report
description: Use when producing a quarterly performance report — enforces the
  standard section order, the approved metric definitions, and the tone rules.
  Triggers on "quarterly report", "QBR deck", "quarter recap".
---

# Quarterly Report Standard

## Section order (do not reorder)
1. Headline result — one sentence, number first
2. What moved and why
3. What we tried that did not work
4. Next quarter's bets

## Metric definitions
| Term | Definition | Source |
|---|---|---|
| Qualified lead | Form fill + fit score ≥ 3 | CRM, not GA4 |
| Organic revenue | Last non-direct click attribution | Warehouse table `rev_attr` |

## Tone
- Lead with the number, then the explanation
- Name the miss before the win
- No adjectives on metrics ("strong growth" → "+18%")

## Never
- Report a metric without naming its source
- Compare to a quarter with a different definition

Four things make that skill work:

• The description names concrete triggers. Not "helps with reports."
• Definitions are pinned to sources. This is the difference between a report and a guess.
• Tone rules are testable. "No adjectives on metrics" can be checked. "Be professional" cannot.
• There is a Never section. Negative constraints prevent more errors than positive ones.

---

Writing the Description

This is where most skills fail. The description is read by the system to decide whether to load the skill, often against dozens of alternatives.

Weak	Strong
"Helps with content."	"Use when drafting or editing customer-facing blog posts — enforces house style, heading structure, and the claims-need-sources rule."
"SEO stuff."	"Use for on-page SEO review: title/meta length, heading hierarchy, internal linking, schema presence. Triggers on 'SEO review', 'on-page audit'."
"Data analysis helper."	"Use when querying the warehouse — contains table locations, join keys, and the metric definitions that differ from the BI tool's defaults."

Write it in third person, name the situation, and include the literal phrases someone would type.

---

Progressive Disclosure

Context is a budget. Every token spent on instructions is one not spent on the actual work — and long instruction blocks measurably dilute attention on the details that matter.

Structure skills in three tiers:

Tier	Contains	Loaded
Description	When this applies	Always (cheap, one or two lines)
Body	The rules that apply every time	On trigger
References	Long tables, full templates, rare edge cases	On demand, by path

Practically: keep the body under a page or two, and push the 40-row metric dictionary into references/metrics.md that the body points to. The model reads it when it needs it.

The one-page test

If your skill body does not fit on one screen, ask which half is edge-case handling. That half belongs in a reference file.

---

What to Turn Into a Skill

Good candidates share a shape: you have explained it more than twice, and you would notice if it were done differently.

Strong candidate	Why
House writing style	High frequency, easy to get subtly wrong
Metric definitions	Wrong definitions produce confidently wrong numbers
Report / deliverable structure	Consistency is the entire value
Review checklists	Naturally enumerable, naturally forgotten
Domain vocabulary	Prevents plausible-sounding but wrong terminology
Compliance / claim rules	The cost of a miss is high

Poor candidates: anything that changes every time, anything requiring live data (that is a tool), and anything you have only done once.

---

Testing a Skill

Skills are code. Untested code drifts.

1. Trigger test. Ask five differently-phrased questions that should load it. Does it fire? Then ask three that should not. Does it stay quiet?
2. Cold test. Run a real task in a fresh session with no other context. Compare against what you would have produced by hand.
3. Adversarial test. Feed it the edge case that made you write the skill in the first place.
4. Regression test. Keep three known inputs and their good outputs. Re-run them after every skill edit.

Step 4 is the one people skip, and it is the one that catches the edit where you "clarified" a rule and quietly inverted it.

---

Common Failure Modes

Symptom	Cause	Fix
Skill never fires	Vague description	Add literal trigger phrases and the situation
Fires on everything	Description too broad	Add explicit "do not use when…"
Output still inconsistent	Rules are subjective	Rewrite each rule so it is checkable
Contradicts another skill	Overlapping scope	Merge them, or give one clear precedence
Worked, then stopped	Body grew past useful length	Split into body + references
Ignores a specific rule	Rule buried mid-paragraph	Promote to its own bullet or a Never list

---

Skill Hygiene Checklist

• Description names the situation and includes literal trigger phrases
• Description says when not to use it, if there is a near neighbor
• Body fits on roughly one screen
• Long tables and templates live in reference files, not the body
• Every rule is checkable, not a matter of taste
• There is an explicit Never section
• Definitions name their source of truth
• Three regression inputs are stored with known-good outputs
• Owner and last-reviewed date are recorded
• It has been run cold, in a fresh session, at least once

---

Next Steps

A skill shapes how work is done. It cannot reach your data or take action — for that you need tools.

AI Tooling & MCP →

---

Get in touch if you are building a skill library and want a second opinion on structure.