DevToolHub

Want to build skills for Claude and automate your workflows? In short, Claude Skills let you teach Claude how to handle specific tasks — once. Instead of repeating the same instructions every time, you package your workflow into a simple folder, and Claude follows it automatically. In this complete guide, you will learn how to build skills for Claude from scratch, with real-world examples you can use right away.

In this guide, you will learn what skills are, how to build one from scratch, and how to test and share them. We will cover real examples so you can follow along and create your first skill in under 30 minutes.

What Is a Claude Skill and Why Build Skills for Claude?

A skill is a folder with instructions that teach Claude how to do something specific. Think of it like writing a process document for a new team member — except Claude reads it automatically before every relevant conversation.

At its simplest, a skill contains just one file: SKILL.md. Essentially, that file holds everything Claude needs to know about when and how to perform a task.

Here is a quick comparison:

Without Skills	With Skills
You explain your workflow every time	Claude already knows the workflow
Results vary between sessions	Results stay consistent every time
More back-and-forth messages	Fewer messages, faster results
Each user prompts differently	Everyone gets the same quality output

How Does It Work When You Build Skills for Claude?

As mentioned earlier, skills use a three-level loading system. This keeps things fast because Claude does not load everything at once.

At the top sits Level 1 — Always loaded: The YAML metadata at the top of your SKILL.md. This tells Claude when to activate the skill.

Below that is Level 2 — Loaded when needed: The full instructions in your SKILL.md. Claude reads these only when it decides the skill is relevant.

At the bottom is Level 3 — Loaded on demand: Any extra files like scripts, templates, or reference docs. Claude pulls these in only when it needs them.

This matters because, as a result, Claude has a limited context window. For instance, if you dump 10,000 words into one file, you waste tokens even when most of that content is not needed.

Skill Folder Structure to Build Skills for Claude

In practice, every skill follows the same simple layout as shown below:

my-skill-name/
├── SKILL.md          # Required — main instructions
├── scripts/          # Optional — Python, Bash scripts
│   └── validate.py
├── references/       # Optional — extra documentation
│   └── api-guide.md
└── assets/           # Optional — templates, icons, fonts
    └── template.md

Important rules:

• First, the file must be named exactly SKILL.md (case-sensitive). Not skill.md, not SKILL.MD.
• Second, the folder name must use kebab-case: my-cool-skill ✅ and not My Cool Skill ❌
• Do not include a README.md inside the skill folder.
• Do not use “claude” or “anthropic” in your skill name. These are reserved.

Step-by-Step: Build Skills for Claude from Scratch

To get started, let us build a simple skill that helps Claude create consistent API documentation.

Step 1: Create the Folder

mkdir api-doc-generator
cd api-doc-generator

Step 2: Create SKILL.md

Next, create a file called SKILL.md inside the folder:

---
name: api-doc-generator
description: Generates consistent REST API documentation from endpoint descriptions. Use when user says "create API docs", "document this endpoint", "generate API reference", or uploads an API spec file.
---

# API Documentation Generator

## Instructions

When the user asks you to create API documentation, follow these steps:

### Step 1: Gather Endpoint Information
Ask the user for these details (if not already provided):
- HTTP method (GET, POST, PUT, DELETE)
- Endpoint path (e.g., /api/v1/users)
- Request parameters or body
- Response format
- Authentication requirements

### Step 2: Generate Documentation
Use this structure for every endpoint:

**Endpoint:** METHOD /path
**Description:** What this endpoint does
**Authentication:** Required or not
**Request:**
- Headers
- Parameters
- Body (with example)
**Response:**
- Success response (with example)
- Error responses (with examples)

### Step 3: Validate
Before finalizing, verify:
- All required fields are filled
- Examples use realistic data
- Error responses include common status codes (400, 401, 404, 500)

Example Output — Create User Endpoint:

Endpoint: POST /api/v1/users

Description: Creates a new user account.
Authentication: Bearer token required.

Request Body:
{
  "name": "John Doe",
  "email": "john@example.com",
  "role": "developer"
}

Success Response (201):
{
  "id": "usr_abc123",
  "name": "John Doe",
  "email": "john@example.com",
  "created_at": "2026-02-14T10:30:00Z"
}

Error Response (400):
{
  "error": "validation_error",
  "message": "Email is already registered"
}

Step 3: Upload the Skill

Once your skill is ready, consequently you have three options to use it:

Option A — Claude.ai:

1. Zip the api-doc-generator folder
2. Go to Settings > Capabilities > Skills
3. Click Upload skill
4. Select the zip file

Alternatively, Option B — Claude Code:
Place the folder in your Claude Code skills directory.

In addition, Option C — API:
Use the /v1/skills endpoint to upload and manage skills programmatically.

Step 4: Test It

After uploading, therefore open a new conversation with Claude and say:

“Document a GET endpoint for fetching user profile by ID”

As a result, Claude should automatically activate your skill and produce structured API documentation following your exact format.

Writing Good Descriptions to Build Skills for Claude

The description field in your YAML frontmatter is what tells Claude when to use your skill. However, get this wrong, and your skill will never activate.

Bad Descriptions (Do Not Use These)

# Too vague — Claude has no idea when to activate this
description: Helps with documentation.

# No trigger phrases — Claude cannot match user requests
description: Creates sophisticated multi-page API references.

# Too technical — no user would say these words
description: Implements OpenAPI 3.0 spec generation with schema validation.

Good Descriptions (Use These as Templates)

# Clear what + when + trigger phrases
description: Generates REST API documentation from endpoint descriptions. Use when user says "create API docs", "document this endpoint", "generate API reference", or uploads an OpenAPI spec file.

# Includes file types and specific triggers
description: Analyzes Figma design files and generates developer handoff docs. Use when user uploads .fig files, asks for "design specs", "component docs", or "design-to-code handoff".

# Clear scope and trigger phrases
description: Manages Linear project workflows including sprint planning and task creation. Use when user mentions "sprint", "Linear tasks", "project planning", or asks to "create tickets".

Quick tip: For example, after uploading your skill, ask Claude: “When would you use the api-doc-generator skill?” Claude will tell you what it understands from your description. Adjust based on what is missing.

Common Patterns to Build Skills for Claude

Pattern 1: Document and Asset Creation

For instance, this is the most common type, where you teach Claude to produce consistent outputs like documents, code, or designs.

Example — Terraform Module Docs Skill:

---
name: terraform-module-docs
description: Creates standardized Terraform module documentation. Use when user says "document this module", "create module README", or "generate terraform docs".
---

# Terraform Module Documentation

## Instructions

### Step 1: Analyze the Module
Read all .tf files in the module directory. Identify:
- Input variables (variables.tf)
- Output values (outputs.tf)
- Resources created (main.tf)
- Provider requirements

### Step 2: Generate Documentation
Use this exact format:

# Module Name
## Description
One paragraph explaining what this module does.

## Usage
module "example" {
  source = "./modules/module-name"
}

## Requirements
| Name | Version |
|------|---------|
| terraform | >= 1.5.0 |
| aws | >= 5.0 |

## Inputs
| Name | Description | Type | Default | Required |
|------|-------------|------|---------|----------|

## Outputs
| Name | Description |
|------|-------------|

## Resources Created
List all resources with their types.

Pattern 2: Multi-Step Workflow Automation

Similarly, use this pattern when your task involves several steps that must happen in a specific order.

Example — PR Review Skill:

---
name: pr-review-workflow
description: Performs structured pull request code reviews. Use when user says "review this PR", "check this code", or "code review".
---

# Pull Request Review Workflow

## Instructions

### Step 1: Understand the Change
- Read the PR description
- Identify what problem it solves
- Note the files changed

### Step 2: Check Code Quality
For each changed file, verify:
- No hardcoded secrets or credentials
- Error handling is present
- Functions are not too long (under 50 lines)
- Variable names are clear and descriptive
- No commented-out code left behind

### Step 3: Check for Common Issues
- SQL injection risks
- Missing input validation
- Unhandled edge cases
- Breaking changes to public APIs

### Step 4: Write the Review
Structure your review as:

Summary: One paragraph about the overall change.
What looks good: List things done well
Suggestions: List improvements with file and line references
Blockers (if any): List issues that must be fixed before merging
Verdict: Approve / Request Changes / Needs Discussion

Pattern 3: MCP-Enhanced Skills

Furthermore, if you already use MCP (Model Context Protocol) to connect Claude to tools like Notion, Linear, or Slack, skills add the workflow layer on top.

Think of it like this:

• MCP = gives Claude access to your tools (the kitchen)
• Skills = teaches Claude what to do with those tools (the recipes)

Example — Sprint Planning Skill with Linear MCP:

---
name: sprint-planner
description: Plans sprints in Linear using team velocity data. Use when user says "plan this sprint", "create sprint tasks", or "set up next sprint".
metadata:
  mcp-server: linear
---

# Sprint Planning with Linear

## Instructions

### Step 1: Fetch Current State
Call Linear MCP to get:
- Current sprint status and remaining tasks
- Team member workload
- Backlog items sorted by priority

### Step 2: Analyze Capacity
- Check team velocity from last 3 sprints
- Account for any team members on leave
- Calculate available story points

### Step 3: Suggest Sprint Contents
- Pull highest priority backlog items
- Do not exceed team velocity by more than 10%
- Balance work across team members

### Step 4: Create Tasks
For each task, call Linear MCP with:
- Title and description
- Assignee
- Story point estimate
- Priority label
- Sprint assignment

### Step 5: Notify Team
Post sprint summary to the team channel

How to Test Skills You Build for Claude

Fortunately, testing is simple, and you do not need any special framework. Instead, just follow these three checks.

Check 1: Does Your Claude Skill Trigger Correctly?

To begin with, try these queries and see if your skill activates:

Should trigger:

"Help me create API docs for our user service"
"Document this endpoint"
"Generate API reference for the payments module"

Should NOT trigger:

"What is the weather today?"
"Write a Python function to sort a list"
"Help me debug this Docker container"

In that case, if your skill does not trigger when it should, add more keywords to your description field.

If it triggers when it should not, make your description more specific. You can also add negative triggers:

description: Generates REST API documentation. Use for "API docs" or "document endpoint". Do NOT use for general code writing or debugging tasks.

Check 2: Does It Produce Correct Output?

After that, run your main use case 3 to 5 times and check:

• Does the output follow your defined structure?
• Are all required sections present?
• Is the quality consistent across runs?

Check 3: Is It Better Than No Skill?

Finally, to verify the improvement, compare the results:

• Without skill: How many messages did it take? Did you need to correct Claude?
• With skill: Does Claude get it right on the first try?

Tips to Build Skills for Claude That Actually Work

Based on experience, here are some practical tips that work well:

First and foremost, be specific, not vague.

# Bad
Validate the data before proceeding.

# Good
Run python scripts/validate.py --input {filename} to check format.
If validation fails, common issues include:
- Missing required fields (add them to the CSV)
- Invalid date formats (use YYYY-MM-DD)

In addition, include error handling. Tell Claude what to do when things go wrong. Do not assume everything will work on the first try.

Add real examples. Show Claude what a typical interaction looks like from start to finish. This helps Claude understand the expected input and output.

Keep SKILL.md under 5,000 words. Move detailed reference material to the references/ folder and link to it.

Put the most important instructions at the top. Claude pays more attention to content near the beginning of the file.

For critical validations, use scripts instead of words. Code is deterministic. Language interpretation is not. If something must happen every single time, put it in a script.

How to Share and Distribute Skills You Build for Claude

For Individual Users

1. Host your skill folder on GitHub
2. Users download and zip the folder
3. Upload through Claude.ai: Settings > Capabilities > Skills

For Teams and Organizations

Admins can deploy skills workspace-wide. As a result, the entire team gets the same skills automatically — no individual setup needed.

Via API

Moreover, for automated workflows and production use, the Skills API gives you full control:

# List skills
curl https://api.anthropic.com/v1/skills

# Add skill to a request
curl https://api.anthropic.com/v1/messages \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-sonnet-4-5-20250929",
    "max_tokens": 1024,
    "container": {
      "skills": ["your-skill-id"]
    },
    "messages": [{"role": "user", "content": "Document the GET /users endpoint"}]
  }'

Checklist Before You Ship Your Claude Skills

Before you upload, use this checklist to validate your skill:

• ✅ Folder name uses kebab-case
• ✅ SKILL.md file exists (exact spelling, case-sensitive)
• ✅ YAML frontmatter has --- delimiters on both sides
• ✅ name field matches folder name in kebab-case
• ✅ description includes WHAT it does and WHEN to trigger
• ✅ No XML angle brackets in the frontmatter
• ✅ Instructions are specific and actionable
• ✅ Error handling included
• ✅ At least one real example provided
• ✅ Tested triggering works on obvious queries
• ✅ Tested it does NOT trigger on unrelated queries
• ✅ Output is consistent across multiple runs

Troubleshooting When You Build Skills for Claude

Your Claude Skill Will Not Upload

Error: “Could not find SKILL.md”
Your file is not named correctly. Rename it to exactly SKILL.md. Check with:

ls -la | grep SKILL

Error: “Invalid frontmatter”
Your YAML is malformed. Make sure you have the --- delimiters:

# Wrong — missing delimiters
name: my-skill
description: Does things

# Correct
---
name: my-skill
description: Does things.
---

Your Claude Skill Does Not Trigger

Most likely, your description is too vague. As a result, add specific trigger phrases that match what users actually type. Ask Claude: “When would you use the [skill-name] skill?” to see what it understands.

Your Claude Skill Triggers Too Often

To fix this, add negative triggers to your description:

description: Advanced data analysis for CSV files. Use for statistical modeling and regression. Do NOT use for simple data viewing or basic charts.

Claude Does Not Follow Skill Instructions

Your instructions are either too vague or buried too deep. Put critical steps at the top. Use numbered lists. Be explicit:

# Bad
Make sure to validate things properly.

# Good
CRITICAL: Before creating the project, verify:
- Project name is not empty
- At least one team member is assigned
- Start date is not in the past

Final Thoughts

In conclusion, learning to build skills for Claude is not complicated. You are just writing clear instructions in a markdown file — the same way you would write a process doc for your team. The difference is that Claude reads it automatically and follows it every time.

Therefore, start with one workflow you repeat often and build a skill for it. Then, test it a few times and improve it based on what you see. That is all there is to it.

Once you see how much time it saves, you will want to build skills for Claude for every workflow you use.

Helpful Links

• Skills Documentation
• Public Skills Repository
• MCP Documentation
• Agent Skills Blog Post

You Might Also Like

• 👉 Teaching GitHub Copilot New Tricks with Agent Skills in VS Code
• 👉 Deploy LLMs on Kubernetes: Complete Guide with Examples
• 👉 Top Developer Trends You Need to Know in 2025