Claude Code skills are markdown files that give your agent specialized abilities. No SDK. No server. No deployment. You write a SKILL.md file, drop it in the right directory, and Claude Code picks it up the next time it runs.

This guide walks through building a skill from zero to working in under 20 minutes.

What a Skill Actually Is

A skill is a single markdown file named SKILL.md inside a folder under ~/.claude/skills/. The file has two parts: YAML frontmatter that tells Claude Code when and how to use the skill, and a markdown body that contains the instructions the agent follows when the skill runs.

That is the entire architecture. One file. One directory. No build step.

The Directory Structure

~/.claude/skills/
  my-skill/
    SKILL.md

Claude Code scans ~/.claude/skills/ on startup. Each subfolder name becomes the skill’s identifier. The folder name should be lowercase and hyphenated: code-reviewer, deploy-validator, morning-brief.

Step 1: Write the Frontmatter

The frontmatter block sits at the top of SKILL.md between --- fences. Three fields matter:

---
name: deploy-checker
version: 1.0.0
description: |
  Validates a deployment checklist before pushing to production.
  Checks for uncommitted changes, failing tests, missing env vars,
  and open TODO comments. Triggers on: "check deploy," "pre-deploy,"
  "ready to ship?"
allowed-tools:
  - Read
  - Bash
  - Grep
  - Glob
---

name is the skill identifier. Match it to the folder name.

description does two jobs. It tells Claude Code what the skill does, and it tells the agent when to activate. Include trigger phrases at the end. These are the words or slash commands that fire the skill. When a user types “check deploy” or “/deploy-checker,” Claude Code matches against this description and loads the skill.

allowed-tools lists exactly which tools the skill can use. This is a permission boundary. A skill that only reads files should not have Write or Bash access. Keep the list tight. A code review skill needs Read and Grep. A deployment skill needs Bash. A writing skill needs Read, Write, and Edit.

Step 2: Write the Instructions

Below the frontmatter, write the instructions in plain markdown. Think of this as a detailed prompt that Claude Code follows when the skill activates.

# Deploy Checker

Runs a pre-deployment validation checklist. Catches common
issues before code reaches production.

## Checks

### 1. Uncommitted Changes
Run `git status` in the project root. If there are unstaged or
uncommitted changes, flag them immediately. Do not proceed until
the working tree is clean.

### 2. Test Suite
Run `npm test` (or the project's test command). If any test
fails, report which tests failed and stop. Do not deploy with
failing tests.

### 3. Environment Variables
Read `.env.example` and compare against the production env
config. Flag any variable present in the example but missing
from production.

### 4. TODO Comments
Grep the codebase for `TODO` and `FIXME` comments. Report
count and locations. These are not blockers but should be
reviewed before shipping.

## Output Format

Report results as a checklist:
- [x] Clean working tree
- [x] All tests passing (N tests)
- [ ] Missing env var: STRIPE_WEBHOOK_SECRET
- [x] 3 TODO comments found (non-blocking)

Three principles for good instructions:

Be specific about what to do. “Check for issues” is vague. “Run git status and flag unstaged changes” is executable. The agent will follow literal instructions better than interpreted ones.

Set boundaries. Tell the skill what it should not do. A code review skill should not auto-fix code unless asked. A deploy checker should not actually deploy. Boundaries prevent the agent from overreaching.

Define the output format. Tell the agent exactly how to present results. A checklist, a report, a score, a diff. If you leave the format open, every run will look different and none of them will be easy to scan.

Step 3: Handle Arguments

Skills can receive arguments when invoked. If a user types /deploy-checker staging, the word “staging” arrives as an argument. Reference this in your instructions:

## Arguments

If an environment name is provided (e.g., "staging," "production"),
run checks against that environment's config. Default to production
if no argument is given.

Claude Code passes arguments as context when loading the skill. You do not need to parse them programmatically. Just describe what the arguments mean and the agent handles the rest.

Step 4: Test It

Save the file to ~/.claude/skills/deploy-checker/SKILL.md. Open a new Claude Code session (or reload) and type the trigger phrase. The agent should recognize the skill, load the instructions, and execute.

If it does not fire, check three things:

  1. The folder is inside ~/.claude/skills/, not nested deeper
  2. The file is named exactly SKILL.md (capitalized, no prefix)
  3. The description includes clear trigger phrases

Real-World Examples

Here are patterns from production skills running on the AgentNDX skills directory:

A code review skill uses Read and Grep to scan changed files, checks for common patterns (unused imports, console.log statements, missing error handling), and outputs a structured review with severity levels.

A security auditor reads project configuration files, checks for hardcoded secrets, verifies dependency versions against known vulnerability databases, and produces a scored security report.

A content pipeline skill reads a source document, runs it through quality checks (word count, readability, keyword density), and writes the output to a staging directory. It uses Read, Write, Edit, and Grep.

A deployment validator runs the test suite, checks environment variables, verifies the build compiles cleanly, and reports a go/no-go decision with specifics on any blockers.

Common Mistakes

Too many tools. Start with the minimum. Add tools only when the skill needs them. A skill with access to Bash can run arbitrary commands. That is powerful and risky. If the skill only reads files, restrict it to Read and Grep.

Vague instructions. “Review the code for quality” produces inconsistent results. “Check for functions longer than 50 lines, unused variables, and missing return types” produces consistent results every time.

No output format. Without a defined format, the skill produces walls of text. Define the structure: checklist, table, numbered findings, scored report. Pick one and specify it.

Trigger phrases that overlap. If two skills both trigger on “review code,” Claude Code may pick the wrong one. Make triggers specific: “security review” vs. “style review” vs. “PR review.”

FAQ

Q: Can a skill call other skills? A: Not directly. A skill runs as a single instruction set. But you can build a “meta-skill” that tells the agent to invoke other skills in sequence by referencing their slash commands in the instructions.

Q: Where do skills run? A: Skills run inside your Claude Code session on your local machine. They have access to the same filesystem and tools as the agent itself, limited by the allowed-tools list.

Q: Can I share skills with my team? A: Yes. The SKILL.md file is portable. Commit it to a shared repo and have teammates copy it to their ~/.claude/skills/ directory. Some teams keep a skills/ folder in their project repo and symlink from there.

Q: How is a skill different from an MCP server? A: An MCP server exposes external capabilities (APIs, databases, web services) to the agent over a protocol. A skill is a local instruction set that tells the agent how to perform a specific task using its existing tools. Skills are simpler to build and require no infrastructure. MCP servers are more powerful for connecting to external systems. See our comparison guide for details.

Browse the full AgentNDX skills directory for more examples, or check out our guide on combining multiple skills in one workflow.