Building Claude Code Skills

Skills are reusable instructions that tell Claude Code how to perform specific tasks. Instead of explaining your deployment process every session, you write it once as a skill and invoke it with a slash command. Think of skills as roles you assign to Claude Code — reviewer, deployer, incident responder.

What a skill looks like

A skill is a Markdown file stored in your project's .claude/skills/ directory (or globally in ~/.claude/skills/). It contains a natural language description of what Claude Code should do, how it should behave, and what tools it should use. 

# Deploy to Production

When the user runs /deploy:

1. Run the test suite. Stop if any tests fail.
2. Build the project with `npm run build`.
3. Deploy to Firebase with `firebase deploy --only hosting`.
4. Verify the deployment by checking the live URL.
5. Report the deployment status and any warnings.

The user then types /deploy in their Claude Code session, and it executes the full workflow.

Why skills matter for businesses

  • Consistency — Every team member gets the same deployment process, the same code review checklist, the same incident response protocol.
  • Onboarding — New developers don't need to memorise tribal knowledge. The skills encode it.
  • Delegation — You can hand off complex workflows to Claude Code without writing them out each time.
  • Iteration — Skills are version-controlled with your code. They improve over time.

Types of skills

Project skills

Stored in .claude/skills/ within a project. Available to anyone working on that project. Examples: project-specific deployment, database migration, release notes generation.

Global skills

Stored in ~/.claude/skills/ on a developer's machine. Available across all projects. Examples: code review style, commit message format, personal workflow preferences.

Building effective skills

Be specific about behaviour

Vague skills produce vague results. Instead of "review the code", specify what to look for: security vulnerabilities, performance issues, naming conventions, test coverage gaps.

Include guard rails

Tell Claude Code what not to do. "Never force-push to main." "Don't modify database schemas without confirmation." "Stop and ask if the change affects more than 5 files."

Chain skills together

Complex workflows can invoke other skills. A "release" skill might run the "test" skill, then the "changelog" skill, then the "deploy" skill. This creates reliable, repeatable pipelines.

Test your skills

Run the skill on a known codebase and verify the output. Skills that work in one context may need adjustment for others. Iterate and refine.

Skills as team roles

A powerful pattern is to think of skills as roles rather than tasks. Instead of a "write tests" skill, create a "QA engineer" skill that thinks about edge cases, boundary conditions, and test coverage the way a dedicated QA person would. This produces better results because it gives Claude Code a perspective, not just a checklist.

Managing skills at scale

As your skill library grows, organisation becomes important:

  • Use clear, descriptive filenames: deploy-production.md, not skill-3.md
  • Keep skills focused — one skill, one responsibility
  • Version control all project skills alongside your code
  • Review and update skills quarterly, or when processes change
  • Document which skills exist in your project's README or CLAUDE.md

Next steps

Skills become even more powerful when combined with agent hierarchies (delegating sub-tasks to child agents) and guardrails (controlling what skills are allowed to do). See Best Practices for production patterns.