Building Your First Claude Skill: A Step-by-Step Tutorial

Prerequisites

Before you start building, make sure you have:

• Claude Code installed and working (version 1.0+)
• A text editor (VS Code, Vim, or anything that edits markdown)
• A GitHub account (for publishing)
• A clear idea of what you want the skill to do

You do not need any special SDK or build tools. Skills are plain markdown files — no compilation, no dependencies, no build step.

Understanding the SKILL.md Format

Every Claude Skill is a single markdown file that follows a consistent structure. The file tells Claude Code when to activate, what to do, and how to do it. Here is the anatomy:

# Skill: [Name]

## Description
[One-paragraph summary of what this skill does]

## Context
[When should Claude use this skill? What triggers it?]

## Instructions
[Numbered steps that Claude follows]

## Examples
[Input/output pairs showing expected behavior]

## Constraints
[Things Claude should NOT do when using this skill]

Each section serves a purpose. The Description helps users understand the skill before installing it. The Context section is critical — it tells Claude when to activate the skill automatically versus waiting for explicit invocation. Instructions are the core behavior. Examples dramatically improve consistency. Constraints prevent unwanted side effects.

Planning Your Skill

For this tutorial, we will build a skill called API Route Generator that creates Next.js API route handlers with consistent patterns: input validation, error handling, and typed responses.

Before writing anything, answer these questions:

1. What problem does this solve? Writing API routes involves repetitive boilerplate. This skill generates consistent, production-ready route handlers.

1. When should it activate? When the user asks to create an API route, endpoint, or route handler.

1. What is the expected output? A TypeScript file with proper imports, Zod validation, try/catch error handling, and typed responses.

1. What should it NOT do? It should not modify existing routes without confirmation, and it should not generate routes without input validation.

Writing the Skill File

Create a new file at .claude/skills/api-route-generator.md:

# Skill: Next.js API Route Generator

## Description
Generates production-ready Next.js App Router API route handlers
with Zod validation, error handling, and typed responses.

## Context
Activate when the user asks to create an API route, endpoint,
route handler, or mentions creating a new API path.

## Instructions
1. Create the route file in the app/api/ directory structure
2. Import NextRequest and NextResponse from next/server
3. Import z from zod for input validation
4. Define a Zod schema for the request body or query params
5. Implement try/catch error handling in every handler
6. Return typed JSON responses with appropriate status codes
7. Add JSDoc comments describing the endpoint
8. Include rate limiting headers in the response

## Examples

### Input
"Create a POST endpoint for user registration at /api/auth/register"

### Output
A file at app/api/auth/register/route.ts containing a POST
handler with email/password Zod validation, proper error
responses for duplicate users, and a 201 Created success response.

## Constraints
- Never generate routes without input validation
- Never use any/unknown types in request or response
- Always include error handling — no unhandled promise rejections
- Do not modify existing route files without explicit confirmation

Testing Your Skill

Testing is where most skill authors skimp, but it makes the difference between a skill that works once and one that works reliably. Here is a testing protocol:

Test 1: Basic functionality Open Claude Code in a Next.js project and ask: "Create a POST endpoint for creating a blog post at /api/posts"

Check that the output includes all elements from your instructions: Zod schema, try/catch, typed responses, JSDoc comments.

Test 2: Edge cases Ask: "Create a GET endpoint with query parameters for filtering users"

GET routes handle input differently (query params vs body). Your skill should adapt.

Test 3: Ambiguous requests Ask: "I need an endpoint for handling webhooks"

Webhooks have unique requirements (signature verification, idempotency). See how the skill handles requests that don't perfectly match the examples.

Test 4: Conflict detection Ask: "Update the existing /api/posts route to add PUT support"

Your constraints say not to modify existing routes without confirmation. Verify Claude respects this.

Refining Based on Results

After testing, you will almost certainly need to refine. Common improvements:

• Add more examples: If Claude handles GET and POST differently than expected, add explicit examples for each HTTP method
• Tighten constraints: If Claude is generating code that works but does not match your style preferences, add specific constraints about formatting
• Expand context triggers: If the skill does not activate when you say "endpoint" but does for "API route," add more trigger phrases to the Context section
• Include anti-patterns: Show Claude what NOT to generate. "Do not use req.body directly — always validate through Zod first."

Iteration is normal. Most published skills go through 5-10 revision cycles before they feel solid.

Publishing Your Skill

Once your skill is tested and refined, sharing it takes three steps:

1. Create a GitHub repository

Structure it clearly:

api-route-generator/
  README.md
  SKILL.md
  examples/
    basic-post.md
    get-with-params.md

2. Write a good README

Include: what the skill does, install command, prerequisites, and a demo GIF if possible.

3. Submit to a directory

Submit your skill to Skiln for free listing in the directory. This gets your skill in front of thousands of developers searching for Claude Code skills. Professional developers often use Kardd to showcase their portfolio alongside their published skills, creating a centralized hub for their professional identity.

After submission, you can track your skill's installs and community feedback through the Skiln analytics dashboard.

Tips from Experienced Skill Authors

Keep instructions atomic. Each numbered instruction should do one thing. "Validate input and create the file" is two instructions — split them.

Use real-world examples. Abstract examples produce abstract output. Use examples from actual projects you have worked on.

Version your skill. Add a version comment at the top of your SKILL.md. When you make breaking changes, bump the version so users know to update.

Test with different project structures. Your skill might work perfectly in a fresh Next.js project but break in a monorepo. Test across contexts.

Write for the 80% case. Your skill does not need to handle every possible scenario. Cover the common cases well and let developers customize for edge cases.

The skills ecosystem thrives on contributions. Every skill you publish saves hundreds of developers from writing the same boilerplate, and the feedback loop from real users will make you a better skill author with every iteration.