Agent Skills: Open Standard for AI Agent Instruction Files

You ask your AI coding assistant to build a REST API endpoint, and it names your routes inconsistently, skips validation, and uses plain JavaScript instead of TypeScript. Again. You could type out the same instructions for the hundredth time—or you could hand the agent a single skill.md file that tells it exactly how you work, once, and have it apply those rules everywhere. That's the promise of Agent Skills: a simple, open standard for AI agent instruction files that works across Claude, Cursor, VS Code, and a growing list of tools. No vendor lock-in. No repeated prompts. Just a folder with a file that trains your AI to think like your team.

Quick Answer

Agent Skills are standardized instruction files (skill.md) inside named folders that tell AI coding assistants how to handle specific tasks. They use progressive disclosure—the AI reads only the skill name and description first, then loads full instructions only when needed. This format works across Claude Code, Cursor, GitHub, VS Code, Goose, Leda, and others as an open community-driven standard.

What Are Agent Skills?

An agent skill is a plain folder containing a single file named skill.md. That file is the instruction manual for an AI agent. It tells the agent how to perform a specific task—from API design to code review to documentation generation—in a way that matches your team's conventions.

The folder structure is dead simple:

api-design/
└── skill.md

The skill.md file has two parts:

• Metadata header: A YAML-style block with the skill's name and a short description. The AI reads this first to decide if the skill is relevant.
• Full instructions: The rest of the file, with step-by-step guidance, rules, examples, and references to helper files or scripts.

Think of it like a recipe card. The card's title and a one-line summary sit on top—that's the metadata. The detailed cooking steps, ingredient list, and special techniques are on the back. A chef (the AI) skims the front to decide if it's the right dish, then flips to the back only when the recipe is needed.

This structure is intentional. It's not code—any developer can create a skill without learning a new language or framework. You write plain text instructions in Markdown. The AI handles the rest.

Why This Matters for Developers

AI agents are powerful, but they are generalists by default. They don't know your company's TypeScript style guide, your preferred API response format, or your logging conventions. Without instruction files, you spend prompting cycles repeating the same requirements. Agent Skills encode that knowledge into reusable, portable files.

Without Agent Skills	With Agent Skills
Manually prompt each time	Write rules once
Inconsistent AI output	Consistent results
Platform-specific customization	One skill works everywhere
Hard to share with team	Git-versioned and shareable

How Agent Skills Work: Progressive Disclosure in Action

The key innovation behind Agent Skills is a design decision called progressive disclosure. Instead of loading every skill's full instructions into the AI's context window when the agent starts—which would quickly consume memory and slow things down—the agent reads only the name and description of each available skill.

Here's how the flow works in practice:

1. Startup Phase: Scan Metadata Only

When an AI agent initializes (for example, when you start a Claude Code session), it scans the skills directory. It opens each skill.md file, reads only the metadata header (name and description), and indexes the skill. No full instructions are loaded. This keeps context windows small and startup time fast.

2. Matching Phase: AI Maps Your Request to a Skill

When you give the AI a task—say, "Build a CRUD API for our user model"—the agent compares the task against the indexed skill descriptions. It looks for semantic matches. If a skill named "API Design" with a description like "Standards for building REST APIs in Next.js with TypeScript and Zod validation" is found, the agent marks it as relevant.

3. Load Phase: Fetch Full Instructions Only When Needed

Only after the AI determines a skill is likely needed does it load the full skill.md content and any referenced files. This is the core of progressive disclosure: the agent doesn't waste context on skills that aren't relevant to the current conversation. It loads exactly what's necessary, nothing more.

4. Execution Phase: Follow the Instructions Step by Step

The AI now has the full instruction set. It follows the rules, applies the conventions, and asks for clarification if the instructions reference a file or step that isn't clear. The skill may include example code, a list of forbidden patterns, or a checklist of required elements. The agent treats these as authoritative.

Quick Fact: Progressive disclosure is why skills are efficient even with hundreds of skill files available. The overhead per file is just a few kilobytes of metadata, not the full instruction text.

Which Tools Support Agent Skills?

The format has been adopted by a surprising number of major tools already. This is not a theoretical standard—it is being used today across the AI coding landscape.

Anthropic's Claude and Claude Code

Claude and Claude Code were early adopters. The skill format is natively supported in Claude Code sessions, and the same skills can be used with the chat interface when the context requires structured instructions.

Cursor, GitHub, and VS Code

Cursor, the AI-first IDE, supports agent skills out of the box. GitHub Copilot and VS Code extensions have also integrated the same format, meaning a skill written for Claude works in Cursor and vice versa.

Other Players

The list continues to grow: Goose, Leda, Amp, Open Code, Gemini CLI, and Factory have all adopted the agent skills format. Each tool reads skill.md the same way, from the same folder structure.

Did You Know? The agent skills format is hosted on GitHub as an open, community-run repository. Anyone can submit improvements or new skill definitions, and the standard evolves through discussion, not vendor decree.

Tool	Adoption Status
Claude Code	Native support
Cursor	Native support
GitHub Copilot	Supported via extensions
VS Code	Supported via extensions
Goose	Native support
Leda	Native support
Amp	Native support
Open Code	Native support
Gemini CLI	Native support
Factory	Native support

The practical implication: you write one skill, and it works across all these platforms. No more translating instructions from one tool's custom format to another. No more vendor lock-in. If you switch from Claude Code to Cursor, your skills come with you.

Creating Your First Agent Skill: A Practical Example

Let's walk through a concrete scenario. You're building a Next.js application with TypeScript, and you want every API endpoint to follow the same pattern: consistent response envelopes, Zod validation, and structured logging.

Step 1: Create the Skill Folder

Inside your project, create a folder:

.project-skills/api-design/

The .project-skills directory is where many tools look for skills by default. You can also place skills in a shared team repository.

Step 2: Write the skill.md File

Open skill.md and add the metadata header:

---
name: API Design (Next.js)
description: Standards for building REST APIs in Next.js App Router with TypeScript, Zod validation, and structured logging.
---

Then write the full instructions:

# API Design Rules

When building a new API endpoint, always follow these rules:

1. **Response Format**: Every response must use the `ApiResponse<T>` wrapper:
   - `{ success: boolean, data?: T, error?: string }`
   - For success: `{ success: true, data: ... }`
   - For errors: `{ success: false, error: "message" }`

2. **Route Structure**: Use Next.js App Router convention:
   - `/api/[resource]/route.ts`
   - One resource per file, multiple HTTP methods in the same route.ts

3. **Input Validation**: Use Zod schemas defined in a shared `@/lib/validations` module.

4. **Logging**: Use the project logger (`@/lib/logger`) with structured metadata:
   - Include requestId, method, path, and elapsed time.

5. **TypeScript**: All handlers must have explicit return types. Use `NextResponse` properly.
   - Import `import { NextRequest, NextResponse } from 'next/server'`.

6. **Error Handling**: Wrap route logic in try/catch. Return 500 with `ApiResponse` format on unexpected errors.

7. **Helper Script**: The file `api-helpers/response.ts` is available in the project for constructing responses.

Step 3: Add Supporting Files

If your skill references a helper script like api-helpers/response.ts, include it in the skill folder or reference it relative to the project root. The AI will look for it.

Step 4: Test Across Tools

Test the skill in Claude Code and Cursor. Give each tool the same request: "Create a POST endpoint for registering a user." The AI should apply your skill's rules automatically—consistent response format, Zod validation, structured logging. If it doesn't, check your description for clarity.

Common Mistake: Writing a description that is too vague, like "Handles API endpoints." The AI may not trigger the skill for relevant requests because the description doesn't clearly match. Use specific terms that mirror how you talk about the task.

Common Mistakes to Avoid When Writing Agent Skills

Even experienced developers make a few predictable errors when creating their first skills.

Vague or Overlapping Descriptions

The description is what the AI uses to decide whether to load the skill. If two skills have similar descriptions (e.g., "API rules" and "Backend conventions"), the AI may load the wrong one—or miss a relevant skill entirely.

Fix: Make each description unique and specific. Include the technology stack, the task, and the scope. For example, "API Design for Next.js App Router with Zod" vs. "Backend Conventions for Express.js with Mongoose."

Too Many Instructions in One Skill

A single skill that tries to cover API design, database access, testing, and deployment will likely exceed context limits. The AI may struggle to follow all rules, or the skill may be too large to load efficiently.

Fix: Break large skills into smaller, focused ones. Create separate skills for API design, database queries, and testing. Use descriptive names so the AI can match each one independently.

Platform-Specific Commands

A skill written with shell commands that only work on macOS (e.g., open -a) will break if your teammate uses Linux or Windows—or if the AI runs in a cloud environment.

Fix: Use cross-platform commands and paths. Prefer actions the AI can perform through its tool interface rather than raw shell instructions. If you must include shell commands, note the required environment.

Not Testing Across Multiple Tools

A skill that works perfectly in Claude Code might not trigger in Cursor because of subtle differences in how the tools scan for skills. The format is open, but implementations can vary.

Fix: Test your skill in at least two tools before sharing it. Most issues are simple path problems—like using .cursor/skills instead of .project-skills. Check each tool's documentation for the default skill directory.

Best Practices for Sharing and Evolving Skills

Agent Skills become more valuable as they are shared. A single developer's skill for API design can standardize an entire team's output.

Use Git for Version Control

Store skills in a dedicated repository or within your project's repository. This gives you version history, code review, and the ability to roll back changes. Each skill folder is small, so even the most complex skills are easy to maintain.

Contribute to the Open Standard

The GitHub repository that defines the agent skills format accepts community contributions. If you find a pattern that works well—or spot a gap in the standard—submit a pull request. The format evolves based on real use cases.

Create an Internal Skill Library

For companies, create a centralized repository of approved skills. Include skills for code style, security requirements, deployment pipelines, and compliance rules. New team members can clone the repository and immediately get consistent AI behavior.

Expert Tip: Include a README.md in your skill repository explaining how to install and use the skills across different tools. This reduces onboarding friction for less experienced team members.

The Future of Agent Skills

The agent skills format is young, but adoption is accelerating. A few trends are already visible.

Beyond Coding

The same concept—a folder with a skill.md file that instructs an AI agent—works for non-coding tasks. Imagine skills for writing technical documentation, designing user flows, or conducting security audits. Any AI agent that reads files can use this standard.

Skill Marketplaces

Expect to see community-run marketplaces where developers share and discover pre-built skills. A skill for "Django REST Framework with JWT authentication" could be downloaded and dropped into any project, saving hours of configuration.

Remote Skill Loading

Future tools may support loading skills from remote URLs, not just local folders. This would allow teams to maintain a single source of truth for skills that update automatically—no more manual syncs.

The direction is clear: agent instructions are moving from inline prompts into structured, portable, versioned files. Agent Skills provide that structure without the complexity of a new framework.

Key Takeaways

• Agent Skills use a simple skill.md file inside a folder to define reusable instructions for AI coding assistants.
• Progressive disclosure ensures the AI only loads full instructions when needed, keeping context small and responses fast.
• The format works across ten+ major tools including Claude Code, Cursor, GitHub, VS Code, and Gemini CLI, making skills truly portable.
• Create effective skills by writing specific descriptions, keeping each skill focused, and avoiding platform-specific commands.
• Share skills via Git, contribute to the open standard, and build internal libraries for team consistency.
• The standard is evolving toward remote loading, skill marketplaces, and use cases beyond coding.

Frequently Asked Questions

What is an agent skill?
An agent skill is a folder containing a skill.md file that provides instructions for an AI agent to perform a specific task. It defines rules, conventions, and steps that the AI follows when the task matches the skill's description.

How is progressive disclosure different from loading everything at startup?
Progressive disclosure loads only the metadata (name and description) of each skill during startup. Full instructions are loaded only when the AI determines the skill is relevant to the current task. This saves context window space and improves response speed.

Which AI tools support the agent skills format?
Claude Code, Cursor, GitHub, VS Code, Goose, Leda, Amp, Open Code, Gemini CLI, and Factory currently support the format. The list continues to grow as the standard gains adoption.

Can I use the same skill in Claude Code and Cursor?
Yes. Because the format is an open standard, a skill written for one tool works in any other tool that follows the same spec. This is the primary benefit: write once, run everywhere.

How do I test if a skill is working correctly?
Give the AI a task that should trigger the skill, then check the output against your instructions. Try the same task in at least two different tools (e.g., Claude Code and Cursor) to verify portability.

What should I include in the metadata header?
The metadata header should contain the skill's name and a short, specific description. The name is a label; the description is what the AI uses to match the skill to a task. Use keywords that mirror how you talk about the task.

Is the agent skills format controlled by a single company?
No. The format is hosted on GitHub as an open, community-maintained repository. Any company or developer can propose changes or additions, and adoption decisions are made by the community.

Summary Box

Agent Skills are a simple, open standard for defining AI agent instructions using a skill.md file in a folder. They use progressive disclosure to remain efficient, work across ten major AI coding tools, and eliminate vendor lock-in. Creating a skill involves writing a short metadata header and full instructions in plain Markdown. Best practices include using specific descriptions, keeping skills focused, testing across tools, and version-controlling with Git. The standard is community-driven and evolving toward broader use, including non-coding tasks and remote loading.