Claude Code Skills: Build, Share
& Deploy Reusable AI Skills

Claude Code skills are the mechanism that takes individual developer productivity and multiplies it across an entire engineering organisation. A skill is a packaged, reusable workflow — stored as a Markdown file in your repository, invokable with a slash command, and executed by Claude Code as a structured agentic task. Write a skill once. Let every developer on your team use it indefinitely.

The concept sounds simple, but the operational impact is significant. Consider what happens when your best developer encodes their code review process into a skill. Or your security team encodes a vulnerability scan workflow. Or your DevOps team encodes the deployment checklist. Every developer, regardless of their seniority, now has access to those expert workflows on demand — without asking for help, without missing steps, and without variation in quality.

This is what our Claude Code enterprise deployments focus on in phase two: after the initial setup is solid, we build a skills library that encodes your organisation's institutional knowledge into reusable workflows any developer can run.

What Claude Code Skills Actually Are

At their core, Claude Code skills are Markdown files that contain structured instructions for a multi-step task. When a developer invokes a skill with a slash command, Claude Code reads the skill file, injects it into its context, and executes the workflow it describes — using all of its available tools: file system access, code execution, search, web fetch, and any connected MCP servers.

This is different from a saved prompt or a macro. A Claude Code skill is genuinely agentic: it can read files, write code, run tests, check for issues, and report back — all as part of a single invocation. The skill file defines the agent's objective, its methodology, its quality criteria, and what it should output. Claude handles the execution.

The file format is plain Markdown. No special syntax, no domain-specific language. The skill description and instructions are written in natural language, which means they're readable and maintainable by anyone on the team — not just whoever originally wrote them. Claude Code reads the skill file and interprets it with the same comprehension it brings to any complex technical document.

Where Skills Live

Skills can live in three locations, each serving a different scope. Project skills live in .claude/skills/ within your repository and are version-controlled alongside your code. These are team skills — every developer working in that repository has access to them. Personal skills live in ~/.claude/skills/ on the developer's machine and are available across every project they work in. Plugin skills are packaged with Claude Code plugins and are installed when a developer installs a plugin — this is how third-party skills and organisation-wide skill libraries are distributed.

For enterprise Claude Code deployments, we typically set up all three layers. The global plugin delivers organisation-wide standards and security skills. Each repository has project-level skills for that codebase's specific workflows. And developers have personal skills for their individual preferences — things like preferred output formats, personal code review styles, or language-specific helpers they've built up over time.

Anatomy of a Claude Code Skill

A skill file has a consistent structure that Claude Code is designed to parse and execute. Here's what a production-grade skill looks like:

# PR Code Review Skill

## Description
Perform a thorough code review of the current PR diff. Checks for security issues,
performance problems, test coverage, and adherence to our coding standards.

## Trigger
Invoke with `/pr-review` — Claude will automatically detect the current branch diff.

## Workflow

### Step 1: Get the Diff
Run `git diff main..HEAD` to get all changes in this PR. If the diff is empty,
check `git diff HEAD~1` to review the most recent commit.

### Step 2: Security Scan
Review all changed files for:
- SQL injection risks (raw string interpolation in queries)
- XSS vulnerabilities (unsanitised user input rendered to DOM)
- Hardcoded secrets or credentials
- Insecure direct object references
- Missing input validation

### Step 3: Performance Review
Check for:
- N+1 query patterns (loops that make database calls)
- Missing database indexes on new JOIN conditions
- Synchronous operations that should be async
- Unnecessary re-renders in React components (missing useMemo/useCallback)

### Step 4: Test Coverage
- Check if new functions have corresponding tests
- Verify edge cases are tested (null inputs, empty arrays, error states)
- Flag any changes to critical business logic without updated tests

### Step 5: Code Standards
Apply rules from CLAUDE.md:
- Check for forbidden patterns
- Verify naming conventions
- Check for proper error handling

## Output Format
Produce a structured review report with:
- **CRITICAL**: Issues that must be fixed before merge
- **WARNING**: Issues that should be fixed but aren't blockers
- **SUGGESTION**: Improvements worth considering
- **APPROVED**: If no critical or warning issues found, state this clearly

End with a one-paragraph summary suitable for a PR comment.

Notice the structure: a clear description, a trigger, and a numbered workflow with named steps. Each step tells Claude what to do and what criteria to apply. The output format section ensures consistency — every time this skill runs, the output follows the same structure, making it parseable by humans and machines alike.

The Description Section

The description section serves a dual purpose. It tells Claude what the skill does — its purpose and scope. But it also serves as the matching criteria for Claude Code's skill recommendation system: when a developer asks Claude to do something, Claude checks whether any available skills are relevant and suggests them. A well-written description dramatically improves the accuracy of these suggestions.

Write descriptions that capture the triggering intent, not just the action. "Performs a code review" is less useful than "Analyzes PR diff for security vulnerabilities, test coverage gaps, and code standard violations, producing a structured report suitable for PR comments." The second version will match correctly when a developer types "can you review this PR" or "check my code for security issues."

Building Your First Skills: What to Encode

The most common question teams ask when building a skills library is: what should we encode first? The answer is almost always the same: start with the workflows that are currently bottlenecked on a small number of people. The senior developer whose code review queue is always full. The security engineer who gets asked to check things manually. The DevOps lead who writes the deployment notes. Skills are most valuable where expertise is scarce and demand is high.

High-Value Skills for Engineering Teams

The key principle is that each skill should encode expert judgment, not just a checklist. The security scan skill shouldn't just grep for known-bad patterns — it should understand why they're bad and how to evaluate context. A SQL injection risk in a raw query is different from the same pattern in a test fixture. Encoding that judgment is what makes skills genuinely valuable rather than just automated linting.

Namespacing and Organising Skills

As your skills library grows, organisation becomes important. Claude Code supports namespaced skill invocation using the format /namespace:skill-name. This prevents naming collisions between project skills, personal skills, and plugin skills that might cover similar territory.

# Project skills (no namespace needed for local invocation)
/pr-review
/add-feature

# Plugin skills (always use namespace to avoid conflicts)
/security:vulnerability-scan
/security:dependency-audit
/devops:deploy-checklist
/devops:rollback-procedure

# When you have multiple skills in a domain, group them:
.claude/skills/
├── testing/
│   ├── SKILL.md (invoked as /testing)
│   ├── unit-tests/SKILL.md (/testing:unit-tests)
│   └── e2e-tests/SKILL.md (/testing:e2e-tests)
├── review/
│   ├── SKILL.md (/review)
│   ├── security/SKILL.md (/review:security)
│   └── performance/SKILL.md (/review:performance)
└── deploy/
    ├── SKILL.md (/deploy)
    ├── staging/SKILL.md (/deploy:staging)
    └── production/SKILL.md (/deploy:production)

For enterprise skill distribution, we recommend shipping skills as part of a private Claude Code plugin. This means the skills are version-controlled separately from individual repositories, can be updated centrally, and are consistently available across every project in your organisation. When your security team updates the vulnerability scan criteria, every developer gets the update automatically on next plugin sync — not after a PR is merged to every repository.

Writing Multi-Step Agentic Skills

The full power of Claude Code skills comes from multi-step workflows where each step informs the next. This is where skills genuinely exceed what a saved prompt can do: Claude can execute code, read its output, adjust its plan, write files, run tests, interpret results, and iterate — all within a single skill invocation.

# Add API Endpoint Skill

## Description
Creates a complete, production-ready API endpoint following all project conventions.
Invoke with: /add-endpoint [METHOD] [path] [brief description]

## Prerequisites
Read CLAUDE.md before starting. Confirm you understand:
- The project's auth middleware pattern
- The Zod validation approach
- The service layer convention
- The testing requirements

## Workflow

### Phase 1: Planning (do not write code yet)
1. Identify which service this endpoint belongs to
2. Check if a similar endpoint already exists
3. Identify the relevant domain types in `src/types/`
4. Draft the Zod schema for the request body

### Phase 2: Implementation
Execute in this exact order:
1. Create the Zod request schema in the route file
2. Create the route handler using the project template
3. Add the auth middleware
4. Implement the service call (create service function if it doesn't exist)
5. Add error handling using the project's error types

### Phase 3: Tests
1. Create an integration test file in `tests/api/`
2. Test: happy path (201/200 as appropriate)
3. Test: missing required fields (400)
4. Test: invalid field formats (400)
5. Test: unauthenticated request (401)
6. Test: resource not found (404)
7. Run `npm run test:integration` and fix any failures

### Phase 4: Documentation
1. Add endpoint to `docs/api-reference.md`
2. If this is a public-facing endpoint, add a changelog entry

## Completion Criteria
Report is complete only when:
- All tests pass
- TypeScript has no errors (`npm run type-check`)
- Lint passes (`npm run lint`)
- Documentation is updated

The phased approach is intentional. Planning before writing code produces higher-quality output. The explicit completion criteria prevent Claude from declaring success prematurely. And the prerequisite step — reading CLAUDE.md — ensures the skill benefits from the full context of your project configuration.

Sharing Skills Across Your Organisation

The most common skill-sharing approach for enterprises is the private Claude Code plugin model. A plugin is a distributed package that can include skills, MCP server connections, CLAUDE.md snippets, and hooks. When developers install your organisation's private plugin, they get the full suite of shared skills — and those skills update automatically as your team improves them.

For teams not ready to build a full plugin, there's a simpler approach: a shared skills repository. Store your skills library in a separate Git repository, and add it as a submodule or use a scripts-based sync to pull it into the .claude/skills/ directory of each project. This provides version control and sharing without the overhead of plugin infrastructure.

Version your skills library the same way you version any critical dependency. Tag releases. Maintain a changelog. When you make a significant change to a skill — especially one that changes its output format or invocation syntax — communicate that to your team with the same care you'd use for a breaking API change.

Our Claude Code training workshops include a skills-building session where teams identify their highest-value workflows and begin encoding them in real time. It's one of the most immediately productive sessions we run — teams often leave with 5-10 working skills ready to deploy.

Measuring the Impact of Your Skills Library

The most direct measurement is time-to-complete for the workflows your skills encode. If the PR review skill reduces review turnaround from 24 hours to 30 minutes, that's a concrete, measurable outcome. Pair this with developer satisfaction surveys — anecdotally, developers report that a well-designed skills library makes Claude Code feel genuinely useful rather than occasionally helpful.

Quality metrics matter too. Track defect rates for code that went through the automated review skill versus code that didn't. Track how many security findings the security scan skill catches before code reaches production. These numbers make the business case for continued investment in the skills library — and they're the kind of numbers that get CFOs and CTOs interested in expanding the Claude Code rollout.

If you're evaluating Claude Code for enterprise deployment and want to understand what a production skills library looks like at scale, book a free strategy call. We can walk you through examples from actual deployments and help you identify which workflows in your organisation would benefit most from being encoded as skills.