The open standard for teaching AI agents reusable, modular capabilities
Agent Skills are a simple, open format for giving AI agents new capabilities and domain-specific expertise. Each skill is a directory containing at minimum a SKILL.md file — YAML frontmatter describing the skill plus Markdown instructions the agent follows. Optional subdirectories hold scripts, reference docs, and templates. The agent discovers installed skills at startup, sees only lightweight metadata, and loads full instructions only when it decides a skill is relevant to the current task.
Think of it as an onboarding guide for an AI colleague. Instead of cramming every possible instruction into one bloated system prompt, you package domain knowledge into discrete, reusable modules. The agent stays lean until it actually needs the expertise — then loads just what's required. Anthropic published the specification as an open standard on 18 December 2025 at agentskills.io ↗, and within weeks it was adopted by OpenAI Codex, Gemini CLI, GitHub Copilot, Cursor, and dozens of other tools.
Agents are capable generalists, but they don't know your workflows, security checks, or domain edge cases. Loading everything upfront wastes tokens and degrades performance as context fills with irrelevant instructions.
Skills package instructions, scripts, and reference material into self-contained directories. The agent sees skill names and descriptions at startup (~50–100 tokens each) and loads full instructions only when triggered.
A skill written for Claude Code works identically in OpenAI Codex, Gemini CLI, GitHub Copilot, and every other platform implementing the spec. Portable, version-controlled, and sharable across teams.
Agent Skills solved a problem every AI tool vendor had independently: how to give agents specialised knowledge without wrecking context window efficiency. The speed of adoption — from a single vendor's internal pattern to an industry-wide open standard in under six months — signals that this format hit a genuine architectural nerve.
MCP (Model Context Protocol) is excellent for connecting agents to external APIs, databases, and live services — it handles tool-calling and structured data retrieval. Agent Skills solve a different problem: packaging procedural knowledge, workflows, and instructions that the agent should follow. MCP gives agents tools to call. Skills give agents expertise to apply. In practice, the two are complementary — a skill can reference MCP servers, and many production workflows use both.
Agent Skills are built on two core engineering principles: progressive disclosure (load information in tiers, not all at once) and token intentionality (strictly control what enters, exits, and never touches the context window). Here are the key mechanics.
At startup, the agent reads only YAML frontmatter — name and description — from every installed skill. This is the Discovery tier. When the agent decides a skill is relevant, it loads the full SKILL.md body (Activation, recommended under 5,000 tokens). Supporting scripts and reference files load only during Execution. This means you can install dozens of skills with negligible context cost.
Every skill starts with a SKILL.md file. YAML frontmatter declares name, description, optional license and metadata. The Markdown body contains the instructions the agent follows when the skill activates. The spec recommends keeping the body under 500 lines.
--- name: api-security-reviewer description: Reviews API code for security vulnerabilities. Use when reviewing backend code or APIs. license: Apache-2.0 --- # API Security Review Analyze code for auth issues, injection attacks, data exposure...
A common mistake: writing goals in SKILL.md but relying on the LLM to figure out execution via generic tools. If an agent uses a default web fetcher, it can burn 8,000+ tokens on a single HTML page. A targeted Python or Bash script in scripts/ can filter noise, parse structured data, and return clean JSON — cutting token consumption by up to 90%. Pre-making logical decisions in code means the LLM doesn't waste compute figuring it out on the fly.
Skills can bundle executable scripts (Python, Bash, Node, etc.) that the agent runs in a sandbox. These scripts handle operations that benefit from deterministic execution — sorting, parsing, data transformation, API calls — rather than burning tokens on tasks code handles better. Anthropic's own PDF skill includes a Python script that extracts form fields without loading either the script or the PDF into context.
The Agent Skills standard has been adopted across the AI coding and agent ecosystem at a pace reminiscent of MCP's earlier spread. The specification lives at agentskills.io, maintained by Anthropic and open to community contributions. Here's the landscape.
The three major model vendors all support SKILL.md natively. Claude Code pioneered the format, OpenAI adopted it for Codex, and Google's Gemini CLI implements full progressive disclosure with consent-based activation.
Microsoft adopted Agent Skills as a first-class feature in GitHub Copilot and VS Code. Cursor, one of the most popular AI-native IDEs, supports the standard alongside its existing rules system. Skills created in any tool are portable.
A growing ecosystem of directories indexes community and official skills from GitHub repositories. SkillsMP claims 500,000+ indexed skills. Security-focused directories like SkillsDirectory.com scan for prompt injection and credential theft.
| Need | Use This | Why |
|---|---|---|
| Repeatable workflow with domain logic | Agent Skill | Packages instructions + scripts the agent loads on demand. Portable across platforms. |
| Connect to external API or service | MCP Server | Structured tool-calling protocol for live data sources. Handles auth, schemas, streaming. |
| Project-wide coding conventions | CLAUDE.md / GEMINI.md | Always-loaded context for persistent project rules. Skills complement these for specialised tasks. |
| One-off explicit command | Slash Command | User-invoked, deterministic triggers. Skills are model-invoked based on context matching. |
Skills are being used across engineering, documentation, compliance, and creative workflows. These are real patterns from the community and official skill repositories.
Skills that run structured review passes checking for auth issues, injection vectors, and code quality — then fix problems before presenting code to the developer. Anthropic's official simplify skill does this natively.
Skills package brand guidelines, templates, and design tokens so every generated document, presentation, or report follows organisational standards without re-explaining them each session.
Instead of the agent fetching entire HTML pages (8,000+ tokens), a bundled script filters out scripts, styles, and nav — returning only structured data. Pre-defining CSS selectors in the script eliminates per-run discovery costs.
Git release skills generate changelogs, tag versions, and create PRs following team conventions. Firebase skills scaffold apps with auth and database configuration pre-wired to best practices.
Skills for MDR compliance, SOC2 preparation, and accessibility auditing (WCAG 2.2) encode regulatory checklists and verification workflows that the agent applies consistently across code and documentation.
Skills that query databases, run analysis scripts, and produce comparative reports — with bundled schema references so the agent doesn't need to rediscover data structures on every invocation.
Agent Skills evolved from Anthropic's internal tooling for Claude Code into the fastest-adopted open standard in the AI agent space.
Anthropic develops skills as an internal mechanism for Claude Code — structured folders of instructions that Claude loads dynamically to improve performance on document editing, code generation, and specialised tasks.
Anthropic publishes its engineering guide on context engineering for agents, establishing the theoretical foundation for progressive disclosure and token-efficient agent architectures. Released alongside Claude Sonnet 4.5.
Anthropic's engineering blog describes presenting tools as a filesystem the model can explore incrementally — the architectural pattern that skills formalise.
On 18 December 2025, Anthropic publishes Agent Skills as an open standard at agentskills.io with an Apache 2.0 code license and CC-BY-4.0 documentation license. The specification repo moves to github.com/agentskills/agentskills.
OpenAI adopts the SKILL.md format for Codex CLI. Google's Gemini CLI implements full progressive disclosure. GitHub Copilot, Cursor, VS Code, OpenCode, and Amp all add native support. Community marketplaces like skills.sh and SkillsMP launch.
500,000+ skills indexed across public marketplaces. Google publishes official Gemini API skills with evaluation data showing 87–96% accuracy improvement. Security scanning becomes standard — Cisco researchers flag exfiltration risks, driving the emergence of security-first directories.
Skills are not always the answer. Here's an honest assessment of when they add value and when they add friction.
You repeat the same prompt patterns across conversations — code review checklists, release workflows, data analysis pipelines. Skills eliminate prompt repetition.
You need consistent, deterministic outputs — brand compliance, regulatory checks, security audits — where bundled scripts handle the repeatable logic.
Your team shares domain knowledge that new hires (or new agent sessions) need. Skills act as version-controlled onboarding docs for AI colleagues.
You work across multiple AI tools and want portable capabilities. A skill written for Claude Code also works in Codex, Gemini CLI, and Copilot.
Your task is genuinely one-off. Writing a skill for something you'll do once is overhead — just use the prompt directly.
You need real-time data from external services. Skills aren't API connectors — use MCP servers for live data integrations. Skills can reference MCP, but they don't replace it.
Your instructions are short enough for CLAUDE.md or GEMINI.md. If the guidance fits in persistent project context without bloating it, a skill adds unnecessary indirection.
You're working in a constrained environment without filesystem access. Skills require directory structures — they don't work in environments that can't read local files.
Agent Skills represent the strongest signal yet that AI agent workflows are converging on composable, modular architectures rather than monolithic prompt engineering. The open standard model — Apache 2.0 licensed, cross-platform by design — mirrors the MCP playbook that proved effective for tool integration. For South African businesses evaluating AI agent adoption, skills lower the barrier meaningfully: expertise can be packaged once and deployed across whichever tools the team already uses, avoiding vendor lock-in. The security surface is real, though — community skills need vetting, and the ecosystem's maturity varies. Treat skills like any open-source dependency: inspect before installing.
Large organisations should evaluate skills as a mechanism for encoding internal workflows, compliance requirements, and domain expertise into portable, auditable packages. The key advantage: skills are version-controlled text files, making them compatible with existing governance and change management processes. Start with high-repetition workflows — code review standards, document templates, deployment checklists — where the ROI is immediate and measurable.
Small teams and agencies get disproportionate value from skills because they eliminate the "explain everything every session" tax. Package your client delivery process, your testing workflow, your documentation standards into skills that any team member's agent can use consistently. The cross-platform portability matters here: if one developer uses Claude Code and another uses Cursor, the same skills work for both.
Building skills is one of the best ways to learn context engineering — the discipline of managing what enters an LLM's context window and when. Writing a SKILL.md forces you to think about progressive disclosure, token budgets, and the boundary between what the model should reason about versus what code should handle deterministically. Start with the official Anthropic skills repo and the spec at agentskills.io.
Agent Skills Specification — The canonical format spec ↗
agentskills/agentskills — Spec repo, SDK, and documentation ↗
anthropics/skills — Anthropic's official example skills ↗
Equipping Agents for the Real World — Anthropic engineering blog ↗
Agent Skills API Documentation — Claude API integration guide ↗
Claude Code Skills Docs — Building skills for Claude Code ↗
OpenAI Codex Skills — Using skills with Codex CLI ↗
Gemini CLI Skills — Google's implementation ↗
VS Code Agent Skills — GitHub Copilot integration ↗
skills.sh — The Agent Skills Directory ↗
SkillsMP — 500K+ indexed skills with filtering ↗
Skills Directory — Security-scanned skills registry ↗
claude-skills (5.2K★) — 192+ skills for 11 platforms ↗
google-gemini/gemini-skills — Official Gemini API skills ↗
Anthropic Skills Course — Official training on building skills ↗
Agent Skills Specification — agentskills.io · Anthropic Engineering Blog (Jan 2026) · agentskills/agentskills GitHub · Claude API Skills Docs · OpenAI Codex Skills Docs · Gemini CLI Skills Docs · VS Code Agent Skills · Google Developers Blog — Closing the Knowledge Gap (Mar 2026) · Simon Willison — Agent Skills (Dec 2025) · Sam Witteveen — Agent Skills Deep Dive (YouTube) · State of Context Engineering in 2026 — SwirlAI · SkillsMP Marketplace · skills.sh Directory
Content validated March 2026. Agent Skills is an open standard maintained by Anthropic under Apache 2.0 (code) and CC-BY-4.0 (documentation). This is an independent educational explainer by Imbila.AI.
Give this URL to any AI agent — it can fetch the full explainer as structured markdown, no Cloudflare blocking.