Skills: Reusable Knowledge Packages

Skills vs. Agents vs. Commands

Before we build skills, let's clarify how they differ from agents and commands:

| Feature | Skill | Agent | Command |

|---|---|---|---|

| What it is | Knowledge package | Independent AI instance | Task macro |

| Context | Adds to current context | Own context window | Adds to current context |

| Triggers | Auto or manual | Routing or manual | Manual (/command) |

| Contains | Instructions + templates + scripts | Instructions + config | Instructions + args |

| Token cost | Progressive disclosure (~100 initial) | Full separate context | Full content on invoke |

| Best for | Specialized knowledge domains | Specialized roles | Repeatable task sequences |

Skills are the right choice when Claude needs specialized knowledge to perform a task — not a different identity (that's an agent) and not a fixed sequence (that's a command).

Skill Structure

Skills live in .claude/skills/:

.claude/skills/
└── db-migrate/
    ├── SKILL.md         ← Main skill file (required)
    ├── templates/       ← Template files
    │   └── migration.ts.template
    ├── scripts/         ← Helper scripts
    │   └── validate-schema.sh
    └── references/      ← Reference docs
        └── naming-conventions.md

SKILL.md Anatomy

The SKILL.md file has frontmatter and a body:

---
name: Database Migration
description: Creates and validates Prisma database migrations
disableAutoInvocation: false
disableModelInvocation: false


When to Use This Skill

Use this skill when the user wants to:
Create a new database migration
Modify the Prisma schema
Add or remove tables, columns, or indexes

Steps

1. Read the current prisma/schema.prisma
2. Apply the requested changes
3. Run npx prisma migrate dev --name <migration-name>
4. Validate the generated SQL
5. Update repository files if schema changed
6. Run tests to verify

Templates

Use the migration template at templates/migration.ts.template for
any custom migration scripts.

Naming Conventions

Reference references/naming-conventions.md for table and column
naming rules.

Common Patterns

Adding a Column
1. Add to schema.prisma
2. Set a default value for existing rows
3. Run migrate dev
4. Update related types and DTOs

Creating a Relation
1. Add the foreign key column
2. Add the @relation directive
3. Run migrate dev
4. Verify foreign key constraint in generated SQL

Frontmatter Options

name

Display name for the skill:

---
name: Database Migration
---

description

What the skill does — used for auto-triggering:

---
description: Creates and validates Prisma database migrations
---

Claude uses this description to decide when to auto-invoke the skill.

disableAutoInvocation

Prevents automatic triggering:

---
disableAutoInvocation: true
---

When true, the skill only activates if you explicitly invoke it. Useful for skills you only want on demand (like deployment or destructive operations).

disableModelInvocation

Prevents Claude from invoking the skill on its own:

---
disableModelInvocation: true
---

The skill can only be invoked by you, never by Claude's own decision.

Progressive Disclosure

This is the killer feature of skills. Here's how it works:

Initial Load (~100 tokens)

When a session starts, Claude reads only the frontmatter of each skill:

---
name: Database Migration
description: Creates and validates Prisma database migrations
---

That's about 100 tokens per skill. If you have 10 skills, that's 1,000 tokens — compared to the thousands of tokens the full skill bodies would cost.

On-Demand Load (full body)

When a task matches a skill's description, Claude loads the full SKILL.md body — all the instructions, patterns, and references. This happens only for the triggered skill.

Session starts
  ↓
Load frontmatter for all skills: ~100 tokens each
  ↓
User: "Create a migration to add a status column to orders"
  ↓
Claude: Matches "Database Migration" skill description
  ↓
Load full SKILL.md body: ~2,000 tokens
  ↓
Claude follows the skill's instructions

If the user never asks about migrations, the full skill body is never loaded. Zero wasted tokens.

Building a Complete Skill

API Endpoint Skill

.claude/skills/api-endpoint/SKILL.md:

---
name: API Endpoint Creator
description: Creates new API endpoints following project conventions


When Triggered

When the user wants to create a new API endpoint, route, or handler.

Steps

1. Read the existing routes in src/routes/ for conventions
2. Create the route file in src/routes/
3. Create the handler in src/handlers/
4. Create the service method in src/services/
5. Create the Zod input/output schemas
6. Add to the route registration
7. Create tests

File Templates

Route File (src/routes/<resource>.ts)

typescript

import { FastifyInstance } from 'fastify';

import { createHandler, getHandler, listHandler } from '../handlers/';

export default async function (fastify: FastifyInstance) {

fastify.post('/', createHandler);

fastify.get('/:id', getHandler);

fastify.get('/', listHandler);

}

### Handler Template

typescript

import { FastifyRequest, FastifyReply } from 'fastify';

import { CreateResourceDto, createResourceSchema } from '../schemas/';

import { Service } from '../services/';

export async function createHandler(

request: FastifyRequest<{ Body: CreateResourceDto }>,

reply: FastifyReply

) {

const dto = createResourceSchema.parse(request.body);

const result = await Service.create(dto);

return reply.status(201).send(result);

}

## Rules

Always validate input with Zod
Always use DTOs between layers
Handler → Service → Repository flow
Include error handling with AppError

Code Review Skill

.claude/skills/code-review/SKILL.md:

---
name: Code Review
description: Reviews code changes for quality, security, and conventions
disableAutoInvocation: true


Review Checklist

Security
[ ] Input validation on all user-facing endpoints
[ ] No SQL injection risks
[ ] No XSS vulnerabilities
[ ] Authentication/authorization checks present
[ ] No sensitive data in logs

Quality
[ ] Single responsibility per function
[ ] Error handling is comprehensive
[ ] No duplicated logic
[ ] Types are explicit and correct

Performance
[ ] No N+1 queries
[ ] Appropriate indexes exist
[ ] No unnecessary database calls
[ ] Pagination for list endpoints

Testing
[ ] Tests exist for new code
[ ] Edge cases are covered
[ ] Tests are meaningful (not just coverage)

Output Format

For each finding:
Category: Security / Quality / Performance / Testing
Severity: Critical / Warning / Suggestion
File:Line: Exact location
Finding: Description
Fix: Recommended change

Key Takeaway

Skills are reusable knowledge packages that give Claude specialized expertise on demand. They use progressive disclosure — only frontmatter loads at session start (~100 tokens), and the full body loads only when triggered. This makes skills extremely token-efficient compared to putting everything in CLAUDE.md. Store skills in .claude/skills//SKILL.md with optional templates, scripts, and references. Use skills for knowledge domains (migrations, endpoint creation, code review) and agents for independent roles (security reviewer, test writer).