Claude Skills: What They Are and How They Work

We keep seeing the same pattern as more builders move from vibe coding to structured development: the tools get more capable, but the knowledge of how to use them well stays locked inside someone's head. Claude Skills is Anthropic's answer to that problem. Here's what Skills actually are, how they work under the hood, and why they matter for teams shipping real software.

---

#What Are Claude Skills?

Claude Skills are folders containing a SKILL.md file with YAML frontmatter, markdown instructions, and optional supporting files like scripts or templates. Anthropic introduced Agent Skills on October 16, 2025 as a way to encode procedural knowledge directly into Claude's workflow.

The idea is straightforward. Instead of pasting the same prompt every time you need Claude to follow a specific process, you package that knowledge into a Skill. Claude discovers the Skill automatically when it's relevant to the task at hand, loads the instructions, and follows them. You can also invoke a Skill directly using a slash command like /skill-name.

Skills work across Claude.ai (on Pro, Max, Team, and Enterprise plans), Claude Code, and the Claude API. They follow the Agent Skills open standard, which means the same Skill format is portable across different AI tools and platforms.

---

#How Do Claude Skills Work?

Skills use a technique called progressive disclosure to stay efficient with context. When Claude starts working on a task, it scans the metadata of all available Skills, which costs only about 100 tokens per Skill. If a Skill's description matches the current task, Claude loads the full instructions, typically under 5,000 tokens. If the Skill includes scripts or reference files, those load only when the instructions call for them.

This layered approach means you can have dozens of Skills available without bloating Claude's context window. Claude pulls in exactly the knowledge it needs, at the moment the task calls for it.

Loading diagram...

Here's what the folder structure looks like in practice:

1my-skill/
2├── SKILL.md           # Main instructions (required)
3├── template.md        # Template for Claude to fill in
4├── examples/
5│   └── sample.md      # Example output
6└── scripts/
7    └── validate.sh    # Script Claude can execute

The SKILL.md file has two parts: YAML frontmatter between --- markers that tells Claude the Skill's name, description, and configuration, and markdown content with the actual instructions. The name field becomes the /slash-command, and the description helps Claude decide when to load the Skill automatically.

A basic Skill looks like this:

1---
2name: api-conventions
3description: API design patterns for this codebase. Use when writing or reviewing API endpoints.
4---
5
6When writing API endpoints:
7
81. Use RESTful naming conventions
92. Return consistent error formats with status codes
103. Include request validation at the handler level
114. Log all errors with structured context

---

#Claude Skills vs System Prompts, CLAUDE.md, and MCP

One of the most common questions about Skills is how they compare to other ways of giving Claude instructions. Each approach serves a different purpose, and understanding the distinctions helps you pick the right tool for the job.

#System prompts

System prompts apply broadly to every conversation. They are useful for persistent preferences and baseline behavior, but they aren't task-aware. Everything in a system prompt loads every time, regardless of whether it's relevant to the current task. For teams with complex workflows, this creates a constant trade-off between thoroughness and token efficiency.

#CLAUDE.md files

CLAUDE.md files provide project-level context that lives in your repository. They work well for coding conventions, directory structures, and project-specific guidelines. However, they are static and load fully into context at the start of every session. They also don't compose easily across multiple projects or teams.

#MCP (Model Context Protocol)

MCP handles connectivity. It gives Claude access to external tools and data sources through a standardized protocol. Think of MCP as the bridge between Claude and the systems where your data lives: databases, APIs, Google Drive, GitHub, and more. MCP tells Claude what it can reach, and our guide to MCP in Claude Code covers this in depth.

#Where Skills fit

Skills fill the gap between connectivity and competence. MCP gives Claude access to your tools. System prompts and CLAUDE.md give Claude broad context. Skills teach Claude how to approach specific tasks with the right steps, constraints, and edge cases accounted for. Because Skills load dynamically based on relevance, they avoid the context bloat that comes with front-loading everything into a system prompt or CLAUDE.md file.

---

#Why Claude Skills Matter for Builder Teams

There is a pattern that shows up consistently in teams using AI coding tools at any real scale. One engineer figures out the right way to handle a tricky workflow, such as how to validate schemas before running database migrations, or which steps to follow when deploying to staging. That knowledge lives in their head, or maybe in a Slack thread that nobody will be able to find again in six months.

Skills turn that kind of institutional knowledge into a reusable, versioned artifact. The engineer writes a Skill once, commits it to the repository, and everyone on the team benefits from it automatically whenever Claude works on a related task. The knowledge compounds over time instead of evaporating after each session.

For organizations on Team or Enterprise plans, admins can provision Skills across the entire workspace. This means security review procedures, coding standards, deployment checklists, and compliance workflows can all be distributed through Skills without requiring each team member to configure anything individually.

In December 2025, Anthropic expanded Skills with organization-wide management and launched a Skills directory with partner-built Skills, making it easier to find and adopt community-created workflows. In January 2026, they followed up with a comprehensive 32-page guide to building Skills, covering everything from planning and design to testing and distribution.

---

#Getting Started with Claude Skills

If you're using Claude Code, you can start building Skills today. The structure is lightweight: create a folder, add a SKILL.md file with a short YAML header and your instructions in Markdown. Basic Skills require no code at all, though you can bundle executable scripts for more advanced behavior.

Skills can live in three places depending on who needs them:

• Personal (~/.claude/skills/): Available across all your projects
• Project (.claude/skills/): Shared with your team via version control
• Enterprise: Managed organization-wide through admin settings

The Claude Code documentation on Skills covers the full configuration reference, including frontmatter options, argument passing, dynamic context injection, and how to run Skills in subagents.

---

#Frequently Asked Questions

#Are Claude Skills free to use?

Skills are available on all paid Claude plans. On Claude.ai, that includes Pro, Max, Team, and Enterprise. In Claude Code, Skills work regardless of plan since Claude Code has its own usage-based pricing. There is no additional cost for creating or using Skills beyond your existing Claude subscription.

#Can Claude Skills run code and scripts?

Yes. Skills can include executable scripts in any language, such as Python or Bash, inside a scripts/ directory within the Skill folder. Claude runs these scripts when the Skill's instructions reference them. This is useful for tasks like generating HTML reports, validating data, or running build steps as part of a workflow.

#Do Claude Skills work outside of Claude Code?

The Skill format follows the Agent Skills open standard, which is designed to be portable across different AI tools. Claude Code, Claude.ai, and the Claude API all support Skills natively. Other tools that adopt the open standard can also use the same SKILL.md format, though feature support may vary by platform.

#Is there a limit on how many Skills I can have?

There is no hard limit on the number of Skills you can make available. Because Skills use progressive disclosure, only the metadata (about 100 tokens per Skill) loads into context at any given time. Full instructions load only when a Skill matches the current task, so having many Skills doesn't meaningfully increase token usage or slow Claude down.

#Can I share Skills with my team?

Yes, in several ways. Project-level Skills stored in .claude/skills/ can be committed to version control and shared through your repository. On Team and Enterprise plans, organization admins can provision Skills across the entire workspace so every team member has access automatically. Anthropic also maintains a public Skills directory with community and partner-built Skills you can adopt.

#What is the difference between a Skill and a custom slash command?

In Claude Code, custom slash commands (stored in .claude/commands/) and Skills (stored in .claude/skills/) both create /slash-command shortcuts. Skills are the newer format and support additional features like automatic invocation based on task relevance, supporting files and scripts, and YAML frontmatter for fine-grained configuration. Existing command files continue to work, but Anthropic recommends Skills for new workflows.

---

If you want to go deeper on how Skills fit into a structured development workflow, read our post on spec-driven development, which covers how we ship features in under an hour using a process that Skills are well-suited to encode.