Claude Code Skills and Plugins: The Developer s Complete Guide

Building Your First Skill

We will build a code review skill from scratch. The goal: when a developer asks Claude Code to review their code, it applies a consistent, opinionated review framework rather than ad-hoc judgment.

Step 1: Create the skill directory

mkdir -p ~/.claude/skills/code-review
touch ~/.claude/skills/code-review/SKILL.md

Step 2: Write the frontmatter

Frontmatter is consumed by the skill loader to determine when to suggest the skill. The description field is critical — it contains the natural language trigger phrases that Claude Code uses to match user intent to available skills. Be specific. Use the exact words developers will use.

---
name: code-review
version: 1.0.0
description: Performs structured code reviews covering
  correctness, security, performance, readability, and
  test coverage. Trigger with: review this code, review
  this PR, code review, check this function, look at
  this implementation.
triggers:
  - code review
  - review this
  - PR review
  - check my code
author: your-name
tags: [code-quality, review, security]
---

Step 3: Write the instruction body

Use imperative form throughout. Write instructions as direct commands, not descriptions. “Check for SQL injection vulnerabilities” not “The reviewer should check for SQL injection vulnerabilities.”

# Code Review

## Quick Reference
- Lead with the most critical issues (security > correctness
  > performance > style)
- Be direct. Do not soften every piece of critical feedback
  with praise.
- Suggest specific fixes, not just problems.
- Flag any code you are uncertain about rather than
  guessing.

## Review Process

### Security (check first)
- SQL injection: parameterized queries or ORM only
- XSS: user input must be escaped before rendering
- Auth: verify auth checks on every route/method
- Secrets: no hardcoded API keys, tokens, or passwords
- Input validation: untrusted input validated at boundary

### Correctness
- Error paths handled (not just happy path)
- Edge cases covered (empty arrays, null values, overflow)
- Async/await used correctly (no floating promises)
- Race conditions identified in concurrent code

### Performance
- N+1 queries identified and flagged
- Unnecessary re-renders in React components
- Memory leaks in event listeners or subscriptions
- Database indexes required by new query patterns

### Test Coverage
- Happy path covered
- At least one error path covered
- Edge cases tested where correctness issues were flagged

## Output Format

Organize review as:
1. Summary (2-3 sentences: overall assessment + priority)
2. Critical Issues (block merge — must fix)
3. Important Issues (should fix before merge)
4. Minor Issues (fix in follow-up or ignore with reason)
5. Positive observations (1-3 things done well)

Step 4: Add a setup script (optional)

#!/bin/bash
# scripts/setup.sh
# Validates that required linting tools are available

for tool in eslint tsc; do
  if ! command -v $tool &> /dev/null; then
    echo "Warning: $tool not found. Some checks will be
      limited to static analysis."
  fi
done

echo "code-review skill ready"

---

Plugin Structure

Plugins are more structured than skills and add system-level capabilities. A plugin requires a plugin.json manifest:

{
  "name": "deployment-assistant",
  "version": "1.2.0",
  "description": "Deployment workflows for Kubernetes and Docker",
  "author": "your-name",
  "commands": [
    {
      "name": "deploy",
      "description": "Run deployment workflow for specified
        environment",
      "script": "scripts/deploy.sh",
      "args": [
        {
          "name": "environment",
          "type": "string",
          "required": true,
          "enum": ["staging", "production"]
        }
      ]
    }
  ],
  "agents": [
    {
      "name": "deployment-reviewer",
      "skill": "skills/deployment-review.md",
      "triggers": ["review deployment", "check deploy config"]
    }
  ],
  "hooks": [
    {
      "event": "pre-tool",
      "tool": "bash",
      "script": "hooks/pre-bash-check.sh"
    }
  ]
}

The commands array defines new slash commands available in Claude Code. The agents array registers specialized sub-agents the plugin exposes. The hooks array registers lifecycle scripts.

---

The Skill Generator Pattern

One of the most powerful patterns in the Claude Code skills ecosystem: using a Claude Code subagent to generate new skills. The Skill Generator skill instructs Claude Code to introspect on a requested capability, identify the key knowledge and procedures involved, and output a complete SKILL.md file ready for installation.

---
name: skill-generator
version: 1.0.0
description: Generates new Claude Code skills from a
  description of the desired capability. Trigger with:
  create a skill, generate a skill, build a skill for,
  write a SKILL.md.
---

# Skill Generator

When asked to create a new skill:

1. Ask for the desired capability if not fully specified
2. Identify the key knowledge domains the skill requires
3. Identify the most common trigger phrases users will
   employ
4. Draft the SKILL.md using the standard template
5. Review the draft: is the Quick Reference section
   actionable in isolation? Are instructions in imperative
   form? Is the output format specified?
6. Output the complete SKILL.md ready to save
7. Provide the installation command:
   mkdir -p ~/.claude/skills/[skill-name] &&
   cat > ~/.claude/skills/[skill-name]/SKILL.md

---

MCP Server Integration

MCP Servers expose external tools to Claude Code. A minimal MCP Server in TypeScript:

import { Server } from "@modelcontextprotocol/sdk/server/index.js";
import { StdioServerTransport } from
  "@modelcontextprotocol/sdk/server/stdio.js";

const server = new Server(
  { name: "my-internal-tools", version: "1.0.0" },
  { capabilities: { tools: {} } }
);

server.setRequestHandler(ListToolsRequestSchema, async () => ({
  tools: [
    {
      name: "query_internal_db",
      description: "Query the internal product database",
      inputSchema: {
        type: "object",
        properties: {
          sql: { type: "string",
            description: "Read-only SQL query" }
        },
        required: ["sql"]
      }
    }
  ]
}));

server.setRequestHandler(CallToolRequestSchema, async (req) => {
  if (req.params.name === "query_internal_db") {
    const result = await db.query(req.params.arguments.sql);
    return { content: [{ type: "text",
      text: JSON.stringify(result) }] };
  }
});

await server.connect(new StdioServerTransport());

Register the MCP Server in your Claude Code config, and the tools it exposes become available to Claude Code like any other tool.

---

Best Practices

• Keep skills under 500 lines. Longer skills dilute focus. If a skill is growing past 500 lines, split it into two focused skills.
• Test across contexts. A skill that works for one type of request may not work for another phrasing of the same request. Test with at least five different phrasings of your trigger intent.
• Version your skills. Use semantic versioning in the frontmatter. Breaking changes to instructions warrant a major version bump. Keep a CHANGELOG in the skill directory.
• Imperative form throughout. Every instruction should be a direct command. “Check X” not “X should be checked.” The imperative form reduces model interpretation variance.
• Specify output format explicitly. If your skill requires a specific output structure, define it explicitly in the instructions. “Output as a numbered list” or “Respond with a JSON object matching this schema.”

---

Real Examples in Production

Teams using Claude Code at scale have converged on several high-value skill and plugin patterns:

• Formatting hook: A pre-commit hook that uses Claude to check staged files against the team style guide before allowing commit. Catches style issues before code review, not during it.
• Architecture review agent: A plugin agent that reviews new pull requests specifically for architectural concerns — not code-level details, but system-design-level decisions that individual code reviewers often miss.
• Deployment skill: Encodes the team’s deployment checklist as a skill so that every deployment review Claude performs checks the same list of pre-flight items.
• Incident response skill: When a production incident is declared, this skill activates and guides Claude through a structured incident analysis process — timeline reconstruction, impact scoping, root cause investigation, and postmortem draft.

---

People Also Ask

What is the difference between a Claude Code skill and a Claude Code plugin?

A skill is a SKILL.md file that encodes knowledge and instructions — it extends what Claude Code knows how to do. A plugin is a structured bundle with a plugin.json manifest that adds new commands, agents, and hooks — it extends what Claude Code can do at the system level. Most developers should start with skills; plugins are for more complex, multi-component capability extensions.

Where do Claude Code skills get stored?

Skills are stored in the ~/.claude/skills/ directory by default (per-user), or in a .claude/skills/ directory within a project for project-scoped skills. Project-scoped skills take precedence over user-scoped skills when both define the same trigger.

Can I share Claude Code skills with my team?

Yes. Skills stored in your project’s .claude/skills/ directory are committed with the project and shared with everyone who clones the repository. This is the recommended pattern for team-shared skills. User-scoped skills in ~/.claude/skills/ are personal and not automatically shared.

---

Ready to put well-engineered AI tools to work immediately? Browse our catalog of production-ready AI tools, prompt packs, and developer resources at wowhow.cloud/browse — built for developers who ship.

Browse Developer AI Tools