Claude Code Skills and Plugins: The Developer's Complete Guide

Claude Code ships with powerful defaults. But the developers who get the most out of it are the ones who have figured out how to extend it — adding custom reasoning frameworks, automating repetitive workflows, integrating external tools, and encoding organizational standards directly into the system.

This guide covers the complete extension ecosystem: Skills, Plugins, Hooks, and MCP Servers. When to use each, how to build them, and the patterns that production teams have converged on.

Skills vs Plugins vs Hooks vs MCP Servers

The four extension mechanisms serve different purposes and should not be confused:

• Skills are markdown files (SKILL.md) that encode specialized instructions, reasoning frameworks, and procedural knowledge. They extend what Claude Code knows how to do. Skills are loaded into context on demand. They are the highest-leverage extension for most developers.
• Plugins are structured bundles (plugin.json manifest + associated files) that add new commands, agents, and automated behaviors to Claude Code. Plugins extend what Claude Code can do at the system level.
• Hooks are scripts that run at specific points in Claude Code's execution lifecycle (pre-tool, post-tool, on-error, session-start, session-end). Hooks extend Claude Code's behavior around tool execution without changing the tool execution itself.
• MCP Servers (Model Context Protocol) are external servers that expose tools and resources to Claude Code via a standardized protocol. MCP Servers connect Claude Code to external systems: databases, APIs, services, and internal tools.

The decision logic: if you are encoding specialized knowledge or a reasoning framework, use a Skill. If you are adding new commands or automating multi-step behaviors, use a Plugin. If you need to intercept or react to tool execution, use a Hook. If you are integrating an external system, use an MCP Server.

Skill Anatomy

Every skill has the same structure:

my-skill/
  SKILL.md          # required: instructions + frontmatter
  scripts/          # optional: automation scripts
    setup.sh
    run.py
  references/       # optional: reference documents
    style-guide.md
    api-docs.md
  assets/           # optional: templates, examples
    template.md
    example-output.md

The SKILL.md file is the core. It uses YAML frontmatter for metadata and a markdown body for instructions:

---
name: api-design-review
version: 1.0.0
description: Reviews REST API designs for consistency,
  security, and developer experience best practices.
  Trigger with: review this API, check my endpoints,
  API design review.
triggers:
  - api design
  - rest api
  - endpoint review
  - openapi
author: your-name
tags: [api, backend, review]
---

# API Design Review

When asked to review an API design, follow this process:

## Step 1: Baseline Assessment

Check for the fundamentals before examining specifics:
- HTTP method semantics (GET for reads, POST for creates,
  PUT/PATCH for updates, DELETE for deletes)
- Consistent naming convention (kebab-case recommended)
- Versioning strategy (URL path preferred: /v1/resources)
- Authentication mechanism (OAuth2/JWT preferred)

## Step 2: Resource Modeling

Evaluate the resource design:
- Are resources nouns, not verbs? (/users not /getUsers)
- Are relationships expressed through nesting or query
  params? (shallow nesting: max 2 levels deep)
- Are batch operations supported where needed?

## Step 3: Response Design
...

The Progressive Disclosure Pattern

Skills should use progressive disclosure: put the most critical information first, with details available via references if needed. Claude Code's context window is finite. A skill that front-loads 2,000 words before getting to the actual instructions will perform worse than a skill that leads with the key directives and links to detailed references for edge cases.

The pattern:

1. Frontmatter: name, version, description, triggers (metadata consumed by the skill loader)
2. Quick reference: the 3-5 most important things to remember (consumed immediately)
3. Step-by-step instructions: the full procedure (consumed when the skill is active)
4. Edge cases: what to do when normal procedure does not apply (consumed as needed)
5. References: links to external documents for deep dives (consumed rarely)

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