Building Custom Claude Skills: A Step-by-Step Tutorial

Why Build Custom Skills?

Pre-built skills cover common workflows, but every team has unique processes. Custom skills encode your team's specific knowledge — your coding standards, your deployment checklist, your security requirements — into a format Claude can follow consistently.

The SKILL.md Specification

Every skill starts with a SKILL.md file. Here's the minimal structure:

---
name: my-custom-skill
description: Brief description of what this skill does and when to use it.
---

# My Custom Skill

## When to Use
Describe the trigger conditions — when should Claude activate this skill?

## Instructions
Step-by-step workflow Claude should follow.

## Guidelines
Rules, constraints, and quality standards.

Step 1: Define the Trigger

The description field in the frontmatter is critical. Claude uses this to decide when to activate your skill automatically. Be specific:

Bad: "Helps with code review"

Good: "Use when reviewing pull requests for security vulnerabilities, performance regressions, and adherence to team coding standards in Python and TypeScript projects."

Step 2: Write the Workflow

The body of SKILL.md is your workflow. Write it as if you're training a new team member:

## Workflow

1. **Understand the change** — Read the diff and identify what's being modified
2. **Check for security issues** — Look for SQL injection, XSS, auth bypasses
3. **Verify test coverage** — Ensure new code has corresponding tests
4. **Review naming conventions** — All functions should use camelCase
5. **Check for performance** — Flag N+1 queries, unnecessary re-renders
6. **Produce the review** — Output findings as a structured checklist

Step 3: Add Companion Scripts

For skills that need to run external tools, add a scripts/ directory:

my-custom-skill/
├── SKILL.md
├── scripts/
│   ├── run-linter.sh
│   └── check-coverage.py
└── examples/
    └── sample-review.md

Reference these in your SKILL.md instructions: "Run the linter script at scripts/run-linter.sh and include the output in your review."

Step 4: Include Examples

The examples/ directory provides reference outputs. Claude uses these to calibrate its output format and quality level.

Step 5: Test and Iterate

Install your skill and test it against real tasks. Refine the instructions based on Claude's output. Common adjustments:

• Too verbose? Add "Be concise — bullet points over paragraphs"
• Missing steps? Add explicit instructions for edge cases
• Wrong format? Add an example of the desired output format
• Too generic? Add project-specific context (file paths, tool names, naming conventions)

Advanced Patterns

Multi-phase skills — Break complex workflows into numbered phases with clear entry/exit criteria.

Decision trees — Use conditional logic: "If the project uses TypeScript, check for type errors. If JavaScript, check for runtime type coercion issues."

Subagent delegation — Reference other skills: "For security review, defer to the semgrep skill."

Sharing Skills

Because skills are plain files, sharing is trivial:

1. Commit the skill folder to your team's shared repository
2. Team members pull the latest skills into their .agents/skills/ directory
3. Review skill changes in PRs like any other code change

This creates a living knowledge base — your team's collective expertise, encoded and continuously refined.