# RESEARCH-SYNTHESIS.md — How to Write Ultra-Sharp Skills for AI Agents

Author: Simon-Pierre Boucher Contact: contact@spboucher.ai Date: 2026-08-05 Basis: 16 distinct web searches + page fetches across official Anthropic documentation, the anthropics/skills repository, Anthropic engineering/blog posts, and community engineering write-ups. Sources listed at the end.

# Part 1 — The 15 Core Principles of an Ultra-Sharp Skill

The description IS the trigger. At startup only name + description are loaded (~100 tokens/skill); Claude matches the user's request against the description to decide whether to fire. A vague description is the #1 cause of skill failure.
A description states WHAT + WHEN, with literal user phrases. Include both what the skill does and the concrete trigger contexts — the exact words a user would type ("PDFs, forms, document extraction") — because an abstract description won't match a concrete request.
Write descriptions in third person, directive voice. Descriptions are injected into the system prompt; "I can help you…" or "You can use this…" causes discovery problems. Directive phrasing ("Use when…") measurably raises activation rates versus purely descriptive phrasing.
Descriptions live in a shared, finite budget. In Claude Code all skill descriptions share a character budget (~15,000 chars default) and overflow is silently dropped — so every description must be dense and short, and each skill you add taxes all the others.
Progressive disclosure is the architecture. Three levels: metadata (always loaded, ~100 tokens), SKILL.md body (loaded on trigger, keep <500 lines / <5k tokens), bundled resources (zero context cost until read/executed). Design every skill around these levels.
Concise is key — the context window is a public good. Assume Claude is already smart: cut anything Claude already knows, and challenge every paragraph with "does this justify its token cost?"
Match degrees of freedom to task fragility. Fragile, order-dependent operations get exact scripts and "do not modify" guardrails (low freedom); judgment tasks get heuristics and trust (high freedom). Narrow bridge → rails; open field → direction.
One default, not a menu. Give a single recommended tool/approach with an explicit escape hatch for the exception ("Use pdfplumber; for scanned PDFs use OCR instead") — offering many options confuses execution.
Prefer deterministic scripts over prose for deterministic work. Bundled scripts are more reliable than generated code, cost zero context (only their output enters context), and must solve errors themselves rather than defer to Claude; no unexplained "voodoo constants."
Make execution intent explicit. Say "Run scripts/x.py" (execute) vs "See scripts/x.py for the algorithm" (read) — ambiguity here wastes tokens or produces re-implementation.
Keep references one level deep, with a table of contents past ~100 lines. Nested reference chains get partially read (head -100); every reference file should link directly from SKILL.md, and long ones need a TOC so partial reads still reveal scope.
Fully specify the output. Templates, exact file naming, destination paths, and input→output example pairs (3–5, covering edge cases) convey format and style better than any amount of description — this is standard prompt-engineering practice applied to skills.
Use workflows with checklists and validation loops. Break complex tasks into numbered steps Claude can check off, and close the loop: run validator → fix → re-validate → only then proceed.
Build evals BEFORE writing extensive documentation. Establish a baseline without the skill, write ≥3 test scenarios including negative prompts that must NOT trigger the skill, run multiple trials (behavior is nondeterministic), and grade outcomes, not paths.
Iterate from observed behavior, not assumptions. Use the two-Claude loop (Claude A authors, Claude B executes real tasks), watch how the agent actually navigates the files (ignored files, missed links, over-read sections), and refine the description first whenever triggering misfires.

Hygiene constants (from the spec): name ≤64 chars, lowercase/numbers/hyphens only, no reserved words ("anthropic", "claude"), gerund form preferred; description ≤1,024 chars, non-empty, no XML tags; consistent terminology throughout; no time-sensitive facts; forward-slash paths only; never assume packages are installed.

# Part 2 — The Sharp Skill Checklist

Apply line by line to EVERY skill before delivery.

# A. Triggering (the point of the spear)

A1. Description states WHAT the skill does AND WHEN to use it
A2. Description contains the literal key terms/phrases a user would type
A3. Description is third person, directive ("Use when…"), no XML tags, ≤1,024 chars
A4. Description would NOT match plausible neighboring requests (no false positives)
A5. Name is gerund-form (or clear noun phrase), lowercase/hyphens, ≤64 chars, not vague (helper, utils)

# B. Body sharpness

B1. SKILL.md body <500 lines; anything long lives in references/
B2. No content Claude already knows; every paragraph earns its tokens
B3. Exactly one recommended default per operation, with explicit escape hatch
B4. Workflow is numbered steps (checklist if >3 steps); validation loop for quality-critical output
B5. Output format fully specified: structure, file naming, destination
B6. Concrete input→output examples where style/format matters
B7. Consistent terminology; no time-sensitive info; no vague verbs without a procedure
B8. Failure modes and edge cases explicitly addressed

# C. Resources & structure

C1. All references link one level deep from SKILL.md; descriptive file names
C2. Reference files >100 lines start with a table of contents
C3. Scripts: execution vs read-as-reference intent is explicit
C4. Scripts handle their own errors ("solve, don't defer"); all constants justified
C5. Dependencies stated explicitly (or stdlib-only); forward-slash paths only

# D. Validation

D1. ≥3 test prompts written: triggering AND at least one non-triggering
D2. Skill executed/simulated against triggering prompts; outputs verified
D3. Negative prompt confirmed NOT to activate the skill
D4. Checklist re-run after any fix

# E. Project rule

E1. Every file carries the author header (Author: Simon-Pierre Boucher / Contact: contact@spboucher.ai)

# Part 3 — Template of the Ideal SKILL.md

markdown

---
name: doing-the-thing            # gerund, lowercase-hyphens, ≤64 chars
description: <What it does in one clause with key nouns>. Use when the user asks to <literal trigger phrases>, mentions <key terms>, or <concrete context>. Do not use for <nearest non-target intent>.
---

<!--
Author: Simon-Pierre Boucher
Contact: contact@spboucher.ai
-->

# Doing the Thing

## When to use / when NOT to use
- Use for: <precise intents>
- Do NOT use for: <neighboring intents that belong to other skills or plain answers>

## Workflow
Copy this checklist and check off items as you complete them:

- [ ] Step 1: <action> (run `scripts/tool.py <args>` — execute, do not read)
- [ ] Step 2: <action>
- [ ] Step 3: Validate: <check>. If it fails, fix and repeat Step 2.
- [ ] Step 4: Produce output exactly per "Output format" below.

## Output format
Save to `<naming-rule>`. Use this exact structure:
<template block>

## Examples
**Input:** <realistic input> → **Output:** <exact desired output>
**Input:** <edge case> → **Output:** <exact desired output>

## Edge cases & failure modes
- <case> → <exact behavior>
- <case> → <exact behavior>

## References (one level deep)
- Advanced details: see [references/advanced.md](references/advanced.md)

Directory anatomy:

text

doing-the-thing/
├── SKILL.md              # <500 lines, loaded on trigger
├── references/           # loaded only when needed; TOC if >100 lines
│   └── advanced.md
├── scripts/              # executed via bash; only output enters context
│   └── tool.py
└── assets/               # templates, images, data (optional)

# Sources

Primary (fetched in full):

Secondary (search-level):