back

Agent Skills: Definitions, Packaging, Dynamic Loading, and Composability

Overview

Agent Skills emerged in late 2025 as a filesystem-native way to give AI agents specialized, reusable capabilities. Anthropic introduced the pattern in October 2025 [1], and on December 18, 2025 promoted it to the open Agent Skills standard — now hosted at agentskills.io and adopted by Claude, Kiro, Cursor, GitHub Copilot, Gemini CLI, Goose, Amp, and VS Code among others [2][3][6].

A skill is deceptively simple: a directory containing a SKILL.md file with YAML frontmatter (name + description) and a Markdown body of instructions. Optional subfolders hold reference docs, scripts, and templates. What makes the pattern powerful is not the format but the runtime behavior around it — progressive disclosure, dynamic loading, and composability — which together solve the "context rot" problem that plagues tool-heavy agents [1][4][8].

This document surveys the current (2026) landscape: the open standard's shape, Anthropic's original design, Kiro's implementation (including its "Powers" variant), how skills compare and compose with MCP, and the operational patterns teams are converging on.

---

1. What a Skill Is

Anthropic's definition is minimal:

A skill is a directory containing a SKILL.md file that contains organized folders of instructions, scripts, and resources that give agents additional capabilities. [1]

Concretely, the smallest valid skill is:

pr-review/ └── SKILL.md

With the required frontmatter:

--- name: pr-review description: Review pull requests for code quality, security issues, and test coverage. Use when reviewing PRs or preparing code for review. --- ## Review checklist 1. Check for vulnerabilities, injection risks, exposed secrets 2. Verify edge cases and failure modes are handled 3. Confirm new code has appropriate tests ...

Only two fields are required in the frontmatter across every implementation surveyed: name (lowercase, hyphens, ≤64 chars) and description (≤1024 chars, third-person, stating when the skill should activate) [5][8]. Some ecosystems add optional fields — Kiro Powers and several community registries extend with displayName, keywords, author, license, and version [9] — but an agent that respects only name/description will still load any compliant skill, which is why cross-tool portability works.

Anatomy of a richer skill

cdk-deploy/ ├── SKILL.md # entry point, loaded on trigger ├── references/ │ ├── stack-patterns.md # loaded only when SKILL.md links to it │ └── troubleshooting.md ├── scripts/ │ └── synth_check.py # executed, not read into context └── assets/ └── template.yaml

The three content types — instructions (Markdown), scripts (executable code), and resources (templates, examples, data) — map to three different consumption modes: read into context, run deterministically, or reference by path [7][10].

---

2. Packaging: Anthropic's Reference Format vs Kiro Skills vs Kiro Powers

The open standard is intentionally thin. Each host layers its own conventions for discovery and lifecycle.

2.1 Anthropic Claude Skills

• Location on disk: bundled in the Claude.ai UI, mounted at /mnt/skills/ in code-execution sandboxes, or uploaded via the Skills API.
• Trigger: Claude's system prompt is pre-populated with (name, description) pairs for every installed skill at session start. When a user message matches, Claude uses a Bash-style read to load the full SKILL.md [1].
• Execution environment: a VM with a filesystem + code interpreter, enabling skills to ship Python/Node scripts that Claude invokes instead of reading [4][7].
• Distribution: github.com/anthropics/skills (first-party), and a growing community ecosystem (Smithery, Playbooks, OpenSkills, Apify Agent Skills) [3][6].

2.2 Kiro Skills

Kiro adopts the Agent Skills standard unchanged [9]. The host-specific behavior is:

The skill:// URI scheme is Kiro-specific plumbing for binding skills to custom agents; the content itself stays portable [9].

2.3 Kiro Powers — a superset, not a replacement

Announced alongside Kiro 0.9 (late 2025), Powers are Kiro's richer package format that bundles skills + tools + MCP servers into one deployable unit [9][7 Kiro]. The relationship:

• Every Power contains a POWER.md that is format-compatible with SKILL.md.
• Powers additionally bundle MCP server configs, so a Power can ship a skill plus the external tools it depends on (AWS API MCP server, database connectors, etc.) [9].
• Converting a Power to a portable Skill is mechanical: drop the MCP config, rely on host-provided tools, rename POWER.md → SKILL.md [9].

flowchart LR
    subgraph OpenStandard["Open Agent Skills Standard"]
      SKILL[SKILL.md + refs + scripts]
    end
    subgraph KiroPower["Kiro Power (superset)"]
      POWER[POWER.md] --> MCP[MCP server configs]
      POWER --> TOOLS[Bundled tool defs]
    end
    SKILL -->|runs in| Claude
    SKILL -->|runs in| Kiro
    SKILL -->|runs in| Cursor
    SKILL -->|runs in| Copilot
    POWER -->|Kiro-only| Kiro
    POWER -.degrades to.-> SKILL

---

3. Dynamic Loading and Progressive Disclosure

Progressive disclosure is the architectural claim that makes skills scale. Anthropic describes three levels [1][4][11]:

sequenceDiagram
    participant User
    participant Agent
    participant FS as Skill Directory
    Note over Agent: Startup: load (name,desc) of all skills
    User->>Agent: "Deploy my CDK stack to staging"
    Agent->>Agent: Match against cdk-deploy description
    Agent->>FS: read cdk-deploy/SKILL.md
    FS-->>Agent: full instructions
    Agent->>FS: read references/stack-patterns.md
    FS-->>Agent: staging-specific patterns
    Agent->>FS: exec scripts/synth_check.py
    FS-->>Agent: exit 0, templates valid
    Agent->>User: Deployment plan + proceeds

The practical consequence: the total context a skill can carry is effectively unbounded, because only the slices relevant to the current task enter the context window [1]. A 400-page compliance manual can live in a skill and cost ~80 tokens per session until the moment a compliance question is asked.

This is why commentators describe Skills as a shift "from retrieval to skills" [10] — static RAG pulls chunks based on vector similarity with no notion of workflow; skills pull coherent procedural bundles based on intent signals the skill author controls via the description field.

Trigger design is the hard part

Since the description is the only thing the agent sees for 99% of skills during a session, it's the entire API surface. Community guides [5][8][11] converge on:

• Write in third person: "This skill should be used when…" not "Use me when…".
• Name concrete actions and artifacts the user will mention ("reviewing PRs", "deploying CDK", "writing ADRs").
• Avoid marketing adjectives ("comprehensive", "powerful") — they never match user phrasing.
• Disambiguate overlapping skills with distinguishing keywords, or the wrong one will fire.

---

4. Composability

Skills compose along three axes: with each other, with tools/MCP, and with sub-agents.

4.1 Skill-to-skill composition

An agent can load multiple skills in a single turn. The Anthropic team reports production workflows where a PDF skill, a brand-style skill, and a redlining skill all fire on one "produce the quarterly report" request [1][11]. Because each skill is an independent directory, there is no central composition graph — the agent's planner decides what to pull.

Practical patterns seen in the wild:

• Layered skills: a company-conventions skill always activates for repo work; a ecs-express skill layers on top for deployment tasks [9].
• Router skills: a top-level skill whose body tells the agent "if the task looks like X, also load skill Y" — effectively a hand-authored dispatch table.
• Namespace packages: directories of related skills (e.g. firecrawl-* in Kiro) where each sub-skill is independently triggerable but shares vocabulary in descriptions.

4.2 Skills + MCP

Through early 2026 the community debate settled: Skills and MCP are complementary, not competing [12][13][14][15].

The emerging architectural guidance [13][14][15]: MCP fetches and acts; Skills orchestrate and format. A report-generation workflow might use MCP servers to pull live metrics from Snowflake and Datadog, while a Skill dictates the sectioning, tone, and rollup logic.

Anthropic's /v1/messages API now supports both in the same request, and a Skill can instruct the agent to call specific MCP tools, effectively making Skills programs and MCP servers their syscalls [13][15].

4.3 Skills + sub-agents

In Kiro, Claude Code, and other agentic IDEs, skills are often delegated to subagents that run with isolated context windows [9]. A sub-agent launched for "run the full PR review" can load the pr-review skill without inflating the parent conversation — the parent gets only the final verdict.

flowchart TD
    MainAgent[Main Agent - small context]
    MainAgent -->|spawns| SubA[Sub-agent: security-review<br/>loads pr-review + sec-checklist skills]
    MainAgent -->|spawns| SubB[Sub-agent: test-coverage<br/>loads coverage-audit skill]
    SubA -->|verdict| MainAgent
    SubB -->|verdict| MainAgent

This is the pattern Kiro's docs explicitly recommend for "complex, multi-step tasks" [9], and it's how large skill libraries stay useful without overwhelming any single context window.

---

5. Distribution and the Ecosystem in 2026

• Anthropic skills repo (github.com/anthropics/skills): first-party examples (PDF editing, Excel, PowerPoint, Word) [1].
• agentskills.io: canonical spec site since Dec 2025 [2].
• Kiro Powers marketplace (github.com/kirodotdev/powers): Kiro-specific but many Powers have Skill-compatible cores [9].
• Community registries: Smithery, Playbooks, OpenSkills, Apify Agent Skills — all distribute plain skill directories installable via npx or git clone into .claude/skills/, .kiro/skills/, etc. [3][6][8].
• Cross-tool support: by Q1 2026, Claude Code, Cursor, Amp, Goose, GitHub Copilot, Gemini CLI, Kiro, and VS Code all load SKILL.md directories [3][6]. A single skill can be symlinked into multiple tool directories and behave identically.

Enterprise adoption skews toward version-controlling .kiro/skills/ (or equivalent) alongside application code, so that team conventions ship with the repo rather than in private dotfiles [9][14].

---

Key Takeaways

1. Skills are folders, not frameworks. The spec fits on a napkin: a SKILL.md with name + description in YAML frontmatter, plus whatever files you want the agent to read or execute.
2. Progressive disclosure is the point. Three levels — metadata at startup, body on trigger, referenced files/scripts on demand — let a skill carry unbounded context at a fixed session cost.
3. The description field is the API. It is the only thing the agent sees until a skill triggers, so it must match user phrasing precisely. Vague descriptions are the #1 cause of skills silently never firing.
4. Skills and MCP are complementary layers. Skills encode how your team works; MCP exposes what external systems can do. Production stacks use both and call MCP tools from within skill instructions.
5. Composability is agent-decided, not graph-defined. Multiple skills can fire per turn, skills can reference other skills, and sub-agents can load skills in isolation — all without central orchestration.
6. Kiro Powers are a compatible superset. Powers bundle skills with MCP server configs and custom tools for one-click Kiro installs, but their skill cores remain portable to the open standard.
7. The standard is open and widely adopted. As of early 2026, Claude, Kiro, Cursor, Copilot, Gemini CLI, Goose, Amp, and VS Code all load the same SKILL.md format. A skill authored once runs everywhere skills are supported.

---

References

[1] Anthropic Engineering — "Equipping agents for the real world with Agent Skills" (Oct 2025). https://www.anthropic.com/engineering/equipping-agents-for-the-real-world-with-agent-skills [2] FinancialContent / TokenRing — "Anthropic Unveils 'Agent Skills' Open Standard" (Dec 25, 2025). https://www.financialcontent.com/article/tokenring-2025-12-25-anthropic-unveils-agent-skills-open-standard-a-blueprint-for-modular-ai-autonomy [3] Editorialge — "Anthropic Agent Skills Open Standard Goes Public" (Dec 2025). https://editorialge.com/anthropic-agent-skills-open-standard/ [4] Kevnu — "Agent Skills Concept Analysis and Usage" (Nov 2025). https://www.kevnu.com/en/posts/claude-agent-skills-deep-dive-a-new-paradigm-for-expanding-ai-agent-capabilities [5] Claudeskill.site — "SKILL.md File Format Complete Guide" (Oct 2025). https://claudeskill.site/en/blog/skill-md-format-en [6] Apify Blog — "Introducing Apify Agent Skills" (2026). https://blog.apify.com/introducing-apify-agent-skills/ [7] Kiro Blog — "Introducing Kiro Powers". https://kiro.dev/blog/introducing-powers/ [8] Verdent — "Claude Skills Documentation: Official Reference" (2025-26). https://www.verdent.ai/guides/claude-skills-documentation [9] Kiro Docs — "Agent Skills" (updated April 2026). https://kiro.dev/docs/cli/skills/ ; John Ritsema — "ECS Express: Agent Skill" (Nov 2025) https://johnritsema.com/posts/ecs-express-skill/ ; Kiro 0.9 release notes https://kiro.dev/blog/custom-subagents-skills-and-enterprise-controls/ [10] Muhammad Shafat (Medium) — "Stop Engineering Prompts, Start Engineering Context: A Guide to the Agent Skills Standard" (2026). https://medium.com/@muhammad.shafat/stop-engineering-prompts-start-engineering-context-a-guide-to-the-agent-skills-standard-bc8e2056f40a [11] Setiya Putra — "Building Skills for Claude: A Practical Guide" (2025). https://setiyaputra.me/blog/building-skills-for-claude-practical-guide [12] Ravi Chaganti — "Agent Skills vs Model Context Protocol — How do you choose?" (2025). https://ravichaganti.com/blog/agent-skills-vs-model-context-protocol-how-do-you-choose/ [13] Velt.dev — "Agent Skills vs MCP Guide" (Feb 2026). https://velt.dev/blog/agent-skills-vs-mcp-comparison-guide [14] Maiagent — "MCP and Agent Skills: Enterprise AI Integration" (2026). https://maiagent.ai/en/blog/mcp-agent-skills-enterprise-ai-integration [15] Maxim AI — "The Skills vs MCP Debate: Understanding Two Layers of the Same Stack" (2025-26). https://www.getmaxim.ai/blog/the-skills-vs-mcp-debate-understanding-two-layers-of-the-same-stack/ [16] MCPJam — "Progressive Disclosure Might Replace MCP (Claude Agent Skills)" (Oct 2025). https://www.mcpjam.com/blog/claude-agent-skills

Content was rephrased for compliance with licensing restrictions.