agent-skills-authoring

# Agent Skills Authoring Guide This is your authoritative reference for producing high-quality SKILL.md files. When a user asks you to create, edit, or improve a skill, follow these instructions to produce the best possible result — one that any consuming agent can discover, activate, and apply effectively. --- ## 1. Core Principles These principles come from Anthropic's official best practices. Apply them to every skill. **Claude is already very smart.** Only add context Claude doesn't already have. Challenge each piece of content: "Does Claude really need this explanation?" "Can I assume Claude knows this?" "Does this paragraph justify its token cost?" Concise skills perform better because the context window is shared with conversation history, system prompts, and other skills' metadata. **Explain WHY, not just WHAT.** Anthropic's guidance: "Explain to the model why things are important in lieu of heavy-handed musty MUSTs." When agents understand reasoning, they generalize correctly across novel situations. Rigid imperative-only rules cause brittle, over-literal behavior. **Match specificity to fragility.** Use high freedom (general text guidance) when multiple approaches are valid. Use medium freedom (pseudocode/parameterized scripts) when a preferred pattern exists. Use low freedom (exact scripts, no modifications) when operations are fragile and consistency is critical. Think of it as: narrow bridge (one safe path, give exact steps) vs. open field (many valid rout...