Claude Code Skills: Build Custom Workflows for Your AI Coding Assistant

Claude Code ships with a general-purpose AI assistant. Skills let you specialize it. A skill is a markdown file that teaches Claude Code how to handle a specific type of task: deploying to Kubernetes, writing database migrations, reviewing pull requests, or following your team's coding conventions.

The difference between "write me a React component" and "write me a React component following our design system, using our custom hooks, with proper error boundaries and accessibility attributes" is a skill.

What Skills Actually Are

A skill is a markdown file in .claude/commands/ (project-level) or ~/.claude/commands/ (global). When you type /skill-name in Claude Code, the file's content gets injected into the conversation as instructions.

.claude/
  commands/
    deploy.md          # /deploy
    review-pr.md       # /review-pr
    write-test.md      # /write-test

That's it. No special syntax, no compilation, no SDK. Just markdown that describes how to do something.

Writing Your First Skill

Here's a practical example: a skill that enforces your team's commit message conventions.

Create .claude/commands/commit.md:

# Commit Workflow

## Steps
1. Run `git diff --staged` to see what's being committed
2. Analyze the changes and categorize: feat, fix, refactor, docs, test, chore
3. Write a commit message following our convention:
   - Format: `type(scope): description`
   - Scope is the package or module name
   - Description is imperative mood, lowercase, no period
   - Body explains WHY, not WHAT
4. If changes touch multiple scopes, create separate commits
5. Run `git commit -m "message"` with the generated message

## Rules
- Never use `--no-verify` to skip hooks
- Never amend published commits
- If tests fail in pre-commit, fix the issue first

## Examples
- `feat(billing): add stripe webhook handler`
- `fix(auth): handle expired refresh tokens`
- `refactor(api): extract rate limiter to shared package`

Now /commit gives Claude Code a structured workflow instead of a vague "commit my changes" instruction.

Skill Design Patterns

The Checklist Pattern

Best for tasks with multiple verification steps.

# Pre-Deploy Checklist

Before deploying, verify each item:

- [ ] `pnpm typecheck` passes
- [ ] `pnpm test` passes
- [ ] No console.log statements in production code
- [ ] Environment variables documented in .env.example
- [ ] Database migrations are reversible
- [ ] API changes are backward compatible

If any check fails, stop and report the issue. Do not proceed with deployment.

The Decision Tree Pattern

Best for tasks where the approach depends on context.

# Bug Fix Workflow

1. Reproduce the bug (find or write a failing test)
2. Identify the root cause:
   - If it's a type error → fix the type definition at the source
   - If it's a race condition → add proper locking/sequencing
   - If it's a missing validation → add schema validation at the boundary
   - If it's a logic error → fix and add regression test
3. Verify the fix doesn't break existing tests
4. Write a test that would have caught this bug

The Template Pattern

Best for generating consistent output.

# New API Endpoint

Create a new API endpoint following our conventions:

## File Structure
- Route handler: `apps/api/src/routes/{resource}/{action}.ts`
- Schema: `apps/api/src/schemas/{resource}.ts`
- Test: `apps/api/src/routes/{resource}/__tests__/{action}.test.ts`

## Required Elements
- Zod schema for request validation
- Authentication middleware
- Rate limiting
- Structured error responses using errorResponse()
- Success responses using successResponse()
- OpenAPI documentation comments

Installing Community Skills

The Claude Code ecosystem has a growing library of community skills. Install them with:

npx add-skill username/repo-name -y

Popular skill collections:

• coreyhaines31/marketingskills (29 marketing/SEO skills)
• hedging8563/lemondata-api-skill (LemonData API integration)

Installed skills appear in ~/.claude/commands/ and work across all projects.

Project vs Global Skills

Location	Scope	Use Case
.claude/commands/	This project only	Project conventions, deploy workflows
~/.claude/commands/	All projects	Personal preferences, general tools

Project skills should be committed to your repo so the whole team benefits. Global skills are for personal workflow preferences.

Advanced: Skills with Hooks

Skills can reference hooks (shell commands that run on specific events) for automated enforcement:

# Pre-Commit Check

Before any commit, the following hooks run automatically:
- `pre-commit`: runs typecheck + lint
- `post-commit`: updates changelog

If a hook fails, investigate the error output and fix the issue.
Do not use --no-verify to bypass hooks.

The hooks themselves are configured in .claude/settings.json:

{
  "hooks": {
    "pre-commit": "pnpm typecheck && pnpm lint-staged"
  }
}

Tips for Effective Skills

1. Be specific about file paths and naming conventions. "Create a component" is vague. "Create a component in src/components/ui/ using PascalCase naming" is actionable.

2. Include examples of correct output. Claude Code learns better from examples than from abstract rules.

3. Define what NOT to do. "Never use any type" is more enforceable than "use proper types."

4. Keep skills focused. One skill per workflow. A 200-line skill that covers everything is less useful than five 40-line skills that each handle one task well.

5. Version your skills. As your conventions evolve, update the skills. Outdated skills are worse than no skills because they enforce old patterns.

Real-World Impact

Teams that adopt skills report consistent improvements:

• Code review cycles drop because conventions are enforced before review
• Onboarding time decreases because new developers get the same guidance as veterans
• AI-generated code quality improves because the AI has explicit context about project standards

The investment is small (30 minutes to write your first few skills) and the payoff compounds with every interaction.

---

Build with AI, guided by your own rules. lemondata.cc provides the API infrastructure for AI-powered development tools.