Introduction
If you are using AI coding assistants like Claude Code, Cursor, or Codex, you have probably noticed something exciting happening in 2026: skills and plugins are transforming these tools from general-purpose helpers into specialized agents that understand your exact workflow. GitHub's trending page is dominated by repositories like anthropics/skills, cursor/plugins, and EveryInc/compound-engineering-plugin — proof that the developer community is all-in on customizing their AI tooling.
This tutorial walks you through building a custom skill for an AI coding agent, step by step, so your assistant becomes genuinely useful for your specific project.
What Are AI Coding Agent Skills?
Skills are structured instruction files that teach an AI coding agent how to perform specific tasks within your codebase. Think of them as domain-specific playbooks:
- Standard behavior: The AI guesses what you want based on general programming knowledge.
- With skills: The AI follows your conventions, uses your patterns, and respects your architecture decisions.
The most common format is a SKILL.md file that lives in a skills/ directory, containing natural-language instructions, file paths, and example commands.
Step 1: Identify the Skill Scope
Before writing anything, decide what problem you are solving. Good candidates for skills:
- Running test suites with project-specific flags
- Deploying to your infrastructure with the right sequence of commands
- Generating documentation following your style guide
- Creating new feature scaffolds (routes, components, migrations)
- Database migration workflows unique to your stack
Example: You want the AI to create new API endpoints following your team's Express.js + TypeScript pattern.
Step 2: Create the Skills Directory
At the root of your project, create a skills folder:
mkdir -p .agent/skills/api-generator
This location keeps skills version-controlled alongside your code but separate from application logic.
Step 3: Write the SKILL.md File
Create the skill definition file:
touch .agent/skills/api-generator/SKILL.md
Here is a complete example:
# API Endpoint Generator
## Description
Creates new REST API endpoints following the project's Express.js + TypeScript conventions.
## When to Use
- User asks to create a new API endpoint or route
- User wants to add CRUD operations for a resource
- User mentions creating controllers, routes, or services
## Steps
1. Identify the resource name (singular, camelCase for files, PascalCase for classes)
2. Create the following files:
- `src/controllers/${Resource}Controller.ts`
- `src/routes/${resource}Routes.ts`
- `src/services/${Resource}Service.ts`
3. Register the route in `src/routes/index.ts`
4. Add OpenAPI/Swagger annotations to each endpoint
5. Write unit test stubs in `tests/controllers/${resource}.test.ts`
## Conventions
- Always use async/await, never callbacks
- Error handling: throw `AppError` from `src/utils/errors.ts`
- Response format: `{ success: boolean, data: any, message?: string }`
- Validation: use Zod schemas in `src/validators/`
- Database: Prisma ORM, all queries go through service layer
## Examples
### Create endpoint skeleton for "Product"
\`\`\`typescript
// src/controllers/ProductController.ts
import { Request, Response } from "express";
import { Product } from "@prisma/client";
import { ProductService } from "../services/ProductService";
import { AppError } from "../utils/errors";
export class ProductController {
static async getAll(req: Request, res: Response) {
const products = await ProductService.getAll();
res.json({ success: true, data: products });
}
}
\`\`\`
Step 4: Reference the Skill in Your Agent Config
Most AI coding agents need to know where to find skills. The typical configuration:
{
"skills": [
{
"name": "api-generator",
"path": ".agent/skills/api-generator/SKILL.md"
}
]
}
For Claude Code, skills can also be loaded via the --skills flag or placed in ~/.claude/skills/ for global availability.
Step 5: Test the Skill
Give your AI agent a prompt that triggers the skill:
Create a new endpoint for "Order" with getAll, getById, create, and update operations.
Watch how the agent follows your conventions. Check for:
- Correct file structure and naming
- Proper error handling patterns
- Consistent response format
- Route registration in the index file
- Validation schemas included
Step 6: Iterate and Refine
Skills improve through iteration. Common refinements:
| Problem | Solution |
|---|---|
| AI forgets conventions | Add explicit checklists at the bottom of SKILL.md |
| Generated code lacks tests | Include a "Required Tests" section with assertions |
| Skill triggers too often | Narrow the "When to Use" section |
| Missing edge cases | Add a "Common Pitfalls" section with examples |
Advanced: Multi-File Skills
Complex skills can reference additional files:
# Advanced API Generator
## Templates
- Controller: `templates/controller.template.ts`
- Service: `templates/service.template.ts`
- Route: `templates/route.template.ts`
- Test: `templates/test.template.ts`
## Before Generating
1. Read `docs/architecture/api.md` for design patterns
2. Check `src/utils/errors.ts` for existing error types
3. Verify Prisma schema in `prisma/schema.prisma`
This keeps your SKILL.md concise while providing rich context through referenced files.
Best Practices
- Keep skills focused: One skill, one responsibility. Do not combine unrelated workflows.
- Use concrete examples: Show exactly what good output looks like — code speaks louder than descriptions.
- Update with your codebase: When conventions change, update the skill. Stale skills cause more harm than no skills.
- Version control them: Skills are part of your project. Commit them alongside code changes.
- Share across projects: Common patterns (testing, linting, deployment) work as reusable skill libraries.
Conclusion
Custom skills turn generic AI coding agents into team members who know your codebase. With the explosion of official skill repositories in 2026 — from Anthropic, Cursor, and the open-source community — there has never been a better time to invest in structured AI agent configuration.
Start with one skill for your most repetitive coding task. Measure the time saved. Then build the next one. Before long, your AI assistant will feel less like a tool and more like a collaborator who actually understands how you work.