Agent Skills

Agent Skills are modular, reusable capability packages that extend AI agent behavior by bundling domain-specific instructions, workflows, and executable resources into filesystem-based directories. They are a core Harness-Engineering mechanism that transforms general-purpose agents into specialists without rebuilding agents from scratch.

What They Are

• Filesystem-based modules: Each skill is a directory containing a SKILL.md file plus optional bundled resources
• Discoverable by design: Skills register themselves in the agent’s system prompt via lightweight metadata
• Composable: Multiple skills can coexist; agents combine them as needed per task
• Cross-surface: Available in Claude Code, Claude.ai, the Claude API, and the Agent SDK

The Three-Level Loading Model

Skills use progressive disclosure — loading information in stages to preserve Context-Engineering efficiency:

Level	Content	When Loaded	Token Cost
1 — Metadata	YAML frontmatter (name, description)	Always, at startup	~100 tokens per skill
2 — Instructions	SKILL.md body (workflows, best practices)	When skill is triggered by a matching request	Under 5k tokens
3 — Resources	Bundled files and scripts	Only when explicitly referenced	Effectively unlimited

At Level 3, executable scripts run via bash — their code never enters the context window, only their output does. This makes skills far more efficient than having the agent generate equivalent code on demand.

Skills vs. AGENTS.md Files

The key distinction is when context is loaded:

• AGENTS-md-Files: Always loaded into every session; best for universal rules and project-wide conventions
• Agent Skills: Loaded on demand, only when relevant; best for domain-specific workflows that don’t apply to every task

Use AGENTS.md for standing instructions. Use skills for specialized capabilities that should remain dormant until needed.

SKILL.md Format

Every skill requires a SKILL.md file with YAML frontmatter:

---
name: pdf-processing
description: Extract text and tables from PDF files. Use when working with PDFs.
---

The description field drives discovery — it is injected into the system prompt, and the agent uses it to decide whether to activate the skill. Descriptions must be specific and written in third person.

Security Considerations

Skills execute code and invoke tools, so a malicious skill can direct an agent to perform harmful operations. The guidance is clear: treat skills like software packages — only install from trusted sources and audit bundled files before use.

Relationship to the Broader Tooling Ecosystem

Skills sit between AGENTS-md-Files (always-on context) and AI-Plugins (third-party capability extensions). They complement Model-Context-Protocol by providing agent-native capability packaging that doesn’t require external servers.

Related Concepts

• Harness-Engineering
• Context-Engineering
• AGENTS-md-Files
• AI-Plugins
• Model-Context-Protocol
• AI-Coding-Agent-Architecture
• Agent-Harness-Components
• Progressive-Disclosure-Context
• Kiro-Powers

Sources

• Anthropic (2025). “Agent Skills Overview.” platform.claude.com. Retrieved March 2026. Available: https://platform.claude.com/docs/en/agents-and-tools/agent-skills/overview

  • Source for the three-level loading model, SKILL.md format requirements, cross-surface availability, and security considerations

• Anthropic (2025). “Skill Authoring Best Practices.” platform.claude.com. Retrieved March 2026. Available: https://platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices

  • Source for description writing guidelines, progressive disclosure patterns, and evaluation-driven development approach

• Anthropic (2025). “Equipping Agents for the Real World with Agent Skills.” claude.com/blog. Retrieved March 2026. Available: https://claude.com/blog/equipping-agents-for-the-real-world-with-agent-skills

  • Design rationale: solving scalability of domain expertise without building separate custom agents; key innovation of separating metadata, instructions, and executable code

• Horthy, Dex (2026). “Skill Issue: Harness Engineering for Coding Agents.” HumanLayer Blog. Available: https://www.humanlayer.dev/blog/skill-issue-harness-engineering-for-coding-agents

  • Practitioner perspective on skills as a progressive disclosure mechanism; contrast with MCP servers and CLAUDE.md; security risks of public skill registries

Note

This content was drafted with assistance from AI tools for research, organization, and initial content generation. All final content has been reviewed, fact-checked, and edited by the author to ensure accuracy and alignment with the author’s intentions and perspective.