spb/ultra-sharp-agent-skills Public

1<!--2Author: Simon-Pierre Boucher3Contact: contact@spboucher.ai4-->56# RESEARCH-SYNTHESIS.md — How to Write Ultra-Sharp Skills for AI Agents78**Author:** Simon-Pierre Boucher9**Contact:** contact@spboucher.ai10**Date:** 2026-08-0511**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.1213---1415## Part 1 — The 15 Core Principles of an Ultra-Sharp Skill16171. **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.18192. **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.20213. **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.22234. **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.24255. **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.26276. **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?"28297. **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.30318. **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.32339. **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."343510. **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.363711. **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.383912. **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.404113. **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.424314. **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.444515. **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.4647**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.4849---5051## Part 2 — The Sharp Skill Checklist5253Apply line by line to EVERY skill before delivery.5455### A. Triggering (the point of the spear)56- [ ] A1. Description states WHAT the skill does AND WHEN to use it57- [ ] A2. Description contains the literal key terms/phrases a user would type58- [ ] A3. Description is third person, directive ("Use when…"), no XML tags, ≤1,024 chars59- [ ] A4. Description would NOT match plausible neighboring requests (no false positives)60- [ ] A5. Name is gerund-form (or clear noun phrase), lowercase/hyphens, ≤64 chars, not vague (`helper`, `utils`)6162### B. Body sharpness63- [ ] B1. SKILL.md body <500 lines; anything long lives in `references/`64- [ ] B2. No content Claude already knows; every paragraph earns its tokens65- [ ] B3. Exactly one recommended default per operation, with explicit escape hatch66- [ ] B4. Workflow is numbered steps (checklist if >3 steps); validation loop for quality-critical output67- [ ] B5. Output format fully specified: structure, file naming, destination68- [ ] B6. Concrete input→output examples where style/format matters69- [ ] B7. Consistent terminology; no time-sensitive info; no vague verbs without a procedure70- [ ] B8. Failure modes and edge cases explicitly addressed7172### C. Resources & structure73- [ ] C1. All references link one level deep from SKILL.md; descriptive file names74- [ ] C2. Reference files >100 lines start with a table of contents75- [ ] C3. Scripts: execution vs read-as-reference intent is explicit76- [ ] C4. Scripts handle their own errors ("solve, don't defer"); all constants justified77- [ ] C5. Dependencies stated explicitly (or stdlib-only); forward-slash paths only7879### D. Validation80- [ ] D1. ≥3 test prompts written: triggering AND at least one non-triggering81- [ ] D2. Skill executed/simulated against triggering prompts; outputs verified82- [ ] D3. Negative prompt confirmed NOT to activate the skill83- [ ] D4. Checklist re-run after any fix8485### E. Project rule86- [ ] E1. Every file carries the author header (Author: Simon-Pierre Boucher / Contact: contact@spboucher.ai)8788---8990## Part 3 — Template of the Ideal SKILL.md9192```markdown93---94name: doing-the-thing            # gerund, lowercase-hyphens, ≤64 chars95description: <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>.96---9798<!--99Author: Simon-Pierre Boucher100Contact: contact@spboucher.ai101-->102103# Doing the Thing104105## When to use / when NOT to use106- Use for: <precise intents>107- Do NOT use for: <neighboring intents that belong to other skills or plain answers>108109## Workflow110Copy this checklist and check off items as you complete them:111112- [ ] Step 1: <action> (run `scripts/tool.py <args>` — execute, do not read)113- [ ] Step 2: <action>114- [ ] Step 3: Validate: <check>. If it fails, fix and repeat Step 2.115- [ ] Step 4: Produce output exactly per "Output format" below.116117## Output format118Save to `<naming-rule>`. Use this exact structure:119<template block>120121## Examples122**Input:** <realistic input> → **Output:** <exact desired output>123**Input:** <edge case> → **Output:** <exact desired output>124125## Edge cases & failure modes126- <case> → <exact behavior>127- <case> → <exact behavior>128129## References (one level deep)130- Advanced details: see [references/advanced.md](references/advanced.md)131```132133Directory anatomy:134135```text136doing-the-thing/137├── SKILL.md              # <500 lines, loaded on trigger138├── references/           # loaded only when needed; TOC if >100 lines139│   └── advanced.md140├── scripts/              # executed via bash; only output enters context141│   └── tool.py142└── assets/               # templates, images, data (optional)143```144145---146147## Sources148149Primary (fetched in full):150- [Skill authoring best practices — Claude Platform Docs](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices.md)151- [Agent Skills overview — Claude Platform Docs](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/overview)152- [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)153- [skill-creator SKILL.md — anthropics/skills (GitHub)](https://github.com/anthropics/skills/blob/main/skills/skill-creator/SKILL.md)154- [Extend Claude with skills — Claude Code Docs](https://code.claude.com/docs/en/skills)155- [Improving skill-creator: test, measure, and refine Agent Skills — Anthropic blog](https://claude.com/blog/improving-skill-creator-test-measure-and-refine-agent-skills)156- [Practical Guide to Evaluating and Testing Agent Skills — Philipp Schmid](https://www.philschmid.de/testing-skills)157- [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/)158159Secondary (search-level):160- [anthropics/skills repository](https://github.com/anthropics/skills)161- [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)162- [How to Activate Claude Skills Automatically — DEV Community](https://dev.to/oluwawunmiadesewa/claude-code-skills-not-triggering-2-fixes-for-100-activation-3b57)163- [Prompt engineering best practices for 2026 — Claude blog](https://claude.com/blog/best-practices-for-prompt-engineering)164- [Testing Agent Skills Systematically with Evals — OpenAI Developers](https://developers.openai.com/blog/eval-skills)165- [Function calling — OpenAI API docs](https://developers.openai.com/api/docs/guides/function-calling)166- [Agent Skills: Progressive Disclosure as a System Design Pattern — SwirlAI](https://www.newsletter.swirlai.com/p/agent-skills-progressive-disclosure)167- [Introducing Task Evals — Tessl](https://tessl.io/blog/introducing-task-evals-measure-whether-your-skills-actually-work/)168