spb/ultra-sharp-agent-skills Public

1<!--2Author: Simon-Pierre Boucher3Contact: contact@spboucher.ai4-->56# CLAUDE.md — Skill Authoring Protocol (Research-First, Ultra-Sharp Skills)78**Author:** Simon-Pierre Boucher9**Contact:** contact@spboucher.ai1011---1213## Mission1415You (Claude) will become an expert in writing **skills for AI agents** — skills that are *ultra sharp* and *fine-pointed*: minimal surface, maximal precision, zero ambiguity, perfect triggering. You will do this in two mandatory phases: **(1) Ultra-intensive web research**, then **(2) Build 2 example skills in English to validate what you learned.**1617Do NOT skip Phase 1. Do NOT write any skill before the research is complete and synthesized.1819---2021## Phase 1 — Ultra-Intensive Web Research (MANDATORY FIRST)2223Perform a deep, exhaustive web research campaign (minimum 10–15 distinct searches + page fetches) on how to write high-quality skills for AI agents. Cover ALL of the following angles:24251. **Official Anthropic documentation on Agent Skills** — SKILL.md format, YAML frontmatter (`name`, `description`), progressive disclosure (metadata → body → bundled resources), folder anatomy (`scripts/`, `references/`, `assets/`).262. **Skill triggering mechanics** — how descriptions drive activation, why skills under-trigger, how to write "pushy" but precise descriptions that fire on the right user phrases and never on the wrong ones.273. **Best practices & anti-patterns** — ideal SKILL.md length (<500 lines), when to split into reference files, table of contents for large references, "principle of least surprise," deterministic scripts vs. prose instructions.284. **Prompt engineering research applied to skills** — instruction clarity, positive/negative examples, output-format specification, step ordering, failure-mode handling.295. **Community & ecosystem knowledge** — GitHub repos of real skills (e.g., anthropics/skills), blog posts, engineering write-ups, comparisons with OpenAI/LLM tool-use instructions, MCP-adjacent patterns.306. **Evaluation & iteration** — how to test a skill (trigger evals, task evals), how to measure trigger rate, how to iterate on descriptions without overfitting.3132### Research rules33- Use `web_search` broadly first, then `web_fetch` the highest-quality primary sources (Anthropic docs, official repos, engineering blogs).34- Take structured notes as you go. Prefer primary sources over aggregators.35- At the end of Phase 1, produce a written synthesis file: **`RESEARCH-SYNTHESIS.md`** containing:36  - The 10–15 core principles of an ultra-sharp skill (each in 1–2 sentences).37  - A checklist ("Sharp Skill Checklist") you will apply to every skill you write.38  - A template of the ideal SKILL.md structure.39- Only when `RESEARCH-SYNTHESIS.md` is complete may you proceed to Phase 2.4041---4243## Phase 2 — Build 2 Example Skills (in English) to Test the Method4445Using ONLY the principles from your synthesis, create **two complete example skills, written entirely in English**, each in its own folder with a proper `SKILL.md`:4647### Skill 1 — Deterministic / verifiable domain48A skill with objectively checkable output (e.g., data extraction, file transformation, structured report generation). It must include:49- YAML frontmatter with a sharp, trigger-optimized `description`.50- A step-by-step workflow with explicit output format.51- At least one bundled resource (`references/` or `scripts/`) demonstrating progressive disclosure.5253### Skill 2 — Stylistic / subjective domain54A skill governing style or judgment (e.g., a house writing style, a code-review playbook). It must include:55- Positive AND negative examples (do this / never do this).56- Clear boundary conditions: when the skill applies and when it must NOT.5758### Validation step59For each skill, after writing it:601. Write 3 realistic test prompts (some that SHOULD trigger it, at least one that should NOT).612. Simulate/run the skill against the triggering prompts and show the outputs.623. Apply your "Sharp Skill Checklist" line by line and report pass/fail.634. Fix anything that fails, then re-check.6465---6667## Non-Negotiable File Header Rule6869**EVERY file you create in this project** — `CLAUDE.md`, `RESEARCH-SYNTHESIS.md`, every `SKILL.md`, every reference file, every script — MUST begin with this header (adapted to the file's comment syntax):7071```72Author: Simon-Pierre Boucher73Contact: contact@spboucher.ai74```7576- Markdown files: use an HTML comment block or visible header lines at the very top.77- Python/shell scripts: use `#` comment lines at the very top (after any shebang).78- YAML frontmatter files (SKILL.md): place the header comment immediately after the frontmatter block, or as `#` comments before it if the format allows.7980No file ships without this header. Verify it before delivering anything.8182---8384## Definition of "Ultra Sharp / Fine Point"8586A skill qualifies as ultra sharp only if:87- Its description triggers on the exact intended intents and nothing else.88- Every instruction is actionable — no vague verbs ("handle," "deal with") without a concrete procedure.89- The SKILL.md is as short as possible but no shorter; anything long lives in `references/`.90- Output format is fully specified (structure, naming, location).91- Failure modes and edge cases are addressed explicitly.92- It passed the validation step above.9394---9596## Deliverables Summary97981. `RESEARCH-SYNTHESIS.md` (with header)992. `skill-1-<name>/SKILL.md` + resources (all with headers)1003. `skill-2-<name>/SKILL.md` + resources (all with headers)1014. Validation report (test prompts, outputs, checklist results)102103Work in this exact order. Research first. Sharp skills second. Headers everywhere.104