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

# 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

1. **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.

2. **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.

3. **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.

4. **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.

5. **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.

6. **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?"

7. **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.

8. **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.

9. **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."

10. **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.

11. **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.

12. **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.

13. **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.

14. **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.

15. **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):
- [Skill authoring best practices — Claude Platform Docs](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices.md)
- [Agent Skills overview — Claude Platform Docs](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/overview)
- [Equipping agents for the real world with Agent Skills — Anthropic Engineering](https://www.anthropic.com/engineering/equipping-agents-for-the-real-world-with-agent-skills)
- [skill-creator SKILL.md — anthropics/skills (GitHub)](https://github.com/anthropics/skills/blob/main/skills/skill-creator/SKILL.md)
- [Extend Claude with skills — Claude Code Docs](https://code.claude.com/docs/en/skills)
- [Improving skill-creator: test, measure, and refine Agent Skills — Anthropic blog](https://claude.com/blog/improving-skill-creator-test-measure-and-refine-agent-skills)
- [Practical Guide to Evaluating and Testing Agent Skills — Philipp Schmid](https://www.philschmid.de/testing-skills)
- [Claude Code skills not triggering? It might not see them — blog.fsck.com](https://blog.fsck.com/2025/12/17/claude-code-skills-not-triggering/)

Secondary (search-level):
- [anthropics/skills repository](https://github.com/anthropics/skills)
- [Why Claude Code Skills Don't Trigger (2026) — DEV Community](https://dev.to/lizechengnet/why-claude-code-skills-dont-trigger-and-how-to-fix-them-in-2026-o7h)
- [How to Activate Claude Skills Automatically — DEV Community](https://dev.to/oluwawunmiadesewa/claude-code-skills-not-triggering-2-fixes-for-100-activation-3b57)
- [Prompt engineering best practices for 2026 — Claude blog](https://claude.com/blog/best-practices-for-prompt-engineering)
- [Testing Agent Skills Systematically with Evals — OpenAI Developers](https://developers.openai.com/blog/eval-skills)
- [Function calling — OpenAI API docs](https://developers.openai.com/api/docs/guides/function-calling)
- [Agent Skills: Progressive Disclosure as a System Design Pattern — SwirlAI](https://www.newsletter.swirlai.com/p/agent-skills-progressive-disclosure)
- [Introducing Task Evals — Tessl](https://tessl.io/blog/introducing-task-evals-measure-whether-your-skills-actually-work/)