The complete guide to Claude Code skills

Claude Code is already capable of doing a lot. But out of the box, it has no idea how you work. It doesn't know your stack, your standards, or what a good output looks like for your specific project. Skills are what bridge that gap. They let you define exactly how Claude should behave for any recurring task, and once that's in place, the quality and consistency of what you get back changes completely.

What are skills?

A skill is a Markdown file with instructions that tell Claude how to handle a specific type of task.

Think about onboarding a new developer onto your team. They're skilled, they know how to write good code, and they can figure things out on their own. But on day one, they don't know that your team writes tests before implementation, that PR descriptions follow a specific template, or that certain directories are off-limits without a review. You don't teach them to code. You hand them the team handbook.

A skill is that handbook. You're not teaching Claude how to do the task. It already knows. You're telling it how you want the task done, your way, with your standards.

Before getting into the mechanics, it's worth understanding what Skills are actually designed for.

• Specialization beyond general knowledge: Claude is capable out of the box, but general capability isn't the same as specialized performance. A skill gives Claude the context it needs to handle specific tasks at a higher level: your team's document formats, your data analysis workflows, your code review criteria. The output stops being "good for most situations" and starts being right for yours.

• Capturing knowledge that only exists in your head: every team builds up workflows, conventions, and standards over time. That knowledge usually lives in people's heads, scattered across wikis, or gets re-explained in onboarding calls. Skills give it a permanent, actionable home. Write it once and Claude applies it consistently, without anyone having to remember to mention it.

• Consistent output across the whole team: without a shared Skill, two developers asking Claude for the same type of output get two different results based on how they phrased the request. With a shared project skill, everyone gets output that follows the same standards, regardless of how they asked. This matters more at the team level than it does individually.

• Scalable workflows for organizations: on Team and Enterprise plans, skills can be provisioned organization-wide. That means a workflow defined once by one person becomes available to everyone automatically, without any individual setup required. New team members get the same standards from day one.

How a skill is structured

Every skill lives in its own named folder and requires one file: Skill.md. That file has two parts.

The frontmatter is a YAML block at the top. It defines the skill's name, which becomes the command to invoke it, and a description, which is what Claude reads to decide when to activate it.

---
name: code-reviewer
description: Review code to detect bugs, assess readability, and suggest improvements. Use when the user asks to review code or a pull request.
---

The body is plain Markdown. This is where you write the actual workflow: what to check, in what order, what rules to apply, what the output should look like. Continuing the example above, the body for that code reviewer skill might look like this:

## Workflow
1. Check readability: naming, clarity, and structure.
2. Check complexity: identify logic that is hard to follow or maintain.
3. Check performance: flag obvious bottlenecks or inefficiencies.
4. Flag any function over 50 lines as a refactoring candidate.
5. End with a summary of findings ordered by impact, from highest to lowest.

## Rules
- Do not suggest stylistic changes unrelated to readability or maintainability.
- If a security issue is found at any step, flag it immediately before continuing.
- Keep the tone direct and constructive.

If your Skill.md grows too large, or if some content only applies to specific scenarios, you can split things out into subfolders within the same skill directory. Two common ones are resources/ for supplementary reference files like style guides, brand guidelines, or schemas, and scripts/ for executable code that Claude runs as part of the workflow.

A typical skill folder looks like this:

my-skill/
├── Skill.md
├── resources/
│   └── style-guide.md
└── scripts/
    └── validate.sh

None of the subfolders are required. Start with just Skill.md and add the rest only when a specific task needs it. Reference any additional files from within Skill.md so Claude knows they exist and when to use them.

How Claude loads skills

Claude doesn't load all your skills into memory at once. It uses a system called progressive disclosure, loading only what it needs, when it needs it. Understanding this changes how you write skills.

It works in three levels:

1. Name and description only.

   At the start of every session, Claude scans just the name and description of every available skill. Nothing else. This is how it decides which skill is relevant for a given task.

2. The full Skill.md.

   Once a skill matches a request, Claude reads the full file: your workflow, your rules, your formatting requirements, everything.

3. Scripts and resources.

   These only get loaded if the task specifically needs them. A validation script only runs if validation is part of the current task. Otherwise it doesn't consume any context at all.

The practical implication: you can have many skills installed with substantial content in each, and performance is unaffected until a skill is actually triggered.

The description is the most critical thing you write in any skill. Claude reads descriptions from all available skills at the start of every session to decide which one to activate. If your description is vague or too broad, Claude won't know when to use it and everything inside stays invisible. Keep descriptions short, specific, and clear about both what the skill does and when it should activate.

Sharing skills with your team

Skills aren't limited to personal use. They can be shared across an entire team, which is where they become genuinely powerful as a collaboration tool.

• Personal skills live in ~/.claude/skills/. They're available across all your projects but only for you. Good for experimenting, building drafts, and keeping things specific to your personal workflow.

• Project skills live in .claude/skills/ inside your repository. They get committed to git, and anyone who pulls the repo gets them automatically. This is where team conventions belong: shared workflows, consistent output formats, scripts everyone relies on.

The result is that the whole team works with the same standards, without anyone having to manually sync preferences or re-explain conventions.

You can also control exactly what Claude is allowed to do while a skill is running using the allowed-tools field in the frontmatter. This is a comma-separated list of tool names that restricts Claude to only those capabilities for the duration of the skill.

---
name: code-reviewer
description: Review code to detect bugs and improve quality.
allowed-tools: Read, Grep, Glob
---

The available tools you can allow or restrict are:

By only allowing Read, Grep, and Glob, the skill above can analyze code and search through files, but it can't write, modify, run commands, or reach external services. This is exactly what you want for a review skill: full visibility, zero side effects.

A deployment skill, on the other hand, might need Read, Bash, and WebFetch to read config files, run build scripts, and call an API. The principle is the same: grant only what the task actually requires.

Official skills available to install

Anthropic maintains a set of official skills you can install directly into Claude Code:

https://github.com/anthropics/skills

Install them with:

/plugin install document-skills@anthropic-agent-skills
/plugin install example-skills@anthropic-agent-skills

The repository is organized into two installable groups:

Document skills are production-grade skills that power Claude's built-in file creation capabilities:

• DOCX: creates and edits Word documents: tracked changes, comments, tables, and images. Also reads and extracts content from existing files.

• XLSX: builds spreadsheets with formulas, charts, and formatting. Reads data from existing files and modifies sheets without breaking formula references.

• PDF: extracts text and tables, creates new PDFs, merges and splits documents, rotates pages, fills forms, and runs OCR on scanned files.

• PPTX: creates and edits presentations with layout logic: slide structure, typography, and color palettes. Also parses existing presentations.

Example skills cover a broader range of use cases across three categories:

• Creative and design: skills for generating web interfaces, visual assets, and design-oriented outputs with intentional aesthetic decisions.

• Development and technical: skills for tasks like testing web apps, generating MCP servers, and other developer workflows.

• Enterprise and communication: skills for branding, communications, and repeatable business workflows.

There's also a large community library at https://skills.sh, but approach it with caution. Community skills are not verified by Anthropic, and a skill can include scripts that Claude executes directly on your machine. Those scripts could read files, make external network requests, or run arbitrary commands. Before installing anything from the community, read the Skill.md and review every script. If there's code you don't understand, don't install it.

When to create a skill?

The clearest signal is repetition. If you find yourself typing the same context at the start of multiple conversations, you already have a skill waiting to be written.

Three situations where skills consistently pay off:

• The output depends on context Claude doesn't have. Your stack, your team's conventions, your personal preferences. If every React component request ends with you clarifying that you use Tailwind, that props need default values, that styles go inline, that's a skill.

• The result needs to be consistent across time. If you ask for a technical document and sometimes get headers, sometimes get prose, sometimes get a list of questions back, it's because Claude has no frame of reference for what you want. A skill gives it one.

• The process has steps that keep getting skipped. You want security reviewed before refactoring suggestions. You want a validation step before any file is written. You want every PR summary to include a risk assessment. Without a skill, these happen sometimes and not others.

What doesn't make sense: skills for one-off tasks, or for tasks so context-dependent that fixed instructions would actually get in the way. A skill is a repeatable framework, not a script for every situation.

Building your first skill

The skills that actually stick are the ones that start small and get refined over time, not the ones designed upfront to be perfect.

1. Find what you keep repeating.

   Before writing anything, notice how you currently use Claude. Every time you type the same setup before a request, that's a signal. "Keep in mind we use TypeScript strict mode," "always add a summary at the top," "don't modify files outside src/". If the same instruction has come up three or more times, it belongs in a skill.

2. Create the folder and file.

   Create a folder with a descriptive name and a Skill.md inside it:

   mkdir ~/.claude/skills/your-skill-name
   touch ~/.claude/skills/your-skill-name/Skill.md

3. Write the smallest useful version first.

   Cover the most common scenario only. Don't try to anticipate every edge case. A short, focused skill that Claude follows reliably beats a long one full of instructions it partially ignores.

4. Iterate based on real use.

   Test with actual tasks, not artificial ones. Run the same task with and without the skill and the difference should be obvious. Every time Claude does something unexpected, ask whether that correction belongs in the file. If you're making the same fix repeatedly, move it into the skill and stop relying on in-session corrections.

If you want a guided starting point, there's an official skill in the repository called skill-creator that walks through the whole process from scoping the use case to writing and validating the file.

Once a skill is working well on its own, it can be connected to MCP (Model Context Protocol) servers to interact with external services as part of the workflow. This is where skills stop being instruction files and start being genuine process automation.

Advanced patterns

Once you're comfortable with basic skills, two more advanced patterns are worth knowing.

• Dynamic context injection: using the !command syntax in the skill body, you can run shell commands before Claude processes the content. The output of the command gets injected into the prompt automatically, so Claude always works with real, live data instead of whatever you manually paste in.

  Here's a PR summary skill that fetches the actual diff and recent commits before Claude writes anything:

  ## PR Summary skill
  
  Current diff:
  !git diff main...HEAD
  
  Recent commits:
  !git log main...HEAD --oneline
  
  Open comments on this PR:
  !gh pr view --json comments -q '.comments[].body'
  
  Write a concise PR summary covering what changed, why, and any open discussion points.

  When this skill runs, the three ! commands execute first. Claude never sees the commands themselves; it receives the prompt already populated with the actual diff, the commit list, and the comments. The result is a summary grounded in the real state of the PR, not in whatever context you happened to include in your message.

• Subagent isolation: adding context: fork to the frontmatter runs the skill in a completely isolated context with no access to the current conversation history. This is useful for research or analysis tasks that should stand on their own, where prior conversation context would only add noise.

• Disabling automatic invocation: by default, Claude activates skills automatically when a request matches the description. For sensitive workflows where you want full control over when the Skill runs, you can disable this behavior with the disable-model-invocation: true field in the frontmatter:

  ---
  name: deploy-to-production
  description: Run the full deployment pipeline to production.
  disable-model-invocation: true
  allowed-tools: Bash, Read
  ---

  With this set, Claude will never trigger the skill on its own based on a description match. It only runs when you invoke it manually with the /deploy-to-production command. Useful for anything you wouldn't want firing from a casual mention of the word "deploy" in conversation.

Best practices

These come directly from Anthropic's official authoring guidance.

• Only add context Claude doesn't already have.

  The context window is shared. Every line in your skill competes with the conversation history, other skills' metadata, and the actual request. Claude is already capable; you're not writing a tutorial. Challenge every line: if Claude could figure it out on its own, cut it.

• Nail the description.

  The description is the most important thing in your skill. Claude scans descriptions from all available skills before reading anything else, and uses them to decide which skill to trigger. Write it in third person, include both what the skill does and the specific conditions that should activate it. Keep it under 1024 characters.

  • Bad: description: Helps with documents

  • Good: description: Extract text and tables from PDF files, fill forms, merge documents. Use when working with PDF files or when the user mentions PDFs, forms, or document extraction.

• Use gerund form for skill names.

  Name your skills after the activity they perform: reviewing-code, writing-commit-messages, analyzing-spreadsheets. This makes them easier to reference and clearly communicates what the skill does.

• One skill per workflow.

  Don't build one large skill that tries to do everything. Multiple focused skills compose better and are easier to maintain. Claude can automatically combine multiple skills when a task requires it, so you don't need to anticipate every combination upfront.

• Keep Skill.md under 500 lines.

  If you need more content, move it into separate files in a resources/ subfolder and reference them from the main file. Claude reads additional files on demand, so bundled content doesn't consume context unless it's actually needed for the task.

• Define numbered steps for complex workflows.

  For multi-step tasks, spell out the exact order. Without explicit sequencing, Claude decides what to do first on its own, and that decision varies across runs.

• Build in validation loops.

  If the skill produces output, have Claude validate it before finishing. The pattern is: execute, validate, fix, repeat. This applies to code generation, document creation, and any task where output quality can be checked programmatically or against a checklist.

• Watch how Claude actually uses the skill.

  Pay attention to which files Claude reads, in what order, and which ones it ignores. If Claude consistently skips a file, either the reference to it isn't clear enough or the content isn't needed. If Claude reads the same file repeatedly, that content probably belongs in the main Skill.md.

Conclusion

Building good skills takes practice. It requires being precise about what you're asking for, thinking through edge cases, and being willing to iterate. But the underlying loop is simple: find something you repeat, write it down once, test it, refine it.

Start with something small. A skill that summarizes a document, formats a pull request description, or structures a code review. It doesn't matter if you delete it after a week. The point is to build the habit of noticing what's worth automating and getting comfortable with the format. Everything else follows from there.