--- title: "What Claude Code Skills Actually Are" description: "Claude Code skills are markdown files with YAML frontmatter that Claude auto-loads based on trigger descriptions. They differ from slash commands, tools, MCP." tldr: "Claude Code skills are markdown files with YAML frontmatter stored in ~/.claude/skills/ or .claude/skills/ directories. Claude loads them based on trigger descriptions and uses their content to enhance coding tasks. They are simpler than tools or MCP servers but less flexible than subagents." url: "https://aigentic.blog/what-are-claude-code-skills" publishedAt: "2026-06-16T13:01:37.745Z" updatedAt: "2026-06-16T13:01:37.745Z" category: "skills" tags: ["claude-code","skills","tools","ai-infrastructure","productivity"] --- # What Claude Code Skills Actually Are > Claude Code skills are markdown files with YAML frontmatter stored in ~/.claude/skills/ or .claude/skills/ directories. Claude loads them based on trigger descriptions and uses their content to enhance coding tasks. They are simpler than tools or MCP servers but less flexible than subagents. A Claude Code skill is a markdown file with YAML frontmatter that Claude Code reads, matches against user requests, and auto-loads to enhance coding tasks. Unlike tools or MCP servers, skills do not require runtime infrastructure or protocol implementations. They are static reference and instruction containers that Claude retrieves based on semantic matching of their trigger descriptions. Skills live in three scopes: user-level (`~/.claude/skills/`), project-level (`.claude/skills/` at repository root), and plugin-managed (installed by extensions). Claude loads them in order of specificity, with project-level skills taking precedence. Each skill file is a simple markdown document; its power comes from its declarative nature and Claude's ability to automatically invoke the right ones at the right time. ## How Skills Are Structured A Claude Code skill follows this template: ```markdown --- name: Skill Name description: A clear, specific description of what this skill does and when to use it. triggers: - "trigger keyword one" - "trigger keyword two" --- # Skill Body The markdown content here provides instructions, templates, code snippets, or reference material that Claude loads into context when the skill is triggered. ``` The frontmatter fields are minimal: - `name`: Human-readable name for the skill. - `description`: One to three sentences explaining the skill's purpose and typical use cases. Claude uses this to decide whether to load the skill. - `triggers`: Optional list of keywords or phrases. If present, Claude matches these against request text. If absent, Claude relies on semantic matching of the description. The body is free-form markdown. It can contain code snippets, templates, best practices, API documentation, project conventions, or any reference material Claude should consider when the skill is active. ## Skills vs. Alternatives Skills are one of several ways to extend Claude Code. Understanding the trade-offs matters for choosing the right approach. | Aspect | Skills | Slash Commands | Tools | MCP Servers | Subagents | |--------|--------|---|---|---|---| | Storage | Markdown files in ~/.claude/skills/ or .claude/skills/ | Built into CLI or IDE | Configured in tools.json or Claude profile | Separate daemon process | Separate agent instance | | Execution | None; static context | CLI invocation | Function calls with runtime | JSON-RPC protocol | Spawned as subprocess or API | | Scope | User-level, project-level, or plugin | Single command context | Single invocation context | Long-lived connection | Independent agent lifecycle | | Setup Complexity | Minimal (just create files) | Moderate (CLI config) | Moderate to high (schema, SDK) | High (protocol, daemon) | High (agent config, spawning) | | When to Use | Provide reference material, templates, conventions | Frequently-used single commands | Execute code, call APIs, read/write files | Complex integrations, external services | Multi-step planning, specialized reasoning | | Limitations | No execution capability; purely declarative | Requires explicit invocation | Stateless per invocation | Operational complexity | Higher latency, separate context | Skills excel when you want to inject knowledge, conventions, or templates without building infrastructure. They are ideal for encoding team standards, documentation snippets, or contextual rules that Claude should always consider in a given project. ## Directory Conventions and Precedence Claude Code uses a two-level hierarchy for skill discovery: 1. User-level skills in `~/.claude/skills/` apply globally across all projects and all IDE sessions. 2. Project-level skills in `.claude/skills/` (at the repository root) apply only to that project and take precedence over user-level skills with the same name. 3. Plugin-managed skills are installed and managed by extension systems; their location depends on the plugin framework. Within each directory, each markdown file is treated as one skill. File naming is arbitrary; Claude loads by parsing frontmatter, not by filename. A common convention is `skill-name.md` or `{category}-{skill}.md`, but any valid markdown filename works. When Claude processes a request, it scans available skills, reads their frontmatter, and evaluates the description and optional triggers against the current context. Multiple skills may be loaded in a single session if their descriptions match different aspects of the request. There is no limit to the number of skills that can be loaded; Claude manages context automatically. ## When Skills Are Loaded Claude Code loads skills in two ways: - **Semantic matching**: Claude reads all available skill descriptions and decides which ones are relevant to the user's current request or the active project. A skill for "writing unit tests in Python" would be loaded when the user is working on a Python test file, for example. - **Explicit triggering**: If a skill includes a `triggers` list, Claude can match those keywords or phrases directly in the user's message or codebase context. This means skills act as a form of intelligent context injection rather than explicit command invocation. The user does not write a slash command or function call to use a skill; Claude decides to load it based on relevance. This is both a strength and a limitation: skills are discoverable and automatic, but they offer less explicit control than tools or commands. ## Limitations and Boundaries Skills are not suitable for every extension scenario: - **No execution**: Skills cannot run code, call APIs, read files, or make network requests. If your use case requires dynamic behavior, use tools or MCP servers. - **No state management**: Skills are stateless. If you need to maintain state across invocations, use tools with persistent backends or MCP servers. - **No authentication or secrets**: Skills are plain markdown; storing credentials in them is unsafe. For integrations that need secrets, use tools with credential managers or MCP servers with security middleware. - **No real-time data**: Skills provide static content. If you need live data from external services, use tools or MCP servers with network access. - **Limited interactivity**: Skills do not support multi-turn user prompts or complex dialog. For conversational experiences, consider subagents. Skills are best used for codifying knowledge, templates, and conventions that do not change during a session and do not require external system calls. ## Practical Examples A real-world skill might look like this: ```markdown --- name: Python Testing Standards description: Team conventions for unit testing in Python, including pytest patterns and coverage requirements. triggers: - "pytest" - "test" - "unit test" --- # Python Testing Standards ## Pytest Conventions - Always use fixtures for setup and teardown. - Name test functions `test__`. - Use parametrize for multiple test cases. ## Minimum Coverage - 80% line coverage required for main modules. - 100% coverage for critical paths. [... more content ...] ``` When a user works on a Python test file or mentions "pytest," Claude loads this skill and uses it to inform its suggestions and code generation. Another example, a skill for project structure: ```markdown --- name: Monorepo Layout description: Directory structure and conventions for this monorepo, including package naming and import rules. --- # Monorepo Structure - /packages: Npm packages - /services: Backend services - /apps: Frontend applications [... more content ...] ``` This skill, stored in `.claude/skills/monorepo-layout.md`, is automatically loaded whenever the user works within that project, ensuring Claude respects the project's structure in its code generation. ## Takeaways Claude Code skills are the lightest-weight extension mechanism: simple markdown files with YAML frontmatter that Claude loads based on semantic matching. They excel for encoding team conventions, templates, and project-specific knowledge without runtime overhead. Skills differ fundamentally from tools, MCP servers, and subagents; they provide context and instructions, not execution. If you need dynamic behavior, use tools or MCP servers. If you need multi-agent orchestration, use subagents. Skills are best for static knowledge that enhances Claude's understanding and generation within a project or user context. The two-level directory hierarchy (user-level and project-level) allows flexible scoping; project skills override user skills with the same name. No explicit invocation is required; Claude discovers and loads skills based on relevance, making them both discoverable and automatic. Practical use cases include encoding linting standards, API documentation, test templates, architecture diagrams, deployment procedures, and code style guides. Any knowledge that should inform Claude's responses across many interactions but does not require external calls is a candidate for a skill. ## Further reading - [Anthropic's Claude Code documentation](https://claude.ai/docs) - Official guide to Claude Code and its extensions. - [anthropics/skills GitHub repository](https://github.com/anthropics/skills) - Community-curated skills and examples for Claude Code. - [Claude Code release notes](https://support.anthropic.com) - Announcements and updates on Claude Code features. - [MCP specification](https://spec.modelcontextprotocol.io) - Model Context Protocol documentation for building advanced integrations. - [Tools and integrations guide](https://claude.ai/docs/guides/tools) - Comprehensive guide to tools, MCP, and other extension methods in Claude. ## Frequently asked ### What exactly is a Claude Code skill? A Claude Code skill is a markdown file containing YAML frontmatter that Claude Code reads and loads automatically. The frontmatter includes metadata like name, description, and trigger rules; the body contains the skill's content, instructions, or context. Claude matches incoming requests against trigger descriptions to decide which skills to load. ### Where do Claude Code skills get stored? Skills live in three locations with different scopes: user-level skills in ~/.claude/skills/ (apply across all projects), project-level skills in .claude/skills/ at the repository root (apply only to that project), and plugin-managed skills installed by extensions. All use the same markdown-plus-frontmatter format. ### How do skills differ from MCP servers or tools? Skills are static markdown files with optional YAML frontmatter that Claude loads based on trigger descriptions. Tools require a runtime to execute code or make external calls. MCP servers are full protocol implementations for complex integrations. Subagents are separate agent instances. Skills are the lightest weight and require no runtime infrastructure. ### Can skills execute code or call external APIs? Skills are primarily declarative; they provide context, instructions, or reference material to Claude. They do not have built-in execution or network capabilities. For dynamic behavior, use tools, MCP servers, or subagents instead. ### How does Claude know which skills to load? Each skill's frontmatter includes a description and optional trigger rules. Claude reads this metadata and loads skills whose descriptions match the user's request or project context. The matching is based on semantic relevance and any explicit trigger conditions defined in the skill.