Claude Agent Skills: A First Principles Deep Dive (leehanchung.github.io)

Anthropic’s deep dive explains Claude’s Agent Skills: a prompt-first “meta-tool” architecture that extends an LLM by injecting domain-specific instruction templates into the conversation context rather than executing code or running external functions. Skills live as folders (discovered from ~/.config, project dirs, plugins, or built-ins) and are described to Claude via a single Skill tool in the tools array; Claude decides whether to invoke a skill purely through its internal language reasoning (matching user intent to skill descriptions embedded in the Skill tool prompt), not via embeddings, classifiers, or code-level routing. Invocation loads SKILL.md, injects its instructions as conversational messages, may change allowed tools and model selection, and then continues the session — so skills prepare the agent rather than return immediate results. For builders and the AI/ML community this clarifies trade-offs and best practices: skills are essentially prompt templates with YAML frontmatter (name, description, allowed-tools, model, version) plus optional assets/scripts (resources, not automatically executed) and follow a progressive-disclosure pattern. Key technical implications include explicit permission scoping via allowed-tools (avoid over-broad permissions), non-algorithmic LLM-based selection (affects predictability and testing), concurrency and security concerns (skills modify execution context), and an extensible packaging model (SKILL.md + assets) for turning general agents into specialized ones. The undocumented when_to_use field is noted as brittle; rely on clear descriptions instead.