Skills

Skills are folders under skills/<name>/ containing a SKILL.md and any supporting files. They use progressive disclosure — the description loads eagerly so Claude knows the skill exists, but the body only loads when the skill is invoked.

This is the right primitive when work needs guidance, not delegation. A skill runs inline on the main thread — Claude reads the instructions, applies them to the current conversation, and the findings stay in context. That’s the difference from a subagent: skills shape how Claude works on something; subagents do the work in isolation and return a summary.

For the broader question of when to reach for a skill versus a CLAUDE.md rule or a subagent, see Foundational elements.

Where they live

Skills are folders, not single files:

• User-level — ~/.claude/skills/<name>/. Available across every project.
• Project-level — <repo>/.claude/skills/<name>/. Committed with the repo.

Each skill folder must contain a SKILL.md. Optional supporting files (reference material, scripts, templates) live alongside it and load only when the skill needs them.

What skills can do that subagents can’t

Skills can include scripts that Claude executes via bash without loading the script contents into context. They can bundle reference files that load only when needed. And they’re portable: skills are an open standard at agentskills.io, so a skill authored once works across multiple AI tools that support the format.

For the Playbook’s purposes, the simplest framing is: a skill is a workflow you want available when relevant, not on every session.

Frontmatter shape

The minimum useful skill definition:

---
name: skill-name
description: What this skill does and when to use it. Written in third person.
---

Instructions for Claude when the skill is invoked.

Required fields:

• name — lowercase letters, numbers, and hyphens only. Maximum 64 characters. Anthropic recommends gerund form (reviewing-drafts, screening-stocks) but the convention isn’t universal.
• description — what the skill does and when to use it, written in third person. Maximum 1024 characters. The description is injected into the system prompt at session start; this is what Claude uses to decide whether to invoke the skill.

Optional fields worth knowing:

• allowed-tools — restrict what the skill can do, same way subagents do.
• model — override the main thread’s model when the skill is invoked.
• metadata — optional catch-all for things the spec doesn’t formally cover (versioning, authorship, last-updated date).

The 500-line discipline

Anthropic recommends keeping SKILL.md body under 500 lines. Beyond that, Claude may not load the full file reliably.

If a skill genuinely needs more than 500 lines of content, the right answer is to split:

my-skill/
├── SKILL.md            # Core instructions, under 500 lines
├── references/
│   ├── full-spec.md    # Loaded only when SKILL.md references it
│   └── examples.md
└── scripts/
    └── helper.py       # Executed via bash, contents never load to context

SKILL.md then references the supporting files by name (“for the full schema, see references/full-spec.md”), and Claude loads them only when the task genuinely requires them. This is the third level of progressive disclosure — and the reason skills can grow as large as needed without bloating context.

Two skills that earn their keep

The two below are starting points. Both are user-level (~/.claude/skills/).

Adversarial self-review

The “always apply adversarial review” rule, demoted from CLAUDE.md system prompt to on-demand skill. Triggered by completion phrases or explicit invocation.

---
name: adversarial-self-review
description: Runs adversarial self-review on a completed draft before finalising. Triggered when the user signals a draft is complete, asks for review, or explicitly invokes this skill. Use before final delivery of strategy documents, memos, or product decisions.
---

Before final output, run through:

1. **Assumption audit** — what am I assuming that isn't proven?
2. **Counter-case** — what's the strongest argument against this conclusion?
3. **Evidence gaps** — where am I extrapolating beyond what I've shown?
4. **Bias check** — am I advocating where I should be analysing?
5. **Hedging audit** — am I softening claims to avoid taking a position?

Surface findings as a brief at the top of the draft. Do not silently rewrite.

Why it’s a skill, not a CLAUDE.md rule: the work only matters at draft completion, not on every read or edit. Loading “apply adversarial review” on every session is a cost that pays back only occasionally.

Why it’s a skill, not a subagent: the review uses the main thread’s existing context (the draft you’ve been working on). Forking into an isolated subagent context loses that — you’d have to re-feed the draft, and the main thread wouldn’t see the findings inline.

Stage-analysis screen

Encodes a specific analytical methodology. Triggered by screening requests.

---
name: stage-analysis-screen
description: Applies Weinstein Stage Analysis to a stock or ETF. Triggered when the user asks to screen, classify a stage, or evaluate a chart for stage transitions. Returns structured stage classification with moving-average slope, volume, and breakout filter analysis.
---

Classify into Stage 1 (basing), Stage 2 (advancing), Stage 3 (topping), or Stage 4 (declining).

Required inputs:
- Price relative to 30-week MA
- 30-week MA slope (flat / rising / falling, with threshold)
- Volume on recent breakouts or breakdowns
- Relative strength vs benchmark

Apply false-breakout filters: minimum 2-bar close above resistance, volume confirmation, no immediate reversal.

Output: stage classification, conviction level, key levels to watch, kill rule for the thesis.

This is a useful template for any methodology-as-skill: a named framework with required inputs, decision rules, and a structured output. The methodology lives in the skill, not in the system prompt — which means it loads only when relevant and travels cleanly to other projects that need the same analysis.

Common anti-patterns

Description without “when to use”. Anthropic’s docs are explicit about this: descriptions need both what the skill does and when to use it. A description that only describes the capability (“Processes Excel files”) leaves Claude unable to decide whether to invoke it.

Inconsistent point-of-view. Write descriptions in third person (“Processes Excel files and generates reports”) not second person (“You can use this to process Excel files”). The description is injected into the system prompt; mixing voices causes discovery problems.

Bloated SKILL.md. Past 500 lines, performance degrades. The fix is the same as for CLAUDE.md — delete what doesn’t earn its place, or split into reference files that load on demand.

Skill-shaped subagents. If the work needs an isolated context window or a different model, it’s a subagent. Skills run inline on the main thread.