Creating Custom Skills

Typing the same giant prompt over and over gets old FAST. Skills fix that. They're custom slash commands that plug your own workflows into Claude Code, so you write the prompt once and fire it off with a single command forever after.

What Are Skills?#

A skill is a markdown file full of instructions for Claude. When you call it with a slash command, Claude follows those instructions.

Example. Instead of typing "Review the recent git diff, check for security issues, performance problems, and style violations, then provide feedback as a numbered list" every time, you make a /review-changes skill that does it for you.

This is the whole reason I'm obsessed with turning repeat work into a tool. My website generator took 300+ hours to build, and now it handles what used to be 6 to 8 hours of manual work per site. A skill is a tiny version of that same move (minus the 300 hours, thankfully).

Where Skills Live#

.claude/
└── skills/
    ├── review-changes/
    │   └── SKILL.md
    ├── deploy/
    │   └── SKILL.md
    └── test-feature/
        ├── SKILL.md
        └── template.test.ts    # Supporting file

Project skills live in your project's .claude/skills/ directory. Each skill gets its own folder with a SKILL.md file inside, and the folder name becomes the command (so review-changes/ gives you /review-changes).

Want a skill in every project on your machine? Put it in ~/.claude/skills/ instead. Those are your personal skills, and they don't get committed with any one repo.

SKILL.md Format#

A skill file has two parts, the frontmatter on top and the instructions underneath.

---
name: review-changes
description: Review recent code changes for issues. Use when asked to review a diff or check work before committing.
---
 
Review the git diff of recent changes (`git diff HEAD~1`).
 
Check for:
- Security vulnerabilities (injection, XSS, exposed secrets)
- Performance issues (N+1 queries, unnecessary re-renders)
- Missing error handling
- Code style violations per project conventions
 
Provide feedback as a numbered list with file:line references.
If everything looks good, say so explicitly.

Frontmatter Fields#

Every frontmatter field is optional, but write the description anyway. There are more fields for fancier stuff (like argument-hint, allowed-tools and disable-model-invocation), and Claude Code quietly ignores any field name it doesn't recognize, so a typo won't throw an error. It just won't do anything.

Arguments with $ARGUMENTS#

Skills can take arguments from you, too.

---
name: component
description: Create a new React component
---
 
Create a new React component called $ARGUMENTS.
 
Follow these conventions:
- Use TypeScript with proper prop types
- Server Component by default (add 'use client' only if needed)
- Place in src/components/
- Use named export
- Add basic props interface

Usage. /component UserProfile and Claude builds a UserProfile component.

The $ARGUMENTS placeholder gets swapped for whatever you type after the command.

Auto-Invocation vs Manual#

By default a skill works both ways. You can type /skill-name yourself, AND Claude can load it on its own when your request matches the skill's description. That's why a clear description matters so much.

Manual Only#

Some skills you never want firing by surprise (deploys, commits, anything that touches production). Add disable-model-invocation: true and only YOU can kick it off.

---
name: deploy
description: Deploy the app to production
disable-model-invocation: true
---
 
Run `npm run build`, then `npm run deploy`.
Report the deployed URL when it's done.

Claude Only#

Flip it around with user-invocable: false. The skill disappears from the / menu, but Claude can still load it as background knowledge when it's relevant.

Supporting Files#

Skills can point at other files sitting in their folder.

.claude/skills/test-feature/
├── SKILL.md
└── template.test.ts

---
name: test-feature
description: Generate tests for a feature using our template
---
 
Create tests for $ARGUMENTS using the template at
${CLAUDE_SKILL_DIR}/template.test.ts as a pattern.
 
Follow the same structure:
- describe block with feature name
- beforeEach for setup
- individual it blocks for each behavior
- Use vitest assertions

${CLAUDE_SKILL_DIR} gets swapped for the skill's own folder, so the path works whether the skill lives in the project or in ~/.claude/skills/. That way Claude follows your exact testing patterns every single time.

Real-World Skill Examples#

PR Description Generator#

---
name: pr
description: Generate a PR description for current changes
---
 
Analyze the git diff between this branch and main.
Create a PR using gh cli with:
 
## Summary
- Bullet points of what changed and why
 
## Test Plan
- How to verify these changes work
 
Include file change statistics.

Database Migration#

---
name: migrate
description: Create a Prisma migration for schema changes
---
 
1. Check if there are pending changes in prisma/schema.prisma
2. If yes, run: npx prisma migrate dev --name $ARGUMENTS
3. Verify the migration was created successfully
4. Show the generated SQL

Quick Deploy Check#

---
name: deploy-check
description: Verify the project is ready to deploy
---
 
Run these checks in order. Stop at the first failure:
 
1. `npm run lint` - No lint errors
2. `npm run build` - Builds successfully
3. `npm test -- --run` - All tests pass
4. Check for uncommitted changes (git status)
 
Report: READY or NOT READY with details on failures.

Sharing Skills with Your Team#

Since skills live in .claude/skills/, they're part of your git repo... which means sharing is basically free.

• Commit your skills to share them with your team
• Everyone gets the same commands automatically
• Skills grow up alongside your codebase through version control
• New team members get your workflows on day one

TL;DR#

• Skills are custom slash commands that live in .claude/skills/ (project) or ~/.claude/skills/ (personal)
• SKILL.md holds frontmatter (description matters most, name is optional) plus the instructions
• $ARGUMENTS grabs whatever you type after the command
• Supporting files give Claude templates and patterns to copy
• Claude can load skills on its own, so add disable-model-invocation: true to anything risky
• Commit your skills to git to share them with your team