If you are using Claude Code without skills, you are leaving half its capability on the table. I learned this the hard way. For weeks, I was writing repetitive prompts, copy-pasting instructions into every session, and watching Claude produce inconsistent outputs across projects. Then I installed my first Claude Code skill, and the difference was immediate.
Claude Code skills are structured instruction files that extend what Claude can do. They package workflows, conventions, templates, and domain expertise into reusable SKILL.md files that Claude loads on demand. Instead of re-explaining your coding standards, deployment process, or content format every single time, you write it once as a skill, and Claude applies it consistently across every session.
This guide covers everything I have learned from building, installing, debugging, and shipping Claude Code skills across real projects. Whether you want to use the built-in skills that ship with Claude Code, install community skills from the growing marketplace, or build your own custom skills from scratch, this article walks through every step with working examples.
|
Quick Answer Claude Code skills are SKILL.md files that give Claude specialized instructions for specific tasks. They live in the .claude/skills/ directory, use YAML frontmatter for metadata, and contain Markdown instructions Claude follows at execution time. Skills can be invoked manually with slash commands (e.g., /review, /simplify) or triggered automatically when Claude detects a matching task. Built-in skills ship with Claude Code. Custom skills can be created by writing a SKILL.md file. Community skills install via npx or manual download. Skills work across Claude Code, Claude.ai, and the API — write once, use everywhere. |
What Are Claude Code Skills?
Claude Code skills is a folder containing a SKILL.md file written in Markdown. The file has two parts: YAML frontmatter at the top that defines the skill name and description, and Markdown content below that contains the actual instructions Claude follows when the skill runs.
When you invoke a skill, Claude reads the SKILL.md into its context window and executes the instructions. Skills can spawn subagents, run bash commands, read and write files, accept arguments, and orchestrate multi-step workflows. They are not static templates — they are dynamic playbooks that Claude interprets and adapts to the current context.
Skills vs. Slash Commands
This distinction confused me early on, and I see other developers making the same mistake. Slash commands like /clear, /compact, /help, and /cost are hardcoded CLI operations. They do one fixed thing with no AI reasoning involved. Skills like /review, /simplify, /batch, and /loop are prompt-based. They load instructions into Claude’s context and let it reason through the task. Both start with /, but they are fundamentally different systems.
Skills vs. MCP Servers
MCP (Model Context Protocol) servers give Claude access to external tools — databases, APIs, third-party services. Skills teach Claude how to use those tools effectively. A useful analogy: MCP is the kitchen with all the equipment, and skills are the recipes that tell Claude how to cook. You can combine them. Sentry’s code review skill, for example, defines the PR analysis workflow in a SKILL.md while fetching error data through Sentry’s MCP server.
Skills vs. Plugins
Traditional plugins require complex APIs, authentication setups, and server infrastructure. Skills are just files and folders. They are easy to version control, easy to distribute, and easy to modify. If you can write documentation, you can create a skill. This accessibility is what drives the rapid ecosystem growth — the barrier to contributing a useful skill is writing clear Markdown, not building a server.
Skills vs. CLAUDE.md
CLAUDE.md files provide persistent project context — coding conventions, architecture decisions, team preferences. They load automatically every session. Skills are task-specific and load on demand. I use CLAUDE.md for “always remember this” context and skills for “do this specific workflow when asked.” They complement each other. A common mistake is putting task workflows in CLAUDE.md when they should be skills — this wastes context tokens on every session, even when the workflow is not needed.
|
Feature |
Description |
|
File Format |
SKILL.md with YAML frontmatter + Markdown instructions |
|
Location |
.claude/skills/ (project-level) or ~/.claude/skills/ (global) |
|
Invocation |
Slash command (/skill-name) or automatic trigger |
|
Arguments |
$ARGUMENTS placeholder for dynamic input |
|
Subagents |
Can spawn parallel agents for multi-step tasks |
|
Cross-Platform |
Works in Claude Code, Claude.ai, and API |
How Claude Code Skills Work Under the Hood
Understanding the skill execution model helped me write significantly better skills. Claude Code skills operate on a progressive disclosure architecture — Claude does not dump the entire skill into its context window upfront. Instead, it loads information in stages.
The Three-Stage Loading Process
At stage one, Claude reads only the metadata — the name and description from the YAML frontmatter. This costs roughly 100 tokens and stays in context permanently. Claude uses this metadata to decide whether to load the full skill. At stage two, when the skill triggers, Claude reads the SKILL.md body into context. At stage three, if the instructions reference supporting files like REFERENCE.md, templates, or scripts, Claude reads only the files it needs for the current task.
This is why the description field matters so much. I have had skills that never triggered because the description did not match how I naturally phrased requests. If you typically say “review my code,” but your description says “audit software artifacts,” Claude will miss the connection.
Script Execution and Token Efficiency
When a skill references an executable script like validate_form.py, Claude runs it via bash. The script code itself never enters the context window — only its output does. This means you can bundle heavy validation logic, data processing, or API calls in scripts without burning context tokens. I use this pattern extensively for skills that need to parse large files or run linting checks.
Built-In Claude Code Skills You Should Know
Claude Code ships with several bundled skills that are available in every session. I ignored these for weeks, building custom alternatives before realizing the built-in options were already well-designed. Here is what is available and how I use each one.
/simplify — Automated Code Cleanup
This is the skill I use most frequently. After making changes to a codebase, /simplify reviews recently changed files for code reuse opportunities, quality issues, and efficiency improvements. It spawns three parallel review agents, each examining changes from a different angle. I run it after every large refactoring session or after accepting a batch of AI-generated code. It catches unused imports, redundant variables, opportunities to extract shared logic, and overly complex conditionals.
/review — Multi-Agent Code Review
The /review skill performs a structured code review on your recent changes. You can scope it to specific concerns — /review “check for security vulnerabilities in the auth module” narrows the review focus. I find it most valuable when working on unfamiliar parts of a codebase where I might miss context-specific issues.
/batch — Parallel Task Execution
The /batch skill lets you run the same operation across multiple files or targets simultaneously. Instead of processing files sequentially, /batch spawns parallel agents. This is a significant time saver for bulk operations like updating import paths across a project or applying consistent formatting to multiple components.
/loop — Background Monitoring
The /loop skill runs a continuous monitoring loop in the background. While I have not used it as heavily as the other built-in skills, it is useful for longer coding sessions where you want automated checks running without switching terminals.
/debug — Session Diagnostics
When something goes wrong in your Claude Code session — a tool call fails silently, Claude seems confused about context, or behavior is unexplainably odd — /debug reads the session debug log and helps diagnose the issue. This skill has saved me hours of troubleshooting.
/claude-api — API Reference Loader
If you are building applications with the Claude API or Anthropic SDK, /claude-api loads the relevant API reference material for your project language. It supports Python, TypeScript, Java, Go, Ruby, C#, PHP, and cURL, plus the Agent SDK reference. This skill also activates automatically when Claude detects code importing anthropic or @anthropic-ai/sdk.
Built-In Skills at a Glance
|
Skill |
Function |
Best For |
Agents Spawned |
|
/simplify |
Code cleanup and optimization |
Post-refactoring review |
3 parallel |
|
/review |
Structured code review |
Security and quality checks |
1+ |
|
/batch |
Parallel task execution |
Bulk file operations |
Multiple |
|
/loop |
Background monitoring |
Long coding sessions |
1 continuous |
|
/debug |
Session diagnostics |
Troubleshooting failures |
1 |
|
/claude-api |
API reference loading |
SDK development |
1 |
How to Create Custom Claude Code Skills
Building your own Claude Code skills is where the real power lies. The process is straightforward — you are essentially writing documentation that Claude follows. But there are patterns that make skills dramatically more effective.
Step 1: Create the Skill Directory
Skills live in one of three locations depending on scope. For project-specific skills, create a folder inside your-project/.claude/skills/. For personal global skills, use ~/.claude/skills/. For shared team skills, use the –add-dir flag or the Anthropic skills marketplace.
Here is the directory structure I use for a typical skill:
|
Directory Structure your-project/ └── .claude/ └── skills/ └── my-skill-name/ ├── SKILL.md ├── references/ │ └── REFERENCE.md └── templates/ └── output-template.md |
Step 2: Write the SKILL.md File
Every SKILL.md starts with YAML frontmatter between — markers, followed by Markdown instructions. The frontmatter must include a name (which becomes the slash command) and a description (which Claude uses to decide when to auto-trigger the skill).
|
Example: Commit Message Formatter Skill — name: commit-format description: Format git commit messages using Conventional Commits. Use when user mentions commit, git message, or asks to format a commit message. — # Commit Message Formatter Format all commit messages following Conventional Commits 1.0.0. ## Format <type>(<scope>): <description> ## Rules – Imperative mood, lowercase, no period, max 72 chars – Breaking changes: add ! after type/scope |
Step 3: Configure Invocation Behavior
By default, Claude can invoke skills both manually (via /skill-name) and automatically (when it detects a matching task). You can control this with frontmatter fields. Setting disable-model-invocation: true prevents automatic triggering — useful for deployment or destructive operations where you always want explicit control. Setting context: fork runs the skill in a separate subagent, which is ideal for long-running tasks that should not block your main session.
Step 4: Add Supporting Files
Keep SKILL.md focused on core instructions. Move detailed documentation, API schemas, example collections, and large reference materials into a references/ subfolder. Reference these files from SKILL.md so Claude knows what they contain and when to load them. This progressive disclosure approach means heavy reference content does not consume context tokens unless the task specifically needs it.
Step 5: Test and Iterate
Claude actively watches the .claude/skills/ directory. Edit a SKILL.md mid-session and the changes apply immediately — no restart required. I use this for rapid iteration: invoke the skill, check the output, tweak the instructions, and re-invoke. This live reload capability makes skill development surprisingly fast.
Advanced Pattern: Subagent Orchestration
For complex workflows, skills can spawn separate subagent processes using the context: fork frontmatter field. The subagent runs in its own context window, which means it does not consume your main session’s tokens. I use this pattern for deployment skills and long-running analysis tasks. The main agent acts as a project manager while the forked agent does the heavy lifting. You can even orchestrate multiple subagents working in parallel on different parts of a task.
Advanced Pattern: Argument-Driven Skills
Skills accept dynamic arguments through the $ARGUMENTS placeholder. When you invoke /fix-issue 123, the $ARGUMENTS value becomes “123” inside SKILL.md. You can also use indexed variants like $0 and $1 for specific positional arguments. This makes skills flexible enough to handle different inputs without needing separate skill files for each variation. I use argument-driven skills for ticket-based workflows where the issue number drives what files to check and what tests to run.
Installing Community and Third-Party Claude Code Skills
The Claude Code skills ecosystem has grown rapidly. As of early 2026, there are official Anthropic skills, verified third-party skills, and thousands of community-contributed skills compatible with the universal SKILL.md format.
Installing Official Anthropic Skills
Anthropic maintains a public skills repository on GitHub (anthropics/skills) with categories spanning creative design, development, enterprise communication, and document processing. Install individual skills with npx skills add anthropics/claude-code –skill skill-name or browse the collection and download manually.
The Anthropic Skills Marketplace
Anthropic launched an official plugin marketplace accessible from within Claude Code. You can register the Anthropic skills repository and install skill bundles: /plugin install document-skills@anthropic-agent-skills covers document generation, /plugin install example-skills@anthropic-agent-skills covers a broad starter set.
Community Skill Libraries
Beyond the official repository, community-maintained libraries like the Antigravity Awesome Skills collection offer curated bundles organized by role. The Web Wizard bundle includes frontend-design, api-design-principles, lint-and-validate, and create-pr. The library supports Claude Code, Cursor, Gemini CLI, and other agents using the same SKILL.md format.
Manual Installation
The simplest installation path is manual. Download or write a SKILL.md file and drop it into ~/.claude/skills/your-skill-name/. In any Claude Code session, the skill becomes available immediately. No build step, no compilation, no package manager.
Best Claude Code Skills to Install Right Now
After testing dozens of community skills and building several of my own, here are the ones that have had the most measurable impact on my development workflow.
1. frontend-design — Escape Generic AI Aesthetics
The official Anthropic frontend-design skill is the most-installed skill in the ecosystem. Without it, Claude defaults to the same Inter font, purple gradient, minimal animation pattern that every AI-generated UI shares. With the skill loaded, Claude produces distinctive typography, purposeful color palettes, and intentional animations. The difference in output quality is immediately visible.
2. Code Review and Quality Skills
Community-built code review skills that enforce project-specific validation rules outperform the generic built-in /review significantly. I wrote a custom review skill for an Astro site that knows the project’s URL patterns, component structure, and validation rules. A generic skill is fine; a project-specific one is transformative.
3. Git Workflow Skills
Skills for commit message formatting, PR description generation, branch naming, and changelog generation save substantial time on mechanical git operations. The git-dojo skill is a popular community option that handles conventional commits, interactive rebasing guidance, and merge conflict resolution.
4. Testing and QA Skills
Browser automation skills turn Claude from a code-generation tool into an end-to-end QA engineer. Claude can open pages, interact with elements, verify behavior, and report results. Combined with testing framework skills (Jest, Vitest, Playwright), you get automated test generation that actually matches your project patterns.
5. Document Generation Skills
Anthropic’s official document skills cover PowerPoint, Excel, Word, and PDF creation. These skills run in the code execution environment and produce production-quality files. I use the PPTX skill regularly for client presentations and the DOCX skill for report generation. The skills handle complex formatting — tables of contents, page numbers, branded headers, chart embedding — that would take significant manual effort in a traditional workflow.
6. SEO and Content Skills
I built a custom SEO article writing skill that runs SERP analysis, generates structured outlines with H2/H3 hierarchy, and produces fully formatted articles with NLP entity density, featured snippet optimization, and FAQ sections. The skill outputs publication-ready DOCX files with branded formatting. It replaced a multi-step manual process that used to take me hours per article.
Using Claude Code Skills in Claude.ai and the API
One of the most powerful aspects of Claude Code skills is cross-platform portability. The same SKILL.md file works in Claude Code, Claude.ai, and the Anthropic API without modification.
Skills in Claude.ai
Claude.ai supports skills through the Customize > Skills interface. You upload a skill as a ZIP file containing the skill folder, and it appears in your skills list. Claude automatically invokes matching skills when your request aligns with the skill description. You can also toggle skills on or off individually. Skills require code execution to be enabled in Settings > Capabilities.
Skills in the API
The Anthropic API supports skills through the code execution tool. Skills run in a VM environment where Claude has filesystem access, bash commands, and code execution capabilities. The API supports both Anthropic’s pre-built skills (PowerPoint, Excel, Word, PDF) and custom skills you upload. Check Anthropic’s Agent Skills documentation for the API integration quickstart.
Plan-Level Availability
|
Plan |
Pre-Built Skills |
Custom Upload |
Org Sharing |
|
Free |
Yes |
Yes |
No |
|
Pro |
Yes |
Yes |
No |
|
Max |
Yes |
Yes |
No |
|
Team |
Yes |
Yes |
Yes (default off) |
|
Enterprise |
Yes |
Yes (admin-controlled) |
Yes (admin-controlled) |
SKILL.md File Structure: A Complete Breakdown
After building over a dozen skills, I have settled on a consistent SKILL.md structure that produces reliable results. Here is the anatomy of a well-written skill file.
YAML Frontmatter Fields
|
Field |
Required |
Purpose |
Example |
|
name |
Yes |
Slash command name (64 chars max) |
deploy-prod |
|
description |
Yes |
Auto-trigger matching (200 chars max) |
Deploy the app to production… |
|
context |
No |
Execution context (fork for subagent) |
fork |
|
disable-model-invocation |
No |
Prevent auto-triggering |
true |
|
dependencies |
No |
Required packages |
python: [pandas] |
The Description Field Is Critical
Claude uses the description to decide when to auto-invoke a skill. Write it using the exact phrases you would naturally say when requesting the task. Include verb variations: “review my code,” “check this PR,” “audit these changes” should all appear if they describe the same action. I have seen skills fail to trigger simply because the description used formal language while the developer spoke casually.
Instruction Patterns That Work
The Markdown body should follow one of three patterns depending on the skill type. Reference skills add domain knowledge (coding standards, style guides, API conventions) that Claude applies alongside your current conversation. Task skills give step-by-step instructions for specific actions like deployments or code generation. Workflow skills orchestrate multi-step processes with checkpoints and decision logic.
For task and workflow skills, I always include an explicit output format section, at least two concrete examples, and a “Rules” or “Constraints” section listing what Claude should never do. This eliminates most inconsistency issues.
Why Skills Fail Silently and How to Fix It
The most frustrating skill issue is silent non-triggering. You ask Claude to do something, and it ignores your skill entirely. I have identified three common causes. First, the description does not match your natural phrasing — fix it by writing the description as you would speak. Second, another skill with a similar description is intercepting the trigger — check with /skills to see what is loaded. Third, the skill is not in the correct directory — verify the path matches .claude/skills/skill-name/SKILL.md exactly.
Versioning and Team Distribution Patterns
For teams, skills should live in version control alongside the codebase. Put project-specific skills in your-repo/.claude/skills/ and commit them. When a teammate clones the repo, the skills are automatically available. For organization-wide skills on Enterprise plans, admins can provision skills that appear for all users automatically. On Team plans, peer-to-peer and peer-to-org sharing is available but disabled by default — an admin must enable it.
The Performance Gap Between Generic and Project-Specific Skills
A generic “code review” skill from the marketplace will give you decent results on any codebase. A project-specific skill that knows your exact directory structure, naming conventions, validation rules, and architectural patterns will give you dramatically better results. The effort to customize a generic skill to your project is minimal — usually 30 minutes of editing — but the output quality difference is substantial. I now treat skill customization as a standard part of project setup.
Troubleshooting Common Claude Code Skills Issues
1. Skill Does Not Trigger
Start with the description. Make it match your natural language. Run /skills to confirm the skill appears in the loaded list. Try invoking it directly with /skill-name to rule out detection issues. If it still fails, check the file path — SKILL.md must be inside a named subfolder under .claude/skills/.
2. Skill Triggers Too Often
If a skill activates on unrelated requests, the description is too broad. Narrow it by adding specific trigger phrases and excluding irrelevant ones. Adding disable-model-invocation: true forces manual-only invocation for sensitive skills.
3. Inconsistent Output Quality
Add concrete examples to SKILL.md showing expected inputs and outputs. Include a “Rules” section with explicit constraints. Remove ambiguous instructions — if Claude can interpret an instruction two ways, it will eventually interpret it the wrong way.
4. Context Window Overload
If Claude starts losing context during skill execution, your skill is loading too much content. Move large reference files out of SKILL.md and into supporting files. Use scripts for heavy data processing — script code does not enter the context window, only the output does. Monitor context usage with the /context command.
The Universal Agent Skills Standard
One of the most consequential developments in the skills ecosystem is the emergence of a universal SKILL.md standard. Anthropic collaborated with multiple AI tool vendors to establish an open specification at agentskills.io. The same SKILL.md format now works across Claude Code, Cursor, Gemini CLI, Codex CLI, GitHub Copilot, and Antigravity IDE.
This cross-platform compatibility means a skill you build for Claude Code is immediately usable in other agents without modification. The specification defines the frontmatter fields, Markdown structure, supporting file conventions, and invocation patterns. If you are building skills for distribution, following the agentskills.io standard ensures maximum portability. I have published skills that developers use across three different coding agents without me maintaining separate versions.
Security Considerations for Claude Code Skills
Skills execute in Claude’s code environment with filesystem and bash access. This makes security a real concern, especially with third-party skills.
- Review before enabling. Always read the SKILL.md and any bundled scripts before installing a skill from an untrusted source. Check for suspicious network calls, file system access outside the project directory, or instructions that could exfiltrate data.
- Never hardcode credentials. Do not put API keys, passwords, or tokens in SKILL.md files. Use environment variables or secure credential stores.
- Watch for prompt injection. The most significant risk with skills is prompt injection — a malicious skill could manipulate Claude into executing unintended actions. Anthropic has implemented mitigations, but the risk is not zero.
- Prefer official and verified sources. Skills from the Anthropic repository and verified publishers have been reviewed. Community skills from unknown authors require more scrutiny.
Frequently Asked Questions About Claude Code Skills
1. What are Claude Code skills?
Claude Code skills, a SKILL.md file containing YAML frontmatter and Markdown instructions that extend Claude’s capabilities for specific tasks. Skills are loaded on demand, invoked via slash commands or automatic detection, and can orchestrate multi-step workflows including subagent spawning, file operations, and script execution.
2. How do I install a Claude Code skill?
Create a folder inside .claude/skills/ in your project directory or ~/.claude/skills/ globally. Place a SKILL.md file inside the folder. The skill is immediately available in your next Claude Code session. For marketplace skills, use npx skills add followed by the repository and skill name. No build step or compilation is required.
3. Are Claude Code skills free to use?
Skills are available on all Claude plans including Free, Pro, Max, Team, and Enterprise. Anthropic’s built-in skills (document creation, code review) are included at no additional cost. Community skills are typically free and open source. Some specialized commercial skills on third-party marketplaces carry a price tag, usually in the 5 to 15 EUR range.
4. Can I use the same skill in Claude.ai and Claude Code?
Yes. Skills are cross-platform. The same SKILL.md file works in Claude Code, Claude.ai (via Customize > Skills upload), and the Anthropic API (via the code execution tool). Write the skill once and deploy it across all Claude surfaces without modification.
What is the difference between Claude Code skills and MCP servers?
MCP servers provide tool access — they connect Claude to external systems like databases, APIs, and third-party services. Skills provide workflow knowledge — they teach Claude how to perform tasks with step-by-step procedures, standards, and best practices. MCP solves tool orchestration. Skills solve workflow orchestration. They can be combined: a skill can define a workflow that uses MCP tools for data access.
Conclusion
Claude Code skills have fundamentally changed how I work with AI-assisted development. The built-in skills (/simplify, /review, /batch) handle the most common developer workflows out of the box. Custom skills let you encode your exact processes, standards, and domain expertise into reusable playbooks. The growing community ecosystem means you rarely need to build from scratch.
The key takeaways from my experience:
- Start with built-in skills. Run /simplify and /review on your current project before building anything custom. They are better than most people expect.
- Invest 30 minutes in project-specific customization. A generic skill is decent. A customized one is transformative. Editing the description and instructions to match your project patterns is the highest-ROI activity.
- Keep SKILL.md lean. Use progressive disclosure — core instructions in SKILL.md, bulk references in supporting files, heavy logic in scripts. Your context window will thank you.
- Version control your skills. Commit project skills to your repository. When teammates clone the repo, they get the skills automatically. This is the simplest way to share workflow knowledge across a team.
If you want to take automation even further, explore how Claude Code hooks can trigger actions and workflows automatically alongside your skills.
|
Pro Tip Run /skills in your next Claude Code session to see everything available. Then try /simplify on a file you recently changed. Most developers are surprised by how much the built-in skills catch. From there, identify one repetitive workflow you perform weekly and write a custom skill for it. That single skill will pay for itself within a day. |
