Building Custom Skills for Claude Code - The No-Code Way to Extend AI in 2026

Claude Code has a plugin system that requires no code. Skills are markdown files that live in ~/.claude/skills/ and define reusable workflows, checklists, and behaviors that Claude can invoke during sessions. They are the simplest way to extend Claude Code’s capabilities and the most underused feature in the toolset.

What Skills Are

A skill is a markdown file that describes a workflow or set of instructions. When a skill is relevant to the current task, Claude loads it and follows the instructions. Skills can also be invoked explicitly as slash commands.

The file structure is straightforward:

~/.claude/skills/
  commit.md
  review.md
  deploy.md
  test-coverage.md

Each file is a self-contained instruction set. No imports, no dependencies, no build step. Write markdown, save the file, and the skill is available in the next Claude Code session.

Anatomy of a Skill File

A skill file has an optional frontmatter section and a body:

---
name: commit
description: Create a well-structured git commit
---

# Commit Workflow

When creating a commit, follow these steps:

1. Run `git status` to see all changed files
2. Run `git diff --staged` to review staged changes
3. If nothing is staged, ask which files to stage
4. Write a commit message following this format:
   - First line: type(scope): description (max 72 chars)
   - Types: feat, fix, refactor, docs, test, chore, perf
   - Blank line after first line
   - Body: explain WHY, not WHAT (the diff shows what)
5. Run the commit
6. Run `git status` to confirm success

## Examples

Good: `feat(auth): add JWT refresh token rotation`
Bad: `updated auth stuff`

Good: `fix(api): handle null response from payment provider`
Bad: `fix bug`

The name field in frontmatter becomes the slash command. After saving this file, typing /commit in Claude Code invokes this skill.

Real Skill Examples

Code Review Checklist

---
name: review
description: Review code changes against team standards
---

# Code Review

Review the current changes (staged or recent commits) against these criteria:

## Correctness
- [ ] Logic handles edge cases (null, empty, boundary values)
- [ ] Error handling exists and is appropriate
- [ ] No silent failures (empty catch blocks, ignored return values)

## Security
- [ ] No hardcoded secrets or credentials
- [ ] User input is validated and sanitized
- [ ] SQL queries use parameterized statements
- [ ] File paths are validated against traversal attacks

## Performance
- [ ] No N+1 query patterns
- [ ] No unnecessary re-renders in React components
- [ ] Large lists use pagination or virtualization
- [ ] Database queries have appropriate indexes

## Maintainability
- [ ] Functions do one thing
- [ ] No magic numbers - use named constants
- [ ] Types are specific, not `any`
- [ ] Test coverage exists for new logic

Report findings grouped by severity: critical, warning, suggestion.

Invoking /review after making changes runs this entire checklist against the current diff. This replaces a manual code review process with a consistent, repeatable check.

Deployment Workflow

---
name: deploy
description: Run the full deployment pipeline
---

# Deploy

Execute the deployment pipeline in order. Stop and report if any step fails.

1. **Pre-flight checks**
   - Run `git status` - working tree must be clean
   - Run `git log origin/main..HEAD` - confirm commits to deploy
   - Run `npm test` - all tests must pass
   - Run `npm run build` - build must succeed

2. **Version bump**
   - Read current version from package.json
   - Ask what type of bump: patch, minor, or major
   - Update package.json version
   - Create a git tag with the new version

3. **Deploy**
   - Run `git push origin main --tags`
   - Run `npm run deploy` if it exists
   - Confirm deployment succeeded

4. **Post-deploy**
   - Run smoke tests if `npm run test:smoke` exists
   - Report deployment summary: version, commits included, test results

Database Migration Generator

---
name: migrate
description: Generate a database migration from schema changes
---

# Generate Migration

1. Read the current schema from `src/server/db/schema.ts`
2. Run `pnpm db:generate` to check for pending changes
3. If there are changes:
   - Review the generated SQL migration
   - Check for destructive operations (DROP, ALTER column type)
   - If destructive: warn and ask for confirmation
   - Add the migration file to git staging
4. If no changes detected, report that schema is up to date

## Safety Rules
- NEVER auto-apply migrations to production databases
- ALWAYS review generated SQL before confirming
- Flag any migration that drops columns or tables

Test Coverage Report

---
name: coverage
description: Analyze test coverage and suggest improvements
---

# Test Coverage Analysis

1. Run `npm test -- --coverage` and capture the output
2. Parse the coverage report for:
   - Overall line coverage percentage
   - Files with less than 80% coverage
   - Functions with zero coverage
3. For each under-covered file, read the source and identify:
   - Untested code paths
   - Edge cases without tests
   - Error handling without coverage
4. Generate specific test suggestions for the 3 lowest-coverage files
5. Report in this format:

## Coverage Summary
- Overall: X%
- Files below 80%: [list]

## Priority Test Gaps
[For each file, specific test cases to add]

Skills vs Hooks vs CLAUDE.md

These three systems overlap but serve different purposes:

The decision tree:

• Static rule that should always apply - CLAUDE.md
• Automated action on every file change - Hook
• Multi-step workflow invoked on demand - Skill
• Security enforcement - Hook (non-negotiable)
• Code review checklist - Skill
• Project architecture context - CLAUDE.md

How Claude Discovers Skills

Claude Code scans ~/.claude/skills/ at session start and registers each skill. Skills appear in the available slash commands and Claude can also auto-suggest relevant skills based on conversation context.

If a skill file has the description field in frontmatter, Claude uses it to determine relevance. A well-written description improves auto-matching. A vague description like “do stuff” means Claude will rarely suggest it.

Sharing Skills Across Teams

Skills live in the user’s home directory by default, but sharing them is straightforward:

Option 1: Git repository Create a shared skills repo and symlink into ~/.claude/skills/:

git clone [email protected]:team/claude-skills.git ~/claude-skills
ln -s ~/claude-skills/*.md ~/.claude/skills/

Updates to the repo are one git pull away from every team member.

Option 2: Dotfiles Add ~/.claude/skills/ to the team’s dotfiles management (chezmoi, yadm, stow). Skills sync alongside shell configs and editor settings.

Option 3: Project-level skills For project-specific skills, create a .claude/skills/ directory in the repo. Claude Code checks both the user-level and project-level skill directories. Project skills travel with the codebase and are available to every contributor.

my-project/
  .claude/
    settings.json
    skills/
      deploy.md
      migrate.md
  src/
  ...

Writing Effective Skills

Be specific about steps. “Review the code” is vague. “Run git diff, read each changed file, check for X, Y, Z” is actionable. Claude follows explicit steps more reliably than open-ended instructions.

Include examples. Show what good output looks like. A commit message skill that includes example commit messages produces better results than one that only describes the format.

Handle failure cases. “If tests fail, stop and report which tests failed” prevents Claude from continuing past a broken state. Skills without failure handling can produce cascading errors.

Keep skills focused. One skill per workflow. A skill that tries to handle deployment, rollback, and monitoring is three skills that should be separate. Focused skills are easier to invoke, easier to maintain, and produce better results.

Test the skill. Run it a few times and refine based on the output. Skills that read well as documentation may not execute well as instructions. Iterate until the skill produces consistently correct results.

The Compound Effect

Individual skills save minutes. A library of 10-15 well-crafted skills fundamentally changes how development works with Claude Code. Common workflows become single-command operations. Team conventions are encoded and repeatable. New team members get the same skill library and immediately work with the same processes.

Skills are the lowest-effort, highest-leverage extension point in Claude Code. No code to write, no APIs to learn, no plugins to install. Just markdown files that describe how to do things well.