Agent Skills — Specialization Class: Packaging Capabilities on Demand

In Part 1, CLAUDE.md addresses the general context — what Claude needs to know at all times. However, there are things you do not want to stuff into the context all the time: a 40-step financial report generation process, how to write in a brand voice, the procedure for filling out a complex PDF form. Loading everything into each session wastes tokens and creates noise.

Agent Skills is the solution: packaging one specialization into a module, and Claude only "unpacks" it when the task truly requires it. This is an important mindset shift — from "stuffing as many prompts as possible" to "packaging capabilities into modules."

What is a Skill

In its simplest form, a skill is a directory containing a SKILL.md file (Anthropic Engineering). This directory may also include scripts, reference documents, and resources. Anthropic likens a skill to onboarding documentation for a new employee: it transforms a general agent into a specialist for a specific task.

The standard structure according to the open specification (agentskills.io):

skill-name/
├── SKILL.md          # Required: metadata + instructions
├── scripts/          # Optional: executable code
├── references/       # Optional: reference documents as needed
└── assets/           # Optional: templates, images, data

SKILL.md and Required Frontmatter

SKILL.md must begin with a YAML frontmatter block containing two mandatory fields (agentskills.io — specification):

The description field is extremely important: it is the basis for Claude to decide for itself when to activate the skill. Writing an ambiguous description will result in the skill never being called at the right time.

Minimal example:

---
name: pdf-form-filler
description: Fill and extract fields in a PDF file. Use when the user
  needs to fill out a PDF form or read fields from a PDF file.
---
# Fill PDF Form
1. Run `scripts/extract_fields.py` to get the list of fields.
2. Map user data to the corresponding fields.
3. Refer to `references/FORMS.md` when encountering a complex form.

Core Principle: Progressive Disclosure

This is the idea that powers Skills. Information is loaded in three layers, only when needed (Anthropic Engineering):

1. Metadata (very light). At startup, Claude only loads the name + description of all skills into the context — enough to know when which skill is needed. The token cost for each skill is very small.
2. Instructions (when relevant). When a task matches a skill, Claude reads the entire body of SKILL.md into the context.
3. Resources (when actually used). Files in references/, scripts/, assets/ are only read or executed when truly needed.

Amazing Consequence: You Can Install Many Skills While Keeping Token Costs Low When Not In Use

This is a key differentiator compared to stuffing all instructions into one gigantic CLAUDE.md. Recommendation: keep SKILL.md concise (usually under ~500 lines), separating longer sections into reference files.

Skills Can Contain Code — A Unique Strength

A skill can include scripts (Python, Bash, JS...) for Claude to run as a tool. The reason: many operations (sorting lists, analyzing PDFs, calling APIs) executed via code are cheaper and more deterministic than letting the model "generate tokens." An official example is a PDF processing skill that includes a Python script to read and extract fields — without needing to load both the script and the PDF into context (Anthropic Engineering).

This is a subtle yet significant difference: a skill is not just "instruction text"; it can be a pre-packaged execution capability.

Pre-built vs Custom, and Portability

• Pre-built (provided by Anthropic): read/create Excel, PowerPoint, Word, and fillable PDFs — integrated into the file creation features of Claude apps (Anthropic — Skills).
• Custom (written by you): there is a skill called skill-creator that provides interactive guidance for building new skills.
• Portable — "write once, use everywhere": the same format runs on Claude apps, Claude Code, API, and Claude Agent SDK. Agent Skills are also published as an open standard for cross-platform use (agentskills.io).

Installation in Claude Code: drop into ~/.claude/skills/ (personal) or install via a plugin from the marketplace, then share with your team through version control. In the API, skills are managed via the endpoint /v1/skills and require the Code Execution Tool (beta) as the execution environment (Claude Docs — Agent SDK Skills).

Skills vs Slash Commands vs Subagents vs MCP

These four concepts are often conflated. Each solves a different problem (Anthropic — Skills explained):

There is a "mnemonic" to help remember: **Skills change behavior, Subagents protect context, MCP adds capabilities, Hooks ensure a deterministic action runs.** And another way to say it from Anthropic: Projects/CLAUDE.md say "this is what you need to know," Skills say "this is how to do it"; MCP connects data, Skills teach what to do with the data (Skills explained).

Note on overlap: a skill can be triggered via a slash command or automatically matched — the two mechanisms are not mutually exclusive.

Best Practices for Creating Skills

From the technical guide by Anthropic (Engineering — Agent Skills):

• Start with evaluation (eval-first). Identify where the agent is underperforming, then write a skill to address that specific issue — rather than writing skills based on intuition.
• Structure for scalability. As SKILL.md expands, separate detailed parts into references/.
• Think from Claude's perspective. Pay attention to name and description, as these are the basis for the skill to be activated at the right time.
• Iterate with Claude. Ask Claude to summarize commonly used patterns into skills.

Security: Only install skills from trusted sources

Since skills carry both code and instructions, a malicious skill could cause Claude to leak data or act unexpectedly. The principle: only install skills from trusted sources, and thoroughly audit files/scripts/dependencies along with any external network instructions before use. This is the same "supply chain" spirit that we will encounter in Plugins (Post 5).

Three common misconceptions

• "Enabling multiple skills will consume context." — Incorrect. Thanks to progressive disclosure, initially only metadata (~dozens to hundreds of tokens/skill) is loaded.
• "Skill = slash command / = subagent / = MCP." — Incorrect. See the table above.
• "Skills are only used in Claude Code." — Incorrect. Skills are portable across apps, Code, API, and Agent SDK.

Summary & Next Steps

Agent Skills package expertise into a directory module (SKILL.md + resources), loaded according to the principle of progressive disclosure to be both powerful and token-efficient, potentially including code for execution, and portable throughout the Claude ecosystem.

However, both CLAUDE.md and Skills are guidelines — Claude strives to adhere to them but does not guarantee absolute compliance. When you need an action to definitely occur or definitely be blocked (formatting code, security scanning, prohibiting dangerous commands), you need a definite mechanism. That is Hooks — Post 3.

References

• Anthropic Engineering — Equipping agents for the real world with Agent Skills: https://www.anthropic.com/engineering/equipping-agents-for-the-real-world-with-agent-skills
• Anthropic — Introducing Agent Skills: https://www.anthropic.com/news/skills
• Anthropic — Skills explained (comparison of Skills/Commands/MCP): https://claude.com/blog/skills-explained
• Agent Skills — Open specification: https://agentskills.io/specification
• Claude Docs — Agent Skills in the SDK: https://docs.claude.com/en/api/agent-sdk/skills
• AZDIGI — Guide to Agent Skills (Vietnamese): https://azdigi.com/blog

Post 2/7 in the "Agent Development Toolkit with Claude" series. Content reinterpreted from the original document by Anthropic. Previous ← Post 1: CLAUDE.md · Next → Post 3: Hooks.