How to Use Claude Code Skills — The Complete Guide

What Are Claude Code Skills?

Claude Code Skills are markdown-based instruction files that teach Claude Code how to perform specific types of tasks with domain expertise.Anthropic describes them as "dynamic context loading" -- rather than stuffing every instruction into a single CLAUDE.md file that consumes tokens on every conversation, skills load only when they are relevant to the current task.

Skills solve a fundamental problem that every team encounters as they adopt Claude Code: the CLAUDE.md file grows unmanageably large. A mature project might need instructions for frontend conventions, backend API patterns, database migration workflows, testing standards, deployment procedures, and documentation formats. Loading all of this into context on every single interaction wastes tokens and dilutes Claude's attention.

With skills, you decompose those instructions into focused, modular files. A frontend design skill loads when you are building UI components. A testing skill loads when you are writing tests. A deployment skill loads when you are preparing a release. Each skill provides deep, specialized guidance exactly when it is needed, and stays out of the way when it is not.

Skills can be invoked in three ways: manually via slash commands (e.g., /design), automatically through trigger patterns that match keywords or file types in your conversation, or programmatically by other skills that reference them in composition chains. This flexibility makes skills the most powerful customization mechanism in the Claude Code ecosystem.

Skill File Format

A Claude Code skill file is a standard markdown file with YAML frontmatter that defines metadata and an optional trigger condition. The frontmatter tells Claude Code how to identify, describe, and activate the skill. The body contains the actual instructions that Claude follows when the skill is loaded.

Frontmatter Fields

The YAML frontmatter block supports these fields:

• --name (required): A short, human-readable name displayed in skill listings and slash command suggestions.
• --description (required): A one-sentence summary that helps Claude Code determine when this skill is relevant. Write this as a "use when" statement for best automatic matching.
• --trigger (optional): A keyword pattern, file glob, or contextual condition that causes the skill to load automatically. Examples: "*.tsx", "test", "deploy".

Example Skill File

Here is a complete skill file for enforcing a project's API design conventions:

The body supports all standard markdown including headings, lists, code blocks, tables, and links. Claude Code parses the full document and treats every instruction as a directive to follow when the skill is active.

Creating Your First Skill

To create your first Claude Code skill, you need three things: a skills directory, a markdown file with frontmatter, and instructions that solve a real problem your team faces repeatedly. The entire process takes under five minutes.

Step-by-Step Walkthrough

1. 1.
   Create the skills directory. In your project root, create the .claude/skills/ directory. If you already have a .claude/ folder for your CLAUDE.md or settings, just add the skills/ subdirectory.

   mkdir -p .claude/skills
2. 2.
   Create your skill file. Name it something descriptive. The filename becomes part of how Claude Code identifies the skill, so use clear, lowercase names with hyphens.

   touch .claude/skills/code-review.md
3. 3.
   Write the frontmatter. Open the file and add the YAML frontmatter block at the top. Include at minimum a name and description.
4. 4.
   Write actionable instructions.The body should contain specific, opinionated guidance. Avoid vague statements like "write good code." Instead, specify exact patterns: "Use early returns to reduce nesting. Maximum function length is 30 lines. Prefer composition over inheritance."
5. 5.
   Test the skill. Start a Claude Code session and invoke your skill with a slash command matching the skill name. Verify that Claude follows your instructions by giving it a task the skill covers.

   > /code-review Review the changes in src/auth/login.ts
6. 6.
   Iterate and refine. Skills are living documents. After using a skill on several real tasks, you will discover gaps or overly broad instructions. Tighten the language, add examples, and remove anything Claude consistently ignores or misinterprets.

For a deeper walkthrough with more examples, see our dedicated step-by-step skills building tutorial.

Frontend Design Skills

Frontend design skills are the most impactful category of skills because they prevent the "AI slop" aesthetic -- that generic, lifeless look that AI-generated interfaces often produce.As highlighted in Anthropic's official blog, the key to premium AI-generated UI is providing Claude with opinionated design tokens rather than letting it make aesthetic choices from scratch.

Typography Skills

Typography is where most AI-generated interfaces fall flat. A typography skill specifies exact font pairings, size scales, and weight distributions. For example, pairing Playfair Display for headings with JetBrains Mono for code blocks and a clean sans-serif like Inter for body text immediately elevates the output beyond generic defaults.

Your typography skill should define a type scale (e.g., 12px, 14px, 16px, 20px, 24px, 32px, 48px, 64px), specify line heights for each size, set maximum line widths for readability (65-75 characters), and define letter-spacing adjustments for large headings. These constraints produce typography that feels designed rather than defaulted.

Color and Theme Skills

Color skills should define your palette using CSS custom properties, specify dominant vs. accent color ratios (typically 60/30/10), and include both light and dark theme variants. A well-crafted color skill includes semantic color tokens like --color-success, --color-warning, and --color-destructive alongside the brand palette, ensuring consistent visual communication across every component Claude generates.

Motion Skills

Motion skills define animation patterns that bring interfaces to life without overwhelming users. The most effective pattern is staggered reveals -- where list items, cards, or sections animate in sequentially with a slight delay between each element. Your motion skill should specify easing curves (e.g., cubic-bezier(0.16, 1, 0.3, 1) for a premium feel), duration ranges (150ms-400ms for micro-interactions, 400ms-800ms for page transitions), and rules about when motion should be disabled (prefers-reduced-motion).

Background and Layout Skills

Background skills handle layered gradients, subtle textures, and glass-morphism effects that add visual depth. A background skill might specify a gradient mesh using 3-4 color stops with radial gradients positioned at different viewport corners, combined with a subtle noise texture overlay at 2-5% opacity. Layout skills define spacing scales, maximum content widths, breakpoint behaviors, and grid systems that ensure consistency across every page Claude builds.

Testing Skills

Testing skills enforce a consistent test-driven development (TDD) workflow by defining test file structure, naming conventions, coverage thresholds, and the red-green-refactor cycle that Claude should follow. Without a testing skill, Claude tends to write tests as an afterthought. With one, it writes tests first and implements code to satisfy them.

TDD Workflow Skills

A TDD workflow skill instructs Claude to follow a strict sequence: first, write a failing test that describes the expected behavior. Second, write the minimum implementation that makes the test pass. Third, refactor the implementation while keeping tests green. This skill should specify that Claude must run the test suite after each step and report the results before proceeding to the next step.

Test Naming Conventions

Test naming is one of the highest-impact areas for a testing skill. A good pattern is the "should...when..." format: it('should return 401 when the token is expired'). Your skill should enforce that test names describe behavior (not implementation), group related tests in describe blocks by feature or method, and include both happy path and edge case coverage. Specifying 5-8 test cases as minimum per function ensures Claude does not write superficial tests.

Coverage Requirements

Your testing skill can specify coverage thresholds that Claude should target: for example, 90% line coverage for business logic, 80% for utility functions, and 100% for public API surfaces. Include instructions for testing error paths, boundary conditions, and concurrency scenarios. Specifying that integration tests should use test databases (not mocks) for data layer code prevents the common pitfall of tests that pass but do not actually verify real behavior.

Skill Composition

Skill composition is the practice of combining multiple skills to handle complex tasks that span several domains.When you ask Claude Code to "build a user profile page with tests," it can activate both your frontend design skill and your testing skill simultaneously, applying design conventions to the UI and TDD practices to the implementation.

Composition works because skills are additive -- their instructions merge into Claude's active context without conflicting, provided each skill focuses on a distinct domain. A frontend skill governs visual decisions. A testing skill governs test structure. An API skill governs endpoint design. When all three load for a full-stack feature, Claude produces code that is visually polished, well-tested, and API-consistent.

Priority Ordering

When multiple skills load simultaneously, their instructions are applied in the order they are loaded. If two skills contain conflicting guidance -- for example, one says "use Tailwind" and another says "use CSS modules" -- the skill loaded last takes precedence. To manage priority explicitly, you can invoke skills in a specific order using slash commands, or use the trigger field to control automatic loading order based on specificity.

Best practice: keep skills orthogonal. If two skills might conflict, merge them into a single skill or add explicit override rules in the higher-priority skill. Clear boundaries between skills -- one for styling, one for logic, one for testing -- eliminate most composition conflicts naturally.

Global vs Project Skills

Claude Code supports two skill locations: project-level skills in .claude/skills/ at the project root and global skills in ~/.claude/skills/ in your home directory. Each location serves a different purpose in your development workflow.

Project Skills

Project skills live in your repository and are committed to version control. They contain project-specific conventions: your component library patterns, your API response format, your database migration workflow, your test setup. These skills are shared with every team member who clones the repository, ensuring consistent Claude Code behavior across the team. When a new developer joins, they immediately get the same skill-enhanced experience without any manual configuration.

Global Skills

Global skills are personal preferences that apply across all your projects. Typical global skills include your preferred code review checklist, your git commit message format, your documentation writing style, or a personal coding standard you follow regardless of the project. Global skills load after project skills, so they can override project defaults when needed -- though this should be done carefully to avoid surprising teammates who expect project-level behavior.

Resolution Order

When Claude Code starts a session, it discovers skills in this order: 1) project-level skills from .claude/skills/, 2) global skills from ~/.claude/skills/. If both locations contain a skill with the same name, the project-level skill takes priority. This mirrors the convention used by tools like ESLint and Prettier, where project config overrides user config.

Advanced Patterns

Advanced skill patterns go beyond simple instruction files to create intelligent, context-aware behaviors that adapt to different situations. These patterns are used by teams managing large codebases with complex workflows.

Conditional Logic in Skills

Skills can include conditional instructions that Claude evaluates at runtime. For example, a deployment skill might say: "If the target branch is main, require all tests to pass and run the full E2E suite. If the target branch is a feature branch, run only unit tests." Claude interprets these conditionals intelligently, adapting its behavior based on the current context without requiring separate skill files for each scenario.

Checklist-Based Skills

Checklist skills provide a structured sequence of verification steps that Claude works through methodically. This pattern is powerful for code review, security audits, or pre-deployment checks. Each checklist item becomes a gate that Claude must evaluate before proceeding:

Trigger Pattern Strategies

Sophisticated trigger patterns use multiple keywords to improve activation accuracy. Instead of triggering on a single word like "test," which might fire during unrelated conversations, use compound triggers like "write test spec coverage". Claude Code matches any of the trigger words, so listing several related terms reduces false negatives while the specificity of each term reduces false positives. File-glob triggers like "*.test.ts" are the most precise -- they activate only when Claude is working with files matching the pattern.

Template-Based Generation Skills

Some skills include code templates that Claude uses as starting points for new files. A React component skill might include your standard component template with imports, prop types, default export, and test file structure. Claude fills in the template with context-specific details rather than generating from scratch, which dramatically improves consistency across a codebase. This approach reduces the variance in AI-generated code from "creative interpretation" to "structured customization."

Skills vs CLAUDE.md vs System Prompts

Skills, CLAUDE.md files, and system prompts each serve different roles in configuring Claude Code's behavior. Understanding when to use each mechanism is critical for keeping your setup maintainable as your project grows. Here is a detailed comparison:

The general rule: put persistent, always-relevant instructions in CLAUDE.md. Put specialized, task-specific expertise in skills. Use system prompts only for API-level configuration that is not project-specific.

Best Practices

The most effective skills are short, opinionated, and tested against real tasks. Here are seven best practices distilled from teams that have deployed skills in production environments.

1. 1.
   Keep skills under 500 lines. A skill that is too long dilutes its own effectiveness. If Claude has to process 2,000 lines of instructions for a single domain, it may miss critical rules buried in the middle. Split oversized skills into 2-3 focused sub-skills.
2. 2.
   Use imperative language.Write "Use early returns" instead of "You might consider using early returns." Claude responds better to direct instructions than suggestions. Treat skill files like style guides, not blog posts.
3. 3.
   Include concrete examples. Every major rule in your skill should be followed by a code example showing the correct pattern. Claude is significantly more accurate when it has a template to follow rather than an abstract description to interpret.
4. 4.
   Test skills on real tasks before sharing. Run your skill through 5-10 representative tasks before committing it to the team repository. Note where Claude deviates from your intent and tighten the instructions. A skill that works for simple cases but fails on edge cases erodes team trust.
5. 5.
   Version your skills alongside your code. Skills evolve as your project evolves. When you change your component library from Material UI to Radix, update your frontend skill in the same PR. Stale skills that reference deprecated patterns cause Claude to generate outdated code.
6. 6.
   Write "do not" rules sparingly but explicitly.Negative constraints like "Do not use any or unknown types in TypeScript" are highly effective because they create hard boundaries. But too many negative rules make a skill feel restrictive. Aim for a 4:1 ratio of positive to negative instructions.
7. 7.
   Use the description field for discoverability.Write descriptions as "Use when..." statements: "Use when building React components with Tailwind CSS." This helps Claude Code match skills to tasks accurately during automatic activation and helps team members find the right skill when browsing the directory.

Frequently Asked Questions

Related Resources

Continue learning about Claude Code skills and the broader ecosystem with these resources:

• --Skills Directory -- Browse and discover community-contributed Claude Code skills ready to use in your projects.
• --Build Claude Code Skills -- A hands-on tutorial walking through building production-quality skills from scratch.
• --Questions & Answers -- Find answers to common Claude Code questions from the community.
• --MCP Servers -- Explore the MCP server ecosystem that works alongside skills to extend Claude Code.
• --CLAUDE.md Guide -- Learn how to write effective CLAUDE.md files that complement your skills setup.