How Do You Create a Claude Skill for Claude.ai? A Step-by-Step Guide

Mar 17, 2026

Problem

I kept repeating the same instructions to Claude. Every time I started a new coding session, I’d paste the same project guidelines, coding standards, and workflow rules. It was tedious and wasted tokens.

Here’s what I was doing:

1. Start new Claude session
2. Paste 2000 words of project guidelines
3. Paste coding standards document
4. Paste testing requirements
5. Finally ask my actual question

The problem was worse than just repetition. When I worked with team members, we each had our own version of these instructions. Claude gave different results to different people because the context was inconsistent.

I tried saving prompts in a document, but that just moved the problem. I still had to copy-paste every time. And if I updated the prompt, I had to remember to update it everywhere.

What happened?

I searched for a better way to package instructions for Claude and discovered Claude Skills. A skill is a modular package that extends Claude’s capabilities with specialized knowledge and workflows.

The key insight: Skills use progressive disclosure - a three-level loading system that manages context efficiently.

Level 1: Metadata (name + description) - Always loaded (~100 words)
Level 2: SKILL.md body - Loaded when triggered (<5k words)
Level 3: Bundled resources - Loaded only when needed (unlimited)

This means the skill doesn’t hog context until it’s actually needed. Claude reads only the name and description to decide whether to activate the skill. The full instructions load only when triggered.

How to create a skill

Step 1: Create the directory structure

Every skill needs a SKILL.md file. Optional resources go in subdirectories:

my-skill/
├── SKILL.md (required)
│   ├── YAML frontmatter
│   │   ├── name: my-skill
│   │   └── description: When to trigger this skill
│   └── Markdown instructions
├── scripts/          # Executable code (Python/Bash)
├── references/       # Documentation loaded as needed
└── assets/           # Templates, images, fonts

Step 2: Write the SKILL.md frontmatter

The frontmatter is the triggering mechanism. Claude reads only name and description to decide whether to activate the skill.

---
name: tdd-workflow
description: Use this skill when writing new features, fixing bugs, or refactoring code. Enforces test-driven development with 80%+ coverage including unit, integration, and E2E tests.
---

# Test-Driven Development Workflow

This skill ensures all code development follows TDD principles...

The description must answer: What does this skill do? When should it be used?

I learned this the hard way. My first attempt had a vague description:

description: A helpful skill for developers.

Claude never triggered this skill because the description didn’t explain when to use it. I rewrote it:

description: Use this skill when writing new features, fixing bugs, or refactoring code. Enforces test-driven development with 80%+ coverage.

Now Claude triggers the skill when I ask for new features or bug fixes.

Step 3: Write the skill body

The body contains instructions that load AFTER the skill triggers. Keep it concise - under 500 lines to minimize context bloat.

---
name: springboot-tdd
description: Use when developing Spring Boot applications. Enforces TDD with JUnit 5, Testcontainers, and 80%+ coverage.
---

# Spring Boot TDD Workflow

## When to Activate

- Creating new REST endpoints
- Writing service layer logic
- Adding repository methods

## TDD Workflow

### Step 1: Write User Journey
As a user, I want to [action], so that [benefit]

### Step 2: Generate Test Cases
For each user journey, create test cases:

```java title="Example test"
@Test
void shouldCreateUserWhenValidInput() {
    // Arrange
    UserRequest request = new UserRequest("[email protected]");

    // Act
    UserResponse response = userService.create(request);

    // Assert
    assertThat(response.email()).isEqualTo("[email protected]");
}

Step 3: Run Tests (They Should Fail)

Run: ./mvnw test

Step 4: Implement Code

Write minimal code to make tests pass.

Step 5: Verify Coverage

Run: ./mvnw jacoco:report Verify 80%+ coverage.

### Step 4: Add bundled resources (optional)

Scripts, references, and assets extend the skill without bloating the main file.

**Scripts (`scripts/`)**: For deterministic operations that get rewritten repeatedly.

```text title="scripts/ directory"
pdf-skill/
└── scripts/
    ├── rotate_pdf.py
    ├── merge_pdfs.py
    └── extract_text.py

References (references/): Documentation that Claude references when needed.

bigquery-skill/
└── references/
    ├── finance.md (revenue, billing metrics)
    ├── sales.md (opportunities, pipeline)
    └── product.md (API usage, features)

Assets (assets/): Files used in output (templates, images).

frontend-builder/
└── assets/
    └── hello-world/
        ├── index.html
        ├── app.js
        └── styles.css

Real example: Creating a skill

I created a skill for blog writing. Here’s the complete process:

1. Created the directory:

mkdir -p ~/.claude/skills/blog-writer

2. Created SKILL.md with frontmatter:

---
name: blog-writer
description: Tech blog writing skill that generates .mdx posts from plan files. Use when you need to write technical blog posts that answer specific questions with problem-first structure and practical examples.
---

# Blog Writer

Tech blog writing skill for beginner programmers.

## Workflow

### Step 1: Read Plan Files
Find all `plan-*.md` files in the `plan/` directory.

### Step 2: Generate Blog Posts
For each plan, generate a blog post following this structure:

1. Problem (start with the pain point)
2. What happened
3. Solution
4. Reason
5. Summary

### Step 3: Save to Review Directory
Write `.mdx` files to `review/` directory.

3. Tested the skill:

I asked Claude: “Help me write a blog post about Docker networking.”

Claude triggered the skill automatically and followed the workflow in SKILL.md.

The reason skills work

Skills solve three problems:

1. Context efficiency

The progressive disclosure model means skills don’t compete for context until needed. A skill with 10,000 words of references loads only ~100 words initially.

Without skills:
- Paste 2000 words every session
- 2000 words x 10 sessions = 20,000 tokens wasted

With skills:
- Name + description = ~100 words always loaded
- Full instructions = 2000 words loaded once when triggered
- References = loaded only when Claude decides it needs them

2. Consistency

Every team member uses the same skill. The instructions are versioned and shared.

3. Distribution

Skills can be packaged and shared:

# Package a skill
scripts/package_skill.py ~/.claude/skills/my-skill

# Creates: my-skill.skill (a zip file with .skill extension)
# Share via GitHub, download, extract, use

Common mistakes

Mistake 1: Putting “when to use” in the body

The body loads AFTER triggering. Claude can’t read “when to use this skill” sections in the body because it hasn’t loaded the body yet.

---
name: my-skill
description: A helpful skill.
---

# My Skill

Use this skill when:
- Writing tests
- Fixing bugs

Claude never sees those triggers. Put them in the description:

---
name: my-skill
description: Use when writing tests or fixing bugs. Enforces TDD workflow with 80%+ coverage.
---

Mistake 2: Bloated SKILL.md

If SKILL.md is too long, it wastes context when loaded.

SKILL.md (3000 lines)
├── Basic workflow
├── Advanced patterns
├── API reference
├── Examples
└── Troubleshooting

Instead, split into references:

SKILL.md (200 lines)
├── Quick start
└── Links to references/

references/
├── advanced-patterns.md
├── api-reference.md
└── troubleshooting.md

Mistake 3: Missing the description

The description is the trigger. Without a clear description, Claude doesn’t know when to use the skill.

Summary

In this post, I showed how to create Claude skills using the progressive disclosure model. The key point is the SKILL.md frontmatter: the name and description fields are the triggering mechanism, while the body and bundled resources load only when needed.

To create a skill:

Create a directory with SKILL.md
Write frontmatter with name and specific description triggers
Write concise instructions in the body
Add scripts, references, or assets as needed
Package and share

Skills transformed my workflow from repetitive copy-pasting to consistent, efficient context management. Now every session starts with the right context automatically loaded.

Final Words + More Resources

My intention with this article was to help others share my knowledge and experience. If you want to contact me, you can contact by email: Email me

Here are also the most important links from this article along with some further resources that will help you in this scope:

👨‍💻 Claude Skills Documentation
👨‍💻 Reddit: prompt-master skill

Oh, and if you found these resources useful, don’t forget to support me by starring the repo on GitHub!