How Do Claude Code Skills Work? Complete SKILL.md Guide

Claude Code skills are markdown playbooks stored as SKILL.md files — the agent reads YAML frontmatter for discovery, then loads full instructions only when your task matches. They encode team conventions once so you stop re-pasting the same deploy checklist, review rubric, or SEO workflow every session.

Skills are not a replacement for MCP. Skills tell the agent how to work; MCP gives it live access to GitHub, databases, and APIs.

What Is a Claude Code Skill (SKILL.md)?

A skill is a structured markdown file that teaches Claude Code how to perform a specific task. Think of it as a playbook — you write the steps once, and the agent executes them consistently every time. Skills live in a .claude/skills/ directory (or any directory you configure) and are discovered by scanning for SKILL.md files.

Key Characteristics

• YAML frontmatter with name and description for discovery
• Markdown body with instructions, steps, conventions, and failure handling
• On-demand loading — only the metadata is loaded at session start; full content loads when triggered
• Slash commands — run /seo-audit or /deploy-staging to invoke a skill
• Auto-trigger — if your prompt matches the skill description, Claude may load it automatically

How Does Claude Code Skills Work?

At session start, Claude Code scans your project for SKILL.md files and indexes only the name and description from the YAML frontmatter. This keeps token costs low — even if you have dozens of skills, only a few hundred tokens are used for discovery.

When you type a slash command (e.g., /seo-audit) or your prompt semantically matches a skill description, Claude loads the full SKILL.md body into context. This is called progressive disclosure — the agent fetches details only when needed.

Triggering a Skill

1. Slash command: Type / followed by the skill name (e.g., /deploy-staging). Autocomplete shows matching skills.
2. Auto-trigger: If your prompt closely matches a skill description, Claude may ask or automatically load it.
3. Manual load: You can explicitly request a skill by name.

Example: SEO Audit Skill Trigger

User: "Run an SEO audit on the latest blog post"
Claude: Loads `seo-audit` skill, follows steps to check title, meta, FAQ schema, etc.

SKILL.md Anatomy

---
name: seo-audit
description: Run a SERP-informed SEO audit on a blog post slug using GSC data and FAQ schema rules.
---

# SEO Audit Skill

## When to use
User asks to audit, enrich, or improve CTR on a pristren.com/blog URL.

## Steps
1. Fetch slug from URL path
2. Check title length (50–60 chars) and meta (150–160)
3. Ensure first paragraph answers the target question directly
4. Add or refresh 5–7 FAQ items for FAQPage schema
5. Link to related cluster posts

## Conventions
- No affiliate links
- Practitioner voice — concrete examples from Zlyqor/Pristren production

## Failure handling
- If GSC API returns 429, wait 30 seconds and retry
- If slug not found, ask user for correct URL

The name must match the parent directory. Keep descriptions specific — vague descriptions cause wrong auto-triggers.

Best Practices for Writing Skills

1. One Skill = One Job

Don't create a "do everything" skill. Split into focused skills like deploy-staging, run-tests, code-review. This makes auto-triggering more accurate and keeps each skill under ~500 lines.

2. Numbered Steps

Agents follow sequences reliably when steps are numbered. Use ordered lists for the main workflow, and bullet points for conventions or notes.

3. Explicit Failure Handling

Include what to do when things go wrong: API errors, test failures, missing dependencies. For example:

## Failure handling
- If tests fail, capture output and suggest fixes
- If deploy script missing, run `npm run build` first

4. Link MCP Dependencies

If your skill requires an MCP server (e.g., GitHub, database), mention it in the skill:

## Requirements
- GitHub MCP connected (for PR creation)
- `GITHUB_TOKEN` environment variable set

5. Keep Under ~500 Lines

Split reference material into separate files and reference them from SKILL.md:

See [references/api.md](references/api.md) for API endpoint details.

Installing External Skills

Vendors increasingly ship skills as npm packages. You can install them with:

npx skills add postnifyhq/postnify-agent
export POSTNIFY_API_KEY=your_key

Claude reads the bundled SKILL.md and learns CLI commands without manual copy-paste. This is especially useful for third-party tools like deployment platforms, monitoring services, or AI model providers.

Community Skills

Check the Claude Code Skills Registry for community-contributed skills. You can also publish your own by creating a GitHub repo with a SKILL.md at the root.

Skills + MCP Together

Skills and MCP are complementary. Skills define procedure — the steps to accomplish a task. MCP provides live access to external systems. For example:

• SEO enrichment skill references GSC MCP to fetch query data, then writes markdown locally
• Deploy skill uses GitHub MCP to create PRs and Vercel MCP to trigger deployments
• Code review skill uses GitHub MCP to fetch PR diff and comment

Without MCP, a skill can only operate on local files and static knowledge. With MCP, it becomes a powerful automation that interacts with your entire toolchain.

Compare approaches: Skills vs MCP.

How Much Does Claude Code Skills Cost?

Skills themselves are free — they are just markdown files. However, using skills consumes tokens:

• Discovery: ~50 tokens per skill (name + description)
• Loading full skill: ~500–2000 tokens depending on length
• Execution: varies based on steps and MCP calls

For a typical SEO audit skill (300 lines), loading adds about 1500 tokens. If you run it 10 times a day, that's 15,000 tokens — roughly $0.15 at current Claude Code pricing. Compared to manually typing instructions each time, skills save significant token cost and mental overhead.

Is Claude Code Skills Worth It in 2026?

Absolutely — if you have repetitive workflows. Skills shine when:

• Your team follows consistent conventions (deploy, review, audit)
• You want to enforce best practices without manual oversight
• You onboard new engineers quickly
• You use MCP servers for live data

However, if your tasks are highly variable or one-off, skills may not provide much value. Also, poorly written skills (vague descriptions, missing failure handling) can cause frustration.

Real-World Example

At Pristren, we use skills for:

• SEO audits on every blog post before publishing
• Deploy staging — builds, runs tests, deploys to staging, posts Slack notification
• Code review — checks PR for test coverage, lint errors, and security patterns

Each skill saves ~10 minutes per use. With 50 uses per week, that's 8+ hours saved.

Troubleshooting Common Issues

Skill not triggering

• Check that name matches directory name
• Ensure description is specific (avoid generic phrases like "helps with tasks")
• Verify SKILL.md is in a directory Claude scans (default .claude/skills/)

Skill loads but doesn't execute correctly

• Review steps for ambiguity — agents need explicit instructions
• Add failure handling for edge cases
• Test with a simple prompt first

Token usage too high

• Split large skills into smaller ones
• Use progressive disclosure — keep only essential steps in main SKILL.md
• Reference external files for detailed reference material

Keep Reading

• LLM Token Optimization in 2026 — model routing, caching, MCP audit
• Claude Code Complete Setup Guide — install, CLAUDE.md, MCP, skills
• Claude Code vs Cursor: Token Cost (2026) — dollar math on identical tasks
• AI Model Sprint — June 2026 — frontier model benchmarks

Pristren builds AI-powered software for teams. Zlyqor is our all-in-one workspace — chat, projects, time tracking, AI meeting summaries, and invoicing.