Skip to module content
🧠AI Academy
0/91
Sign in
Module 03 Β· ~9 min

Skills: SOPs That Execute Themselves

The most important format of 2026, and the craft of authoring them.

Reading progress
0/8 Β· 0%

The big idea

πŸ’‘Key idea
A **skill** is a folder containing a `SKILL.md` file β€” a short YAML header (name and description) followed by Markdown instructions β€” plus optional `scripts/` and `references/` folders. *Progressive disclosure* is the mechanic that makes it scalable: roughly 100 tokens of name and description are always visible to the model; the full instructions (under 5k tokens) load only when relevant; auxiliary files load only on demand. You can install hundreds of skills without bloating context. Rule of thumb: if you type the same prompt across multiple conversations, it should be a skill. For an agency whose pitch includes 'we build your SOPs,' this is an existential upgrade. A traditional SOP is a document a human must find, read, and follow β€” with all the inconsistency that implies. A skill is the same institutional knowledge in a form the agent *discovers, loads, and executes* on its own. Your SOPs become self-running.
Quick check
1 question Β· instant feedback
0/1
  1. The #1 cause of skills that never fire is:

Numbers that matter

8
Skills in the reference Google Ads suite (3 read, 4 write, 1 retract) β€” the pull/push/retract doctrine.
<5k
Token budget for a well-authored SKILL.md β€” depth in references/ loads on demand.
#1
Cause of skills that never fire: bad frontmatter descriptions.
Quick check
1 question Β· instant feedback
0/1
  1. Why split read and write into separate skills?

Deep dive

4/4 open

The frontmatter `description` field is the **only thing the agent sees** when deciding whether to load a skill. The full instructions, the scripts, the references β€” none of it exists until that description earns a load.

Write it as trigger conditions, not marketing copy. Good: *'Use whenever the action is: add these negatives, block these terms, cut this wasted spend.'* Bad: *'A comprehensive skill for Google Ads optimization.'*

Bad descriptions are the #1 reason skills never fire in production. Most skill authors write descriptions for humans. Write yours for the router.

The body of a SKILL.md should read like a checklist a competent new hire could follow without a manager present.

Use numbered steps. Specify exact output formats. Include failure-handling instructions. Add examples of good and bad outputs. Decision matrices beat paragraphs β€” if the model has to interpret ambiguous prose, you've introduced variance you'll pay for later.

For anything deterministic β€” data pulls, formatting, file writes β€” **bundle a script** rather than letting the model improvise. Scripts are cheaper, faster, and reproducible. Model improvisation on deterministic tasks is a hidden cost center.

Here's the starting library organized by function:

**Delivery / ops:** `sprint-loop`, `client-onboarding`, `weekly-client-report`, `proposal-builder`

**Growth:** `icp-research`, `landing-page-teardown`, `linkedin-post-pipeline`, `geo-audit`

**Paid:** The eight Google Ads skills (parameterized per client, then mirrored for Meta)

**Content:** `brand-voice`, `content-repurpose`, `substantive-pushback`

Each one is a folder, not a mega-skill. Composition beats configuration.

Knowing when *not* to write a skill is as important as knowing how to write one.

**Skill** = a portable capability the agent discovers and applies by judgment. Use for repeatable workflows.

**Subagent** = a separate context window with restricted tools. Use for role isolation or large-document processing.

**Hook** = a guaranteed script that runs at a lifecycle event regardless of model intent. Use for safety rules, PII scans, audit logs β€” anything that must be a certainty, not a probability.

**CLAUDE.md** = always-on context for one project. Use for conventions, client background, tone rules.

**MCP server** = a live integration with an external tool. Use when the task requires calling an API.

**Slash command** = a human-triggered, parameterized shortcut. Use when a person initiates the workflow.

Advanced patterns compose these: a subagent that loads a skill, or a skill that builds an MCP server (Anthropic's `mcp-builder` skill does exactly this).

Quick check
1 question Β· instant feedback
0/1
  1. Progressive disclosure means an agent can carry hundreds of skills because:

How to run it

  1. Write the description as triggers
    'Use whenever…' phrasing; test with skill-creator to measure firing accuracy.
  2. Under 5k tokens in SKILL.md
    Everything else goes to references/ and loads on demand.
  3. One skill, one job
    Split read from write, and each mutation class from the others.
  4. Version + benchmark
    Treat skills like software: git-versioned, eval'd before/after edits, must beat the no-skill baseline.
Quick check
1 question Β· instant feedback
0/1
  1. Use a hook instead of a skill when:

In the field

πŸ”¬Worked example
The eight-skill Google Ads suite: read side (google-performance-pull, google-search-terms-pull, google-geo-pull) and write side (google-push-negatives, google-push-keywords, google-push-campaign-settings, google-push-geo-bids, google-retract-leads). Architecture rules baked in: read and write separated, skills chain via named upstream analyses, the feedback loop (lead retraction) is a first-class skill.
🚫When not to reach for it
Don't build a skill when the capability is really an integration (that's an MCP server), a guarantee (hook), always-on client context (CLAUDE.md), or a human-triggered parameterized shortcut (slash command).
Quick check
1 question Β· instant feedback
0/1
  1. The lead-retraction skill is a doctrine because:

Pitfalls & takeaways

Failure modes

  • Bad descriptions are the #1 cause of skills that never fire β€” write trigger conditions, not marketing copy.
  • Mega-skills that try to do everything; composition beats configuration.
  • SKILL.md over ~5k tokens β€” push depth into references/ that load on demand.
  • Reusing model improvisation where a bundled script would be cheaper and reproducible.

Durable takeaways

  • Description is destiny β€” it's the only thing the router sees.
  • Composition beats configuration: split read/write and per-mutation class.
  • Bundled scripts beat model improvisation for anything deterministic.
  • Skills are portable across every major stack β€” no lock-in.
  • Version, benchmark, and eval skills like software.

Do the work

πŸ‹οΈProve you learned it

Take a repeated agency task (weekly client report). Write two skills β€” one read (pulls metrics), one write (drafts the narrative to a doc). Frontmatter descriptions must be trigger conditions ('Use whenever the action is…'). Bench them with skill-creator's eval harness against a no-skill baseline; ship only if measurably better.

0 chars
πŸ“¦Artifact to produce
Two production skills for one client workflow, following description-is-destiny + composition rules.

Sources

  • Β· GMS Field Manual Β§3 (Skills: SOPs That Execute Themselves)
  • Β· Anthropic 'Skills Explained' + skill-creator tooling