What Are Claude Code Skills? A Complete Guide (2026)

Mar 20, 2026

I kept loading Claude with the same instructions every time I started a new coding session. “Follow these coding standards. Use this project structure. Check these patterns.” My context window was bloating, and I was wasting tokens on repetitive setup.

Then I discovered Claude Code Skills - a way to package expertise as modular, on-demand instruction files that load automatically when relevant. Let me show you how they work and why they changed my workflow.

The Problem: Context Window Waste

Every time I started a new conversation with Claude, I’d paste in:

Project-specific coding conventions
Architecture patterns we follow
Testing requirements
Git workflow rules

This worked, but it was inefficient. My context window filled up with instructions that might not even be relevant to the current task. When I wanted Claude to focus on frontend work, why was it holding backend patterns in memory?

A Reddit user described the issue perfectly: “Skills are on-demand memory. You want to keep your context as small as possible, so instead of putting everything in memory you keep a repo of loadable skills.”

What Claude Code Skills Actually Are

Claude Code Skills are instruction files (typically named SKILL.md) that Claude automatically loads when relevant context is detected. Think of them as specialized plugins that transform Claude from a general-purpose assistant into a domain-specific expert.

The key insight: instead of permanently occupying context, skills use a three-level progressive disclosure system:

Level 1: Metadata (name + description) - Always loaded (~100 words)
Level 2: SKILL.md body - Loaded when triggered (<5k words)
Level 3: Bundled resources - Loaded as needed (unlimited)

This architecture means metadata stays resident for quick recognition, but full instructions only load when triggered. Reference materials load on-demand.

How Skills Get Triggered

The magic happens through YAML frontmatter descriptions. Here’s how I structure a skill’s trigger:

---
name: backend-patterns
description: Backend architecture patterns, API design, database optimization, and server-side best practices for Node.js, Express, and Next.js API routes.
---

# Backend Patterns

[rest of skill content...]

Claude evaluates the description field against conversation context. When I mention “API routes” or “database optimization,” this skill loads automatically. No explicit invocation needed.

Invocation Modes

Skills support three invocation modes depending on use case:

Mode	User Invokes	Claude Invokes	Use Case
Default	Yes	Yes	General-purpose skills
`disable-model-invocation: true`	Yes	No	Side effects (deploy, send)
`user-invocable: false`	No	Yes	Background knowledge

For a deployment skill that triggers GitHub Actions, I’d set disable-model-invocation: true because I don’t want Claude accidentally deploying. For a coding standards skill, I’d let both user and Claude invoke it.

Setting Up Your First Skill

The minimal structure is dead simple:

.claude/skills/
└── my-skill/
    └── SKILL.md          # Required - this is the skill

But for real projects, I use a more complete structure:

.claude/skills/
└── api-generator/
    ├── SKILL.md           # Main instructions
    ├── scripts/
    │   └── validate.py    # Deterministic validation scripts
    ├── references/
    │   └── schemas.md     # Database schemas and examples
    └── assets/
        └── template.yaml  # Output templates

The key principle: keep SKILL.md focused on instructions. Move detailed schemas, examples, and long-form documentation to references/ so they only load when actually needed.

A Complete SKILL.md Example

Here’s a skill I created for our project’s API development workflow:

---
name: api-development
description: Use when creating or modifying API endpoints, discussing REST/GraphQL design, or implementing backend routes. Covers validation, error handling, and response patterns.
version: 1.0.0
---

# API Development Skill

## When This Skill Applies

- Creating new API endpoints
- Modifying existing routes
- Discussing API design patterns
- Implementing request/response handling

## Core Principles

1. **Validate all inputs** using Zod schemas
2. **Return consistent response format** across all endpoints
3. **Handle errors comprehensively** with proper HTTP status codes
4. **Document with OpenAPI** for all public endpoints

## Request Flow

```text title="api-request-flow.txt"
Request → Validate → Process → Respond
           ↓
         400 Bad Request (validation fails)

Required Imports

Always include these in route files:

import { z } from 'zod'
import { ApiResponse } from '@/types/api'

References

references/validation-patterns.md - Zod schema examples
references/error-codes.md - HTTP status code guidelines

## Dynamic Context Injection

One powerful feature I use is dynamic context injection. Skills can execute commands and include their output:

```yaml title="SKILL.md"
## Current State
- Branch: !`git branch --show-current`
- Status: !`git status --short`
- Last commit: !`git log -1 --oneline`

When this skill loads, Claude sees the actual current state - not static information that quickly becomes outdated.

Common Mistakes I Made

Mistake 1: Vague Descriptions

# TOO VAGUE - triggers too often
description: Helps with coding

# SPECIFIC - triggers appropriately
description: Backend architecture patterns, API design, database optimization, and server-side best practices for Node.js, Express, and Next.js API routes.

The vague description triggered for every coding question. The specific one only loads when I’m actually discussing backend patterns.

Mistake 2: Overloading SKILL.md

I initially put everything in one massive SKILL.md file - schemas, examples, full documentation. Bad idea. The skill took forever to load and wasted context.

Solution: Move detailed content to references/:

references/
├── schemas.md      # Database schemas
├── examples.md     # Code examples
└── troubleshooting.md  # Common issues

Mistake 3: Wrong Invocation Mode

I had a skill that sent Slack notifications. Claude would invoke it during conversations about notifications, causing unwanted messages.

Fix: Added disable-model-invocation: true so only I can trigger it.

Official Plugin Skills

Claude Code comes with pre-built skills through official plugins:

Category	Skills
Plugin Development	skill-development, hook-development
Git Workflows	commit, commit-push-pr
Frontend	frontend-design
Automation	writing-rules

I’ve found the commit skill particularly useful - it knows our commit message format, checks for sensitive data, and follows conventional commits automatically.

Why This Matters

After using skills for a few weeks, I noticed three key benefits:

1. Context Efficiency My context window stays lean. A 100-word metadata entry unlocks thousands of words of specialized guidance when needed.

2. Consistency Across Sessions Claude applies the same patterns and standards whether we’re working on a new feature or debugging an issue from last week.

3. Shareable Expertise I can package our team’s conventions as skills and share them. New team members get the same specialized guidance without lengthy onboarding.

Creating Skills for Your Project

The best skills come from repetition. Ask yourself:

What instructions do I constantly repeat to Claude?
What project-specific patterns should Claude always follow?
What domain expertise would make Claude more helpful?

Take those answers, create a SKILL.md with a clear description, and let Claude discover when to use them.

The Bigger Picture

Skills represent a shift in how we work with AI assistants. Instead of treating the AI as a fixed capability, we’re treating expertise as modular, loadable packages. This approach:

Keeps context minimal until expertise is needed
Applies consistent patterns across sessions
Enables teams to distribute best practices as code
Extends Claude’s capabilities without permanent context cost

For developers using Claude Code, understanding skills unlocks the ability to transform Claude from a general assistant into a specialized partner for any domain or workflow. The key is crafting clear descriptions that trigger skills at the right moment, and organizing content across SKILL.md and bundled resources for optimal context management.

Final Words + More Resources

My intention with this article was to help others share my knowledge and experience. If you want to contact me, you can contact by email: Email me

Here are also the most important links from this article along with some further resources that will help you in this scope:

👨‍💻 Claude Code Skills Documentation
👨‍💻 Claude AI Subreddit

Oh, and if you found these resources useful, don’t forget to support me by starring the repo on GitHub!