What Are Agent Skills?

If you have been following GitHub trends this week, you probably noticed something: Agent Skills are exploding. The mattpocock/skills repository crossed 85,000 stars this week, gaining over 3,000 stars in a single day. Anthropic itself launched an official skills repository. The era of telling AI what to do is over — we are now teaching it how to do specific jobs.

An Agent Skill is a self-contained package of instructions, scripts, and reference materials that teaches an AI coding agent (like Claude Code) how to perform a specific task reliably. Think of it as a plug-in, but instead of code execution, it injects structured knowledge into the agent's context window.

Why Build Your Own Skills?

The skills ecosystem solves real problems:

  • Repetition without context drift. Every time you ask Claude to write a React component, it starts from scratch. A skill gives it your patterns, conventions, and guardrails.
  • Team consistency. Share a skill file and every developer on your team gets the same code quality, naming conventions, and architectural patterns.
  • Complex workflows made simple. Deploy scripts, testing protocols, migration procedures — wrap them in a skill and a single prompt triggers the whole pipeline.

Prerequisites

Before we start, make sure you have:

  1. Claude Code installed (npm install -g @anthropic-ai/claude-code)
  2. A code editor (VS Code, Cursor, or similar)
  3. Basic familiarity with markdown and shell scripting

Step 1: Understand the Directory Structure

Every skill lives in a directory with a SKILL.md file at its root. Here is the minimal structure:

my-skill/
├── SKILL.md          # Required — instructions for the agent
└── scripts/          # Optional — helper scripts
    └── validate.sh   # Example helper script

The SKILL.md file is the brain. It contains instructions, examples, and rules that Claude follows when the skill is active.

Step 2: Write Your First SKILL.md

Let us build a practical skill: API Endpoint Generator. This skill teaches Claude how to create REST API endpoints following your project conventions.

# API Endpoint Generator

## Description
Generates REST API endpoints following the project's established
patterns: Express.js, TypeScript, Zod validation, and error handling.

## Instructions
When the user asks to create an API endpoint:

1. Check the existing codebase for routing patterns
   - Look in `src/routes/` for route files
   - Look in `src/controllers/` for controller files
   - Check `src/middleware/` for auth and validation

2. Create the following files:
   - Route definition in `src/routes/{resource}.route.ts`
   - Controller in `src/controllers/{resource}.controller.ts`
   - Zod schema in `src/schemas/{resource}.schema.ts`

3. Follow these conventions:
   - Use `async/await` (no `.then()` chains)
   - Wrap all route handlers with error middleware
   - Return standardized JSON responses:
     `{ success: boolean, data?: T, error?: string }`
   - Validate all inputs with Zod

4. Register the route in the main router file

## Examples

### GET /users
```typescript
// src/routes/users.route.ts
import { Router } from "express";
import { getUsers } from "../controllers/users.controller";
import { authMiddleware } from "../middleware/auth";

const router = Router();
router.get("/users", authMiddleware, getUsers);
export default router;
```

### POST /users
```typescript
// src/controllers/users.controller.ts
import { Request, Response } from "express";
import { createUserSchema } from "../schemas/user.schema";

export const createUser = async (req: Request, res: Response) => {
  const result = createUserSchema.safeParse(req.body);
  if (!result.success) {
    return res.status(400).json({
      success: false,
      error: "Validation failed",
    });
  }
  const user = await prisma.user.create({ data: result.data });
  return res.status(201).json({ success: true, data: user });
};
```

Step 3: Install the Skill

Claude Code reads skills from its configuration. Add your skill directory to Claude's project config:

# In your project root, create or edit:
# .claude/settings.json

{
  "skills": [
    {
      "name": "api-endpoint-generator",
      "path": "./skills/api-endpoint-generator"
    }
  ]
}

Alternatively, place your skill in the global skills directory (usually ~/.claude/skills/) to use it across all projects.

Step 4: Test Your Skill

Start a Claude Code session and try a simple prompt:

claude

> Create a POST endpoint for creating blog posts

Claude should now follow your SKILL.md instructions and generate files matching your patterns — not its own defaults.

Step 5: Add Helper Scripts (Optional)

For complex workflows, bundle shell scripts with your skill:

#!/bin/bash
# scripts/validate-endpoint.sh
# Validates that a new endpoint follows project conventions

ROUTE_FILE=$1

if [ ! -f "$ROUTE_FILE" ]; then
  echo "Error: Route file not found: $ROUTE_FILE"
  exit 1
fi

# Check for async/await pattern
if grep -q "\.then(" "$ROUTE_FILE"; then
  echo "Warning: Route file uses .then() instead of async/await"
  exit 1
fi

# Check for auth middleware
if ! grep -q "authMiddleware" "$ROUTE_FILE"; then
  echo "Warning: Route is missing authMiddleware"
fi

echo "Validation passed: $ROUTE_FILE"

Reference scripts in your SKILL.md so Claude knows when to run them:

## Validation
After generating endpoint files, run:
`bash scripts/validate-endpoint.sh <route-file>`

Step 6: Share Your Skill

The best part of the skills ecosystem is sharing. To publish your skill:

  1. Create a public GitHub repository
  2. Push your skill directory as the repo root
  3. Share the URL — anyone can clone it and install locally
git clone https://github.com/yourname/api-endpoint-generator.git
cp -r api-endpoint-generator ~/.claude/skills/

Best Practices

PracticeWhy It Matters
Keep instructions specific and unambiguousVague instructions lead to inconsistent outputs
Include real code examplesExamples are more effective than descriptions
Version your skillsUse git tags so teams stay in sync
One skill, one jobComposable skills beat monolithic ones
Test before sharingRun the skill through 5-10 different prompts

What Is Next?

The Agent Skills ecosystem is still early. As more developers contribute, expect skills for everything from database migrations to accessibility audits. The key takeaway: stop repeating yourself to AI. Encode your knowledge once, and reuse it forever.

Start small — one skill, one task. Once you feel the productivity boost, you will never go back to prompting from scratch.