Agent Skills are an open standard for packaging instructions, scripts, and resources into folders that AI coding agents discover and use automatically. Write a skill once, and it works across Claude Code, GitHub Copilot, OpenAI Codex, Cursor, and 30+ other agents. Think of them as onboarding guides for your AI pair programmer — except the new hire reads and follows them instantly.

AI coding agents are becoming remarkably powerful. Claude Code navigates full computing environments. Copilot writes PRs autonomously. Codex runs in sandboxed VMs. But as these agents grow more capable, a gap widens: they're generalists operating in a world that demands specialists.

Your agent doesn't know your API conventions, your deployment checklist, or your team's testing patterns. So you paste that context in. Again. And again. Every new session, every new teammate onboarding their own agent — the same tribal knowledge gets re-explained.

Maybe you've tried workarounds. A giant CLAUDE.md or .github/copilot-instructions.md stuffed with everything. But those load into every conversation whether relevant or not, eating up your context window with database migration instructions when you're building a React component.

The core insight from Anthropic's engineering team: as agents become more powerful, we need more composable, scalable, and portable ways to equip them with domain-specific expertise. This led to the creation of Agent Skills — organized folders of instructions, scripts, and resources that agents discover and load dynamically. Skills transform general-purpose agents into specialized agents that fit your needs, the way an onboarding guide transforms a smart new hire into a productive team member.

A skill is a directory. Inside it sits a SKILL.md file — the only required component — plus optional supporting directories:

The SKILL.md file has two distinct parts:

The frontmatter tells the agent what the skill does and when to activate:

Only name and description are required. This metadata is always loaded into the agent's system prompt at startup (~100 tokens per skill). It's the routing layer — the agent reads these to decide which skills are relevant before loading anything else.

The markdown body tells the agent how to do it:

The body is loaded only when the skill triggers (<5k tokens recommended). The agent reads it into context only after deciding this skill matches the current task.

Scripts, references, and assets are loaded on-demand as the agent needs them during execution. The token budget here is effectively unlimited because files load individually — a skill can bundle a dozen reference docs and the agent pulls in only the one it needs.

Here's how the three levels work together:

*Unlimited because agents load files individually — only what's needed enters context.

No SDK to install. No runtime to manage. No complex configuration. Markdown and folders — tools every developer already knows.

Skills use progressive disclosure to manage context efficiently. The process has three stages:

This three-stage flow is what makes skills lightweight at rest and powerful when triggered. You can have dozens installed without bloating your context window — the agent pulls in only what the current task demands.

The three-level loading model described above isn't just an implementation detail — it's the core design principle that makes skills scalable. You can install 50 skills and the metadata scan costs roughly 5,000 tokens total. Only the skill relevant to your current task loads its full instructions. And bundled files load one-at-a-time, on demand.

This has a direct implication for how you author skills:

Because Level 1 (metadata) is the routing layer, the description field determines whether your skill fires at the right time. It's not a title — it's a routing rule.

Vague (bad): description: Helps with testing

Specific (good): description: Generate and run Playwright browser tests for web applications. Use when asked to create E2E tests, browser-based tests, or UI tests. Includes setup, selectors, and CI configuration.

Include trigger keywords users are likely to say. Be explicit about when the skill should and should not activate. This single field determines whether your skill is useful or just noise.

The agent customization landscape has gotten crowded. Here's how skills fit alongside the other options:

Custom Instructions (.github/copilot-instructions.md, CLAUDE.md, .cursorrules) are always-on. They load into every conversation regardless of context. Best for universal coding standards, formatting rules, and project-wide conventions.

Skills are on-demand. They load only when relevant. Best for specialized capabilities, multi-step workflows, domain expertise, and tasks that need scripts or reference materials.

MCP Servers provide runtime access to external tools — databases, APIs, file systems, third-party services. They give agents the ability to do things.

Rules / AGENTS.md define project-wide conventions that any agent should follow. Similar to custom instructions but positioned as a cross-agent standard.

The mental model that clarifies everything: MCP gives your agent access to tools and data. Skills teach your agent what to do with those tools and data. Instructions set the baseline. Skills provide the specialization.

If you find yourself writing instructions that only apply some of the time — say, your database migration review checklist that's irrelevant when someone's building UI — that's a skill waiting to be extracted.

The Agent Skills format was originally developed by Anthropic internally for Claude. In late 2025, they released it as an open specification at agentskills.io, published the reference implementation at github.com/agentskills/agentskills, and opened it to community contributions.

What happened next moved fast. Within weeks, OpenAI added skills support to Codex. GitHub adopted the standard for Copilot. Cursor, Windsurf, Cline, Goose, Gemini CLI, Roo Code, Amp, and dozens of other agent platforms followed. Vercel built npx skills — a CLI package manager that installs skills across 37+ agents. Today, the Anthropic skills repository has over 70,000 GitHub stars.

The result: a skill you write today works across every major coding agent. You're not locked into any vendor. This portability is what makes the time investment in writing good skills worthwhile — you write once and the returns compound across every tool in your workflow.

Partner-built skills from companies like Atlassian, Figma, Canva, Stripe, Notion, and Zapier are already available. Mintlify auto-generates skill files from documentation sites and serves them at /.well-known/skills/default/skill.md. The ecosystem is converging on skills as the standard way to package agent knowledge.

The applications span every part of the development lifecycle:

Domain expertise. Package your team's specialized knowledge — your API design patterns, your deployment checklist, your security review process — into reusable instructions that any team member's agent can access.

Repeatable workflows. Turn multi-step tasks into consistent, auditable processes. Every code review follows the same checklist. Every migration gets the same safety checks. Every component scaffold includes the same file structure.

New capabilities. Skills can include executable scripts that give agents abilities they don't have natively — PDF processing, image manipulation, complex data transformations — with deterministic, repeatable results.

Organizational knowledge capture. The tribal knowledge that lives in senior developers' heads, your team's Notion wiki, your on-call runbooks — all of it can become a skill that makes the whole team more effective.

Because skills can include executable scripts and arbitrary assets, they deserve the same scrutiny you'd give any software dependency. Anthropic's engineering team recommends treating skills like packages:

The simplicity of the format (it's just markdown and folders) makes manual review feasible. But as community-contributed skills proliferate, security diligence becomes essential for keeping your agent environment safe.

Now that you understand what skills are and why the architecture matters, the next question is practical: how do you actually set them up in your coding agent?

In Part 2, we'll walk through the exact setup process for Claude Code, GitHub Copilot, OpenAI Codex, and Cursor — side by side, with the specific commands, directory paths, and installation methods for each. No other guide on the internet puts all four agents in one place.

What workflow would you turn into a skill first? Reply to this email — I'm collecting the best ideas for Part 3.

📬 Know a developer who keeps re-explaining their codebase to AI? Forward this to them.

Subscribe to AI Native Coding →

References & Further Reading:

This is Part 1 of our 3-part Agent Skills series: