Agent Skills Explained: Definition, Structure, and Engineering Practices

Official Definition and Core Idea

Anthropic defines an Agent Skill as an organized collection of files —primarily a folder containing Markdown documentation, optional scripts, and metadata. This file‑system abstraction makes the creation barrier extremely low: a Skill can be written with any text editor, versioned with Git, and distributed by cloning the repository.

Why Skills Matter

Skills are executable knowledge rather than static facts. They encode procedural knowledge (the "how") while declarative knowledge (the "what") remains in traditional wikis or documentation. By packaging code, instructions, and resources together, Skills enable rapid, Lego‑style composition of complex workflows.

File Structure Overview

SKILL.md

: mandatory file containing two sections—YAML front‑matter (name and description) and the Markdown instruction body. scripts/: optional executable scripts (Python, Bash, JavaScript, etc.) that the Skill can invoke. references/: read‑only reference documents, API specs, schemas, or other supporting material. assets/: static resources such as icons, templates, or PDFs used for visual output.

Three‑Layer Progressive Disclosure

The system loads Skill information in three stages to keep the LLM context small:

Metadata layer (startup) : only the name and description from each SKILL.md are pre‑loaded into the system prompt (≈30‑50 tokens per Skill).

Instruction layer (task trigger) : when a task matches a Skill’s description, the full SKILL.md (YAML + Markdown) is loaded.

Resource layer (execution) : scripts, reference files, and assets are fetched only when the Skill’s instructions require them.

This design prevents context overload while allowing on‑demand access to detailed knowledge.

Discovery, Selection, and Execution

At startup the Agent scans the Skills directory, extracts each Skill’s description, and stores it in the system prompt. During a conversation the Agent semantically matches the user’s request against these descriptions, selects relevant Skills, loads their full instructions, runs any referenced scripts via the command line, and finally formats the output according to the Skill’s template.

Composition Patterns

Skills can be combined in three ways:

Parallel trigger : multiple matching Skills are activated simultaneously and their results are merged.

Pipeline : the output of one Skill becomes the input of the next, forming a sequential workflow.

Nested call : a Skill’s instruction explicitly invokes another Skill, creating a hierarchical execution tree.

Five Standard Design Patterns

Derived from Google Cloud’s best practices, the patterns cover most use cases:

Tool Wrapper – encapsulates external tools.

Generator – collects parameters then produces standardized output.

Reviewer – inserts review steps into a pipeline.

Inversion – gathers data first, then generates output (e.g., weekly reports).

Pipeline + Generator + Reviewer – end‑to‑end document production with quality gates.

Engineering Best Practices

Keep SKILL.md instruction bodies under 500 lines; move extensive details to references/ and link via Markdown.

Use clear heading hierarchy (H1 for the Skill name, H2 for major sections, H3 for sub‑sections) to aid the model’s attention.

Store each Skill in its own Git repository or monorepo subdirectory to leverage version control, diff, blame, and CI pipelines.

Include tags, release notes, and semantic versioning in the YAML front‑matter for easy discovery and rollback.

Adopt data‑driven evaluation (Evals) that measures functional correctness, security, performance (latency and token cost), and cost per call.

Security Considerations

Executable scripts are the biggest attack surface. The system must sandbox script execution, enforce least‑privilege permissions, and audit all script outputs. Evaluation should include a security checklist to prevent malicious code from running on user machines.

Version‑Control Integration

Skills naturally fit into Git workflows: code review, CI testing, tagging, and release management ensure quality and traceability. Continuous evaluation pipelines can automatically run functional tests and benchmark token usage for each Skill version.

Evaluation‑Driven Iteration

Regular Evals (functional, security, performance, cost) guide Skill improvement. By measuring whether a Skill solves the intended problem, developers can decide if the Skill adds genuine model capability or merely codifies existing manual processes.

Overall, the progressive‑disclosure architecture, composable design, and disciplined engineering practices enable hundreds of Skills to be managed efficiently without overwhelming the LLM context.