Creating Custom Skills

Why create custom skills

Built-in skills cover common tasks, but every team has workflows unique to their codebase. A deployment process that touches three services. A code review checklist specific to your architecture. A migration pattern you repeat across modules. These become custom skills.

Custom skills encode tribal knowledge. Instead of explaining a complex workflow to each new team member—or to the agent in every session—you write it down once. The skill becomes a living reference that evolves with your practices.

Directory structure

Skills live in a dedicated directory containing at minimum a SKILL.md file. The directory name is the skill name unless you override it in frontmatter.

Basic structure

my-skill/
├── SKILL.md            # Required: main instructions

That is all a skill needs. The SKILL.md file contains YAML frontmatter and markdown instructions. For simple skills—a code review checklist, a commit message formatter—nothing more is required.

Extended structure

Complex skills benefit from additional files:

api-integration/
├── SKILL.md                    # Entry point and navigation
├── templates/
│   ├── controller.ts.template  # Code templates to fill
│   └── test.ts.template
├── examples/
│   ├── crud-example.md         # Reference implementations
│   └── auth-example.md
├── reference/
│   ├── error-codes.md          # Detailed documentation
│   └── conventions.md
└── scripts/
    ├── validate.sh             # Executable utilities
    └── scaffold.py

Supporting files only load when explicitly referenced. A skill directory can contain megabytes of reference material without impacting sessions that never need it.

Where skills live

Skills load from multiple locations:

Personal skills travel with you. Your preferred debugging workflow, your commit message format, your code review approach—keep these in personal scope.

Project skills travel with the repository. Team coding conventions, project-specific deployment processes, architectural patterns—keep these in project scope so every team member benefits.

Codex skill locations

Codex uses similar but not identical paths:

Same pattern: repository-level for shared team workflows, user-level for personal practices.

SKILL.md file format

Every skill has a SKILL.md file with two sections: YAML frontmatter and markdown body.

Frontmatter

Page 3 covered frontmatter fields in detail. The essential fields for skill creation:

---
name: api-integration
description: Creates API endpoints following project conventions including controller, service, repository layers, tests, and OpenAPI documentation. Use when adding new endpoints or when asked about API patterns.
argument-hint: [endpoint-name] [http-method]
---

The description field does the most work. It tells the agent what the skill does, when to use it, and what it is capable of.

Descriptions must be specific. "Helps with APIs" matches everything and therefore matches nothing well. "Creates API endpoints following project conventions" tells the agent exactly when this skill applies.

Body content

The body contains markdown instructions the agent follows when the skill activates:

---
name: api-integration
description: Creates API endpoints following project conventions
argument-hint: [endpoint-name] [http-method]
---

## Objective

Create a new API endpoint for $0 using the $1 HTTP method.

## Steps

1. Create controller in `src/controllers/$0.controller.ts`
2. Create service in `src/services/$0.service.ts`
3. Create repository in `src/repositories/$0.repository.ts`
4. Add route in `src/routes/index.ts`
5. Create tests in `src/tests/$0.test.ts`
6. Update OpenAPI spec in `docs/openapi.yaml`

## Conventions

- Controllers handle HTTP concerns only
- Services contain business logic
- Repositories handle data access
- All endpoints require authentication unless marked public
- Tests cover happy path and error cases

## Templates

See [templates/controller.ts.template](templates/controller.ts.template) for controller structure.
See [templates/test.ts.template](templates/test.ts.template) for test patterns.

Notice the references to supporting files. The agent reads these only when needed, not at skill load time.

Line limits

Keep SKILL.md under 500 lines. Longer files suggest content that should move to supporting files.

This guideline exists for context economics. When a skill activates, its full body loads into context. A 2,000-line skill consumes significant context budget even for simple tasks.

Progressive disclosure pattern

Effective skills structure information in layers. Core instructions live in SKILL.md. Details live in supporting files, loaded only when relevant.

Three-tier loading

This structure lets a repository contain dozens of skills without bloating session startup. Only descriptions load initially—roughly 100 tokens per skill. Full instructions load when a skill activates. Supporting files load when explicitly needed.

Implementing progressive disclosure

Structure SKILL.md as a high-level guide with references to details:

---
name: database-migration
description: Creates and runs database migrations following project schema conventions
argument-hint: [migration-name]
---

## Quick start

Create migration: `npm run migrate:create $0`
Run migrations: `npm run migrate:up`
Rollback: `npm run migrate:down`

## Migration types

**Schema changes**: See [reference/schema-migrations.md](reference/schema-migrations.md)
**Data migrations**: See [reference/data-migrations.md](reference/data-migrations.md)
**Index management**: See [reference/indexes.md](reference/indexes.md)

## Conventions

- One logical change per migration
- Include both `up` and `down` methods
- Test migrations on copy of production data
- Document breaking changes in migration file

## Examples

See [examples/](examples/) for common patterns:
- Adding a column
- Creating a junction table
- Migrating enum values

The agent gets enough from SKILL.md to handle typical cases. Complex scenarios reference supporting files. The agent loads only what each specific task requires.

Reference file guidelines

Supporting files should be self-contained—readable without loading other files. Include a table of contents if over 100 lines. Link back to SKILL.md for navigation.

Keep reference hierarchy flat. SKILL.md links to reference/schema-migrations.md. That file should not link to reference/schema-migrations/advanced.md. Nested references create context loading chains the agent struggles to navigate efficiently.

Monorepo skill organization

Earlier sections covered automatic discovery in monorepos. For skill creation, this means package-specific skills:

my-monorepo/
├── .claude/
│   └── skills/
│       └── repo-conventions/       # Shared across all packages
├── packages/
│   ├── web-app/
│   │   └── .claude/
│   │       └── skills/
│   │           └── react-patterns/ # Only when editing web-app/
│   └── api-server/
│       └── .claude/
│           └── skills/
│               └── api-patterns/   # Only when editing api-server/

Package-level skills activate only when editing files in that package. A React component skill does not pollute context when working on backend code.

This works well for teams with distinct technology stacks across packages. Frontend developers see frontend skills. Backend developers see backend skills. Shared conventions live at the repository root.

Skill naming conventions

Names become commands, so choose them carefully.

Good names describe what the skill does:

• api-integration - domain
• code-review - action
• migration-create - action with qualifier

Avoid generic names like helper, utils, or stuff. Avoid reserved words: anthropic, claude.

Names must be lowercase letters, numbers, and hyphens only. Maximum 64 characters.