Claude Code Extensibility

The Big Picture

Claude Code has 5 ways to extend and customize it. Think of them as layers:

1 CLAUDE.md — Custom Instructions

What: Markdown files that give Claude persistent context about your project. Loaded automatically every session.

Where to put them

Quick start

# In Claude Code, just type:
/init

This auto-generates a CLAUDE.md based on your project.

Example CLAUDE.md

# My Project

## Tech Stack
- TypeScript, React 18, PostgreSQL

## Commands
- `npm test` — Run tests
- `npm run lint` — Lint code

## Rules
- Use 2-space indentation
- Prefer const over let
- Always write tests for new functions

Path-specific rules

In .claude/rules/api.md, add YAML frontmatter to scope rules to specific files:

---
paths:
  - "src/api/**/*.ts"
---

All API endpoints must include input validation.

2 Skills — Custom Slash Commands

What: Markdown files that become reusable commands. You type /skill-name and Claude follows the instructions in the file.

Where they live

Minimal example

Create .claude/skills/review/SKILL.md:

---
name: review
description: Review code for bugs and style issues
user-invocable: true
---

Review the code for:
1. Bugs and logic errors
2. Security vulnerabilities
3. Performance issues
Suggest fixes for each issue found.

Now type /review in Claude Code and it runs.

Key frontmatter options

Passing arguments

---
name: fix-issue
argument-hint: "[issue-number]"
---

Fix GitHub issue #$ARGUMENTS.
# User types: /fix-issue 123
# Claude sees: Fix GitHub issue #123

Dynamic content with shell commands

---
name: pr-review
---

Review this PR:
- Diff: !`gh pr diff`
- Files changed: !`gh pr diff --name-only`

# The !`command` syntax runs the command and injects the output

3 MCP Servers — External Integrations

What: MCP (Model Context Protocol) servers let Claude use external tools — like querying a database, managing GitHub PRs, or searching Notion. Think of them as plugins that give Claude new abilities.

How to add one

Remote server (most common — cloud-hosted):

# Add GitHub integration
claude mcp add --transport http github https://api.githubcopilot.com/mcp/

# Then authenticate in Claude Code:
/mcp

Local server (runs on your machine):

# Add a PostgreSQL server
claude mcp add --transport stdio mydb -- npx -y @bytebase/dbhub \
  --dsn "postgresql://user:pass@localhost:5432/mydb"

Scopes

Project config file (.mcp.json)

{
  "mcpServers": {
    "github": {
      "type": "http",
      "url": "https://api.githubcopilot.com/mcp/"
    },
    "database": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@bytebase/dbhub"],
      "env": { "DB_URL": "${DB_URL}" }
    }
  }
}

Managing servers

claude mcp list           # List all
claude mcp get github     # Details
claude mcp remove github  # Remove
/mcp                      # Status & auth (inside Claude Code)

4 Hooks — Automated Triggers

What: Shell commands or prompts that run automatically when specific events happen. Like git hooks, but for Claude Code.

Events you can hook into

Where to configure

In any settings file: ~/.claude/settings.json (personal) or .claude/settings.json (project).

Example: Auto-format after edits

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "jq -r '.tool_input.file_path' | xargs npx prettier --write"
          }
        ]
      }
    ]
  }
}

Example: Block editing protected files

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "jq -r '.tool_input.file_path' | grep -q '.env' && exit 2 || exit 0"
          }
        ]
      }
    ]
  }
}
# exit 0 = allow, exit 2 = block

Example: macOS notification on permission request

{
  "hooks": {
    "Notification": [
      {
        "matcher": "permission_prompt",
        "hooks": [
          {
            "type": "command",
            "command": "osascript -e 'display notification \"Claude needs your attention\"'"
          }
        ]
      }
    ]
  }
}

5 Plugins — Bundled Extension Packs

What: A plugin bundles skills, hooks, MCP servers, and agents into one shareable package. It's how you distribute a full extension to a team or community.

Plugin structure

Minimal plugin.json

{
  "name": "my-plugin",
  "description": "What this plugin does",
  "version": "1.0.0"
}

Test locally

claude --plugin-dir ./my-plugin
# Then use: /my-plugin:skill-name

Managing plugins

/plugin                  # Browse & search
/plugin install          # Install from marketplace
/plugin enable name      # Enable
/plugin disable name     # Disable
/plugin uninstall name   # Remove

Settings & Permissions

Control what Claude can and can't do via .claude/settings.json:

{
  "permissions": {
    "allow": [
      "Bash(npm run *)",
      "Bash(git *)",
      "Read(./src/**)"
    ],
    "deny": [
      "Bash(rm *)",
      "Read(.env*)"
    ]
  }
}

Settings file locations (highest priority first)

Interactive setup: type /config in Claude Code.

Quick Reference Cheat Sheet

How Everything Fits Together