What Are Claude Skills and Why Should You Care?

This is Part 1 of a 3-part series on building skills for Claude. If you’ve ever wished Claude could just remember how you like things done, this series is for you.

The Problem Skills Solve

Here’s a scenario that probably sounds familiar. You open a new conversation with Claude. You explain your coding standards. You describe the output format you want. You remind it about your team’s naming conventions, your preferred testing framework, the way you like pull request descriptions structured.

Then you do it all again tomorrow.

Every new conversation starts from zero. There’s no institutional memory. No continuity. You’re burning tokens re-explaining context that hasn’t changed since last week. And the outputs? They’re inconsistent. Monday’s code review follows your standards. Tuesday’s doesn’t, because you forgot to paste in that formatting prompt you refined three weeks ago.

This is the problem that skills solve.

A skill is a set of persistent instructions that Claude loads automatically when relevant. Instead of re-explaining your workflow every session, you encode it once. Claude picks it up when it needs it. Your standards stay consistent. Your tokens go toward actual work instead of repeated setup.

If you’ve ever maintained a CLAUDE.md file or a custom system prompt, you’ve already been doing a primitive version of this. Skills formalise the pattern and make it scalable.

What Is a Skill?

At its simplest, a skill is a folder containing a SKILL.md file. That file holds the instructions Claude follows when the skill is activated. Beyond that, you can bundle templates, example outputs, scripts, and reference documentation alongside it.

Here’s what a typical skill folder looks like:

my-skill/
  SKILL.md           # Main instructions (REQUIRED)
  template.md        # Template for Claude to fill in
  examples/
    sample.md        # Example output
  scripts/
    validate.sh      # Script Claude can execute
  reference/
    guide.md         # Detailed docs loaded on-demand

The only required file is SKILL.md. Everything else is optional and loaded on demand.

I like to think of skills using a cooking analogy. If you’re building AI-powered workflows, MCP (Model Context Protocol) provides the kitchen: the tools, the connectivity, the access to external systems. Skills provide the recipes: the domain knowledge, the workflow logic, the step-by-step instructions for producing a specific outcome.

A kitchen full of tools is useless without recipes. A recipe is useless without a kitchen. Together they enable complex workflows that neither could accomplish alone. A skill can reference MCP tools to pull data from Jira, check GitHub PRs, and push summaries to Confluence, all following a codified process that produces consistent results every time.

Progressive Disclosure: Why Skills Don’t Bloat Your Context

One of the first questions people ask is: “If I have fifty skills, won’t that eat up my entire context window?”

No. And the reason is progressive disclosure: a three-level system that makes skills remarkably token-efficient.

Level 1: Metadata (~100 tokens per skill)

This is always loaded at startup. It’s just the skill’s name and description from the YAML frontmatter at the top of SKILL.md. Claude reads these to know what skills exist and when to activate them.

With fifty skills, you’re looking at roughly 5,000 tokens of metadata. That’s negligible in a 200k context window.

Level 2: Instructions (under 5k tokens)

When Claude decides a skill is relevant to the current task, it loads the full SKILL.md body. This contains the actual instructions, workflow steps, formatting rules, and decision logic. A well-written skill body stays under 5,000 tokens.

This only loads when triggered. If you’re writing code and your sprint-planning skill isn’t relevant, it stays at Level 1.

Level 3+: Resources (effectively unlimited)

The bundled files (templates, examples, scripts, reference docs) are loaded individually as Claude needs them. A skill could bundle 50 pages of API documentation, and it costs zero tokens until Claude actually reads a specific file.

This is the key insight: you can bundle unlimited reference material with zero context penalty until it’s accessed. A skill that includes a complete style guide, ten example outputs, and three validation scripts uses roughly 100 tokens at rest. The heavy resources only load when Claude needs them for the current task.

This three-level system means you can scale to dozens or even hundreds of skills without worrying about context bloat. Each skill is a lightweight pointer until it’s needed.

Core Design Principles

Skills aren’t just a Claude-specific hack. They follow a set of design principles that make them genuinely useful across different contexts.

Composability

Skills can reference other skills and call MCP tools. A code-review skill might invoke your git-conventions skill for naming standards, then use a GitHub MCP server to fetch PR diffs. You build small, focused skills and compose them into larger workflows.

Portability

Skills work across Claude.ai, Claude Code, and the API. Write a skill once, use it everywhere. The same SKILL.md file that powers your Claude Code CLI workflow works in a web conversation or an API integration.

Open Standard

Skills follow the Agent Skills open standard at agentskills.io. This isn’t a proprietary format locked to one vendor. The specification is open, which means the skills you build today aren’t trapped in a single ecosystem.

Skills + MCP: Better Together

I touched on the kitchen-and-recipes analogy earlier. Let me make this more concrete with a comparison.

MCP handles connectivity: standardised access to external systems through a common protocol. It gives Claude the ability to read from databases, call APIs, interact with cloud services, and pull data from dozens of tools.

Skills handle expertise: the domain knowledge and workflow logic that turns raw tool access into reliable outcomes. An MCP server can fetch data from Sentry. But a skill layers code review expertise on top of that data to produce actionable analysis.

This is exactly what Sentry’s sentry-code-review skill does. It combines Sentry’s MCP server (which provides access to error data, performance metrics, and issue tracking) with a skill that codifies a code review methodology. The skill instructs Claude to automatically analyse GitHub PRs by cross-referencing them against Sentry data — checking whether the PR introduces patterns that have historically caused errors, flagging performance regressions, and suggesting improvements based on production telemetry.

Without the skill, you’d get raw data. With the skill, you get expert analysis.

Three Categories of Skills

As I’ve built and studied skills over the past few months, I’ve noticed they fall into three broad categories.

1. Document and Asset Creation

These skills produce consistent outputs: presentations, code modules, design documents, spreadsheets. They follow embedded standards and templates. Every output matches your format. Every time.

Examples include frontend-design (generates UI components following your design system), docx (creates Word documents with your corporate formatting), pptx (builds slide decks following your presentation template), and xlsx (generates spreadsheets with consistent structure and formulas).

The pattern here is: template + rules + examples = consistent output. You encode the standard once, and every future output matches it.

2. Workflow Automation

These skills codify multi-step processes that follow a consistent methodology. Deploy workflows, code review processes, research synthesis, incident response, anything where the value is in following the same reliable steps every time.

The common pattern is checklists, sequential steps, and feedback loops. A deployment skill might: run tests, check coverage thresholds, build the artifact, deploy to staging, run smoke tests, wait for approval, deploy to production, and verify health checks. Each step is codified. None get skipped.

3. MCP Enhancement

These skills layer domain expertise onto MCP tool access. They don’t replace MCP. They make it dramatically more useful by adding context, methodology, and decision logic.

The Sentry example I mentioned earlier is a perfect case. The MCP server provides the data pipeline. The skill provides the expertise to interpret that data and produce actionable recommendations. You could build similar enhancement skills for any MCP server: a cloud-cost-analysis skill that layers FinOps expertise onto AWS cost data, or a security-audit skill that applies compliance frameworks to infrastructure scan results.

Planning Your First Skill

Before you write any YAML, start with your pain points. What do you repeat every conversation? What workflows produce inconsistent results? Where do you waste the most time on setup and context-loading?

Here’s an example of how to frame a skill use case:

Use Case: Project Sprint Planning
Problem: Sprint planning requires checking 3 tools (Jira, GitHub, Confluence),
         following a 12-step process, and producing a formatted summary.
Current: Takes 45 minutes, inconsistent format, often misses steps.
With Skill: Automated workflow, consistent output, 10 minutes.

Ask yourself three questions:

1. What triggers this skill? (e.g., “when I say ‘start sprint planning’” or “when I’m reviewing a PR”)
2. What tools does it need? (e.g., Jira MCP server, GitHub MCP server)
3. What does success look like? (e.g., a formatted sprint summary with all 12 steps completed)

Define success criteria that are both quantitative (time saved, consistency rate, error reduction) and qualitative (output quality, team satisfaction, reduced cognitive load).

Once you’ve identified your use case, the first concrete step is writing the YAML frontmatter for your SKILL.md. This is the metadata that Claude reads at startup, the Level 1 information that determines whether and when your skill gets activated.

---
name: sprint-planning
description: >
  Runs the weekly sprint planning workflow. Pulls open issues from Jira,
  checks PR status in GitHub, and generates a formatted sprint summary
  in Confluence. Use when starting a new sprint or reviewing sprint readiness.
---

The description field is critical. It’s what Claude uses to decide whether your skill is relevant to the current task. A vague description means your skill never gets triggered. An overly technical one means Claude can’t match it to natural language requests.

Here’s what good and bad descriptions look like:

# BAD: Too vague
description: Helps with project management

# BAD: Too technical, doesn't say when to use
description: Queries JIRA API endpoint /rest/agile/1.0/board/{boardId}/sprint

# GOOD: What it does + when to use it + key capabilities
description: >
  Runs the weekly sprint planning workflow. Pulls open issues from Jira,
  checks PR status in GitHub, and generates a formatted sprint summary
  in Confluence. Use when starting a new sprint or reviewing sprint readiness.

The good description follows a simple formula: what it does (runs the sprint planning workflow), how it does it (pulls from Jira, checks GitHub, generates in Confluence), and when to use it (starting a new sprint or reviewing readiness). Include all three, and Claude will reliably match your skill to the right requests.

What’s Next

In Part 2, we’ll get hands-on: building your first skill from YAML frontmatter to working workflow, including testing strategies that ensure your skill triggers reliably and produces consistent results. We’ll walk through a complete skill build, file by file, and cover the common mistakes that trip people up.

Part 2: Building Your First Skill →