Contents

08 / 10Operator20 min lesson + project lab

Extend With MCP, Skills, and Hooks

Choose the right extension mechanism for external tools, reusable knowledge, and deterministic automation without turning every capability into permanent context or authority.

By the end

A reviewed extension design that gives Claude Code one useful new capability with explicit loading, credentials, permissions, tests, and removal steps.

Extend a proven workflow

Extensions should remove a recurring bottleneck in a workflow you already understand. Connecting every available service creates more tools, authentication paths, context, and failure modes without proving value. Start with one repeated job: retrieve an issue, follow a deployment checklist, format changed files, or query a read-only monitoring source.

Write the desired input, output, authority, and proof before choosing the mechanism. If Claude needs access to an external system, consider MCP or an existing CLI. If it needs occasional domain instructions or a repeatable procedure, use a skill. If an action must occur at a lifecycle event without relying on the model to remember, use a hook.

MCP connects tools and data

Model Context Protocol servers expose tools, resources, or prompts through a standardized connection. Claude Code supports remote HTTP servers and local standard-I/O servers, with current configuration scopes for local, project, and user use. Project-scoped `.mcp.json` can be shared, but Claude Code asks for workspace trust and server approval before using it.

Treat every MCP server as code with access to credentials and systems. Prefer official or reviewed servers, inspect the command or remote endpoint, understand the transport, restrict account scopes, and verify the connected tool list. Do not embed secret values in source-controlled MCP configuration. Use environment references, OAuth, a keychain, or another approved credential path documented by the provider.

Skills load reusable knowledge on demand

A skill is a directory containing `SKILL.md` with frontmatter and instructions. Project skills live under `.claude/skills/`, personal skills under `~/.claude/skills/`, and plugins can distribute namespaced skills. Claude can load a skill when its description matches the task or a user can invoke it directly by name.

Use skills for reference material and repeatable workflows that do not belong in every session. Keep the description specific enough to trigger only when relevant. For workflows with consequential side effects, Anthropic documents controls such as disabling model invocation so the user must call the skill intentionally. A skill still operates through the session's tools and permissions; its text is not a security boundary.

Hooks make events deterministic

Hooks run configured logic at defined Claude Code lifecycle events. They are appropriate when an action or check must happen consistently, such as formatting after an edit, blocking a prohibited command, validating before completion, or notifying an operator when attention is needed. Unlike a reminder in CLAUDE.md, a hook is executed by the runtime when its event matches.

Deterministic does not mean harmless. A hook can run shell commands, call HTTP endpoints, invoke MCP tools, or evaluate with a prompt or agent depending on its type. Keep hook commands small, versioned, time-bounded, and observable. Test exit codes and JSON responses, avoid secret leakage in standard output, and provide a way to disable or roll back a broken hook.

Compose and debug the extension stack

The mechanisms can work together: an MCP server supplies a bounded tool, a skill describes the team's procedure for using it, and a hook verifies a required condition. Keep each responsibility visible. Do not hide business policy inside an opaque tool or duplicate the same workflow across CLAUDE.md, a skill, and a hook.

After installation, prove what loaded. Use `/mcp` and `claude mcp list` for server status, `/context` for loaded instructions and skills, `/hooks` for hook configuration, and the configuration debugging guide when scopes disagree. Record the extension source, version or revision, permissions, credentials, and removal command so the system remains operable after the person who installed it forgets the details.

CLAUDE.md: facts and rules every relevant session should know.
Skill: reusable knowledge or a workflow loaded on demand.
MCP: a standardized connection to external tools or context.
Hook: event-driven enforcement or automation that must execute consistently.
Subagent: isolated reasoning and tool work in a separate context, covered next.

Working reference

Commands and patterns

Add and inspect a remote HTTP MCP server

claude mcp add --transport http <name> <official-mcp-url>
claude mcp list
claude mcp get <name>

Use the exact official endpoint and authentication instructions for the chosen service. HTTP is Anthropic's recommended remote transport where supported.

Create a project skill

mkdir -p .claude/skills/verify-release
$EDITOR .claude/skills/verify-release/SKILL.md

A project skill is source-controlled and available in this repository. Its SKILL.md needs valid frontmatter, clear triggering language, instructions, and an explicit proof contract.

Inspect runtime extension state

/mcp
/hooks
/context

Confirm connectivity, hook loading, and context rather than assuming file presence means the current session is using the extension.

When the happy path breaks

Failure modes

Symptom

An MCP server exposes surprising tools or can reach more data than the task needs.

Likely cause

The server, credential scope, and tool inventory were accepted without review because the protocol connection succeeded.

Recovery

Disconnect it, inspect the official implementation and effective tools, restrict credentials and permissions, then reconnect only if the bounded value remains clear.

Symptom

A committed MCP configuration leaks a token or private endpoint credential.

Likely cause

Secret values were placed directly in `.mcp.json`, a command example, or skill text.

Recovery

Rotate the credential, remove it from reachable history, and use approved environment expansion, OAuth, keychain storage, or a secret manager.

Symptom

A workflow sometimes follows an important rule and sometimes forgets it.

Likely cause

A deterministic requirement was written as advisory skill or CLAUDE.md prose rather than enforced at the appropriate lifecycle event.

Recovery

Move the smallest mechanical check into a tested hook while keeping the human-readable policy and exception path documented.

Symptom

A hook blocks normal work, loops repeatedly, or floods context with output.

Likely cause

The event matcher, exit behavior, runtime, or output contract was not tested against success, failure, and re-entry cases.

Recovery

Disable the hook, reproduce it with captured input, narrow the matcher, bound execution and output, and re-enable only after a rollback test.

Hands-on lab

Build one safe extension bundle

Choose a repeated project workflow and add only the extension mechanisms needed to make its context, tool access, or verification repeatable.

01Write the workflow's trigger, input, output, frequency, authority, current friction, and proof.
02Use the extension decision table to choose CLAUDE.md, rule, skill, MCP, hook, or no extension for each need.
03Create one project skill that documents and executes the non-consequential portion of the workflow.
04If an external tool is essential, choose an official or reviewed MCP server and connect it with the least-privilege credential and scope.
05If a mechanical check must always run, add one narrow hook with bounded output and a disable path.
06Start a fresh session and prove the skill, server, and hook are loaded only where intended.
07Run normal, denied, authentication-failure, hook-failure, and removal tests; record every result.

Deliverable: A source-controlled extension bundle and runbook describing purpose, scope, source, configuration, credentials by name, permissions, tests, failure handling, and uninstall steps.

Reusable artifact

Extension decision record

A reusable review sheet for deciding whether and how a Claude Code extension should enter a project.

Workflow: [repeated job and owner]
Observed friction: [what is slow, inconsistent, or unavailable]
Required capability: [knowledge / procedure / external tool / deterministic event / isolated worker]
Chosen mechanism: [CLAUDE.md / rule / skill / MCP / hook / subagent / none]
Why this mechanism: [loading and authority fit]
Source and revision: [official URL, repository, package, version]
Scope: [managed / user / project / local / nested directory]
Tools and data exposed: [inventory]
Credential: [name, owner, minimum scope; never value]
Permission and sandbox rules: [effective boundaries]
Success test: [input -> observable output]
Failure tests: [denied, offline, bad auth, malformed output]
Observability: [status, logs, diagnostic commands]
Disable and remove: [steps]
Reviewer and review date: [owner]

Before you move on

Receipt checklist

Each extension mechanism has one clear responsibility and documented loading scope.
The MCP server or external tool source, tool inventory, and credential scope are reviewed where applicable.
The skill triggers on its intended task and remains absent from unrelated context.
The hook's success, failure, timeout, output, disable, and rollback behavior are tested where applicable.
A clean session can diagnose, use, and remove the extension from the written runbook.

Primary sources

Continue with the source

Extend Claude CodeAnthropic Claude Code DocsDecision guide comparing CLAUDE.md, rules, skills, hooks, MCP, plugins, and subagents.Connect Claude Code to tools via MCPAnthropic Claude Code DocsCurrent transports, scopes, commands, OAuth, project trust, environment expansion, tool search, and security guidance.Extend Claude with skillsAnthropic Claude Code DocsSKILL.md format, locations, discovery, invocation controls, arguments, supporting files, and distribution behavior.Automate actions with hooksAnthropic Claude Code DocsPractical hook creation, lifecycle events, command behavior, testing, debugging, and safety patterns.Hooks referenceAnthropic Claude Code DocsComplete event, matcher, input/output, exit-code, async, HTTP, prompt, agent, and MCP hook contracts.