The Claude Bible
Home / Extending Claude Code
Level: Advanced · 19 lessons

Extending Claude Code

Skills, MCP, sub-agents, hooks, plugins, agent teams. Where Claude Code becomes a platform.

Open the interactive course237 lessons, quizzes, exercises, a final exam with a diploma, 3 languages, free.

Skills: teaching Claude a workflow

A skill is a markdown file (SKILL.md) that teaches Claude a repeatable workflow, triggered by a slash command. Instead of re-pasting a long prompt every time, you invoke it: /my-skill.

Anatomy: a frontmatter (name, description, triggers) + instructions + sometimes reference files and scripts. The description is crucial: it is what lets Claude pick the right skill at the right time.

Pierre has a collection that reveals the power of the mechanism:

A skill is packaged procedural knowledge: you encode your way of doing something once, Claude replays it perfectly on every call.

Key points
  • Skill = repeatable workflow in a SKILL.md, invoked by a slash command
  • The description drives automatic triggering
  • Packaged procedural knowledge, reusable
  • skill-builder: a skill to build skills

MCP: wiring external tools

MCP (Model Context Protocol) is the open standard that links Claude to external tool and data servers: a database, an API, a CMS, a SaaS. Once an MCP server is wired in, its tools become callable by Claude like native tools.

Concretely, you connect a server via /mcp or the config, and the server's prompts appear in the /mcp__[server]__[prompt] format. It is exactly the same technology as the Connectors on the Cowork side.

Examples from Pierre's setup:

A pitfall to know, lived by Pierre: an MCP can be project-scoped. His Strapi MCP only exposes its tools if Claude Code starts from the right project folder. Starting elsewhere = tools missing. Rule: check the scope when an expected MCP tool does not show up.

Key points
  • MCP = standard to wire external tools/data into Claude
  • MCP tools called like native tools; same tech as Connectors
  • Format /mcp__[server]__[prompt]
  • Pitfall: a project-scoped MCP only appears from the right folder

Sub-agents: delegating in isolated context

A sub-agent is a Claude agent that the main agent launches for a task, with its own isolated context. It does its work, and only returns its conclusion to the main agent, not all its intermediate mess.

Two major benefits:

Common types: an Explore agent (read-only search), a Plan agent (designing a strategy), specialized agents (code review, SEO audit, competitive analysis). You manage them via /agents.

Available since July 2025, sub-agents are the basic building block of everything that follows: workflows and agent teams are just structured ways of orchestrating them.

Update, July 2026: since Claude Code v2.1.198 (July 1, 2026), subagents run in the background by default: the main conversation keeps working and gets notified when they finish. The /agents creation wizard was removed in the same release (ask Claude to create an agent, or edit .claude/agents/ directly). The orchestration module has a dedicated lesson on what this changes.

Key points
  • Sub-agent = task delegated in isolated context, returns only its conclusion
  • Keeps the main context clean + enables parallelism
  • Types: Explore (read), Plan, specialized (review, audit)
  • Basic block of workflows and agent teams

Hooks: automating the lifecycle

Hooks are actions triggered automatically at lifecycle moments of Claude Code: before/after a tool call, when Claude finishes, on each file edit, at session start.

Key point: the harness executes hooks, not the model. So any behavior of the form "every time X, automatically do Y" cannot live in memory or preferences: it must be a hook in settings.json.

Typical uses:

Pierre uses git hooks (post-commit) to automatically refresh his Graphify graphs on every commit, and scheduled tasks for memory consolidation. That is what turns a manual practice into an automatic pipeline.

Key points
  • Hook = automatic action on a lifecycle event
  • Executed by the harness, not the model: 'every time X' = a hook, not a preference
  • Format/lint, tests, secret blocking, CI webhook
  • Pierre: post-commit hooks to refresh Graphify

Plugins and Agent Teams

Plugins: a plugin is a versioned bundle that packages several skills, sub-agents, slash commands, hooks, output styles and MCP server definitions together. It is the canonical way to share reusable Claude Code extensions, via a marketplace.

Pierre activates several plugins in his settings.json: superpowers (advanced workflows), frontend-design, code-review, security-guidance, and a personal marketplace searchfit-seo with his own SEO skills. A plugin = installing a whole coherent toolkit at once.

Agent Teams: available since February 2026, they let several agents coordinate on parallel sub-tasks. It is the level above isolated sub-agents: not only do you delegate, the agents collaborate toward a shared goal. We go deeper on orchestration in module 9.

The progression to remember: skill (one workflow) -> plugin (a shared toolkit) -> agent team (several agents collaborating). Each level composes the previous one.

Key points
  • Plugin = versioned bundle (skills + agents + commands + hooks + MCP), shareable
  • Pierre: superpowers, frontend-design, code-review, security-guidance, personal SEO
  • Agent Teams (Feb 2026) = several agents collaborating on sub-tasks
  • Scale: skill -> plugin -> agent team

Author your own skill

A skill in Claude Code is a reusable instruction set stored as a Markdown file called SKILL.md. When you trigger the skill, Claude reads that file and follows it as a set of rules for the current task. Skills live in ~/.claude/skills/<skill-name>/SKILL.md (global, available in every project) or in .claude/skills/<skill-name>/SKILL.md inside a specific repo (project-scoped).

Every SKILL.md starts with a frontmatter block (a short YAML header between two --- lines). The two required keys are name (a short identifier) and description (one sentence that tells Claude when the skill applies). The description is what Claude Code surfaces in the skill list and uses to decide whether to suggest the skill automatically.

A skill triggers in two ways. First, explicitly: the user types /skill-name as a slash command. Second, automatically: if your description matches what the user is asking for, Claude Code may invoke it without being asked. The body of SKILL.md (everything after the frontmatter) is plain Markdown and can contain step-by-step instructions, constraints, output format rules, or even embedded code templates.

The recommended folder layout for a well-structured skill is:

Key points
  • SKILL.md lives in ~/.claude/skills/<name>/ (global) or .claude/skills/<name>/ (project)
  • Frontmatter requires name and description between --- lines
  • Trigger: explicit slash command /name or automatic match on description
  • Skill body is plain Markdown: steps, rules, constraints, templates

Discovering and installing skills

Claude Code ships with a built-in Skill tool, a mechanism that lets the agent load a specialized prompt, workflow, or mini-agent on demand. A skill is a named bundle stored in ~/.claude/skills/<name>/SKILL.md. When you (or Claude itself) invoke a skill, the Skill tool reads that file and adopts its instructions for the rest of the task.

Skills are discovered through several channels. The simplest is typing a slash command such as /graphify or /code-review in the Claude Code prompt. Claude checks the available-skills list (surfaced in its system reminder) and calls the Skill tool automatically. You can also ask in plain English: "find a skill for X" triggers the find-skills skill, which searches the registry and suggests what to install.

The main distribution point is the community repository affaan-m/ECC on GitHub, which bundles hundreds of pre-built skills. You clone or copy the skills you want into ~/.claude/skills/ and they become immediately available. Individual skill authors also publish SKILL.md files as gists or repo subfolders that you can drop in the same way.

Key things to understand about the skill system:

Key points
  • Skills live in ~/.claude/skills/ as SKILL.md files
  • Invoke with a slash command or a natural-language trigger
  • ECC (affaan-m/ECC) is the main community skill library
  • find-skills discovers and suggests new skills on request

The MCP ecosystem

MCP (Model Context Protocol) is an open standard that lets Claude connect to external tools, data sources, and reusable prompts through a single, uniform interface. Instead of hardcoding every integration, you plug in an MCP server (a small program that speaks the protocol) and Claude gains new capabilities instantly.

MCP defines exactly three primitives (the building blocks every server exposes):

In Claude Code you wire up MCP servers in .claude/settings.json under the mcpServers key. Once registered, every tool the server exposes appears automatically in the agent, and you can see the full list with /mcp in the Claude Code prompt.

Key points
  • MCP is the open protocol for connecting Claude to external capabilities
  • Three primitives: tools (callable), resources (readable), prompts (reusable templates)
  • Servers are registered in .claude/settings.json under mcpServers
  • Run /mcp inside Claude Code to list all active servers and their tools

Connecting an MCP server

MCP (Model Context Protocol) is an open standard that lets Claude Code talk to external tools and data sources through a small server process. Each MCP server exposes a set of tools (actions Claude can call) and resources (data Claude can read). You install one, point Claude Code at it, and those capabilities appear automatically in every conversation.

Claude Code supports two scopes for MCP servers. User scope makes a server available in every project on your machine. Project scope locks the server to one repository, which keeps credentials and tool sets isolated. Project-scoped servers are declared in .claude/settings.json inside the repo; user-scoped ones live in your global ~/.claude/settings.json.

Many MCP servers require authentication before Claude Code can call their tools. The two common patterns are a static token (you paste a secret key once and it is stored in the config) and OAuth (Open Authorization, a browser-based flow where you log in with your real account and the server issues a temporary access token). OAuth is preferred when the service already has your login, because no long-lived secret is stored in a file.

Key points
  • MCP servers add tools and resources to Claude Code without changing the model
  • Project scope keeps credentials and tools isolated to one repo
  • OAuth lets you authenticate with your real account instead of pasting a secret key
  • Use 'claude mcp list' to verify a server is connected and healthy

Build your own MCP server

The Model Context Protocol (MCP) is an open standard that lets Claude Code call external tools you define yourself. Instead of being limited to built-in commands, you can expose any function (a database query, an API call, a file transform) as a tool that Claude discovers and invokes automatically.

MCP servers communicate with Claude Code over one of two transports (the channel through which messages travel). stdio (standard input/output) is the simplest: Claude Code launches your server as a child process and pipes JSON messages back and forth over stdin and stdout. HTTP with Server-Sent Events (SSE) runs your server as a persistent web service, useful when the server must be shared across machines or stay alive between sessions. For local tools, stdio is almost always the right choice.

Every tool you expose has three required parts: a unique name, a human-readable description (Claude reads this to decide when to call the tool), and an input schema (a JSON Schema object that describes what parameters the tool accepts). Claude Code validates every call against the schema before dispatching it, so bad arguments are caught early.

Key points
  • MCP (Model Context Protocol): open standard for custom Claude tools
  • stdio transport: Claude launches your server as a child process
  • Input schema: JSON Schema that validates tool arguments
  • Tool description: the text Claude reads to decide when to call your tool

Sub-agent patterns

A sub-agent is a separate Claude Code process that Claude spins up to handle one specific task in isolation. "Isolation" means it gets its own blank context window (the memory buffer holding the conversation so far), so it cannot see the parent session's history, credentials, or intermediate reasoning. This is intentional: a fresh context stays focused and avoids polluting results with unrelated information.

When should you delegate to a sub-agent? The rule of thumb is: delegate when a task is independent (it does not need knowledge the parent already holds), expensive (it would burn most of the parent's context budget reading many files), or parallelisable (several similar tasks can run at the same time). Examples include running a full security audit on a single module, generating a translation for each supported language, or executing a test suite on a branch.

Claude Code recognises three named agent types you will encounter in skills and documentation:

Because each sub-agent starts cold, the orchestrator must pass all needed context in the prompt itself: file paths, relevant code snippets, constraints, and expected output format. Treat each delegation prompt like a self-contained ticket handed to a contractor who has never seen your project before.

Key points
  • Sub-agents run in isolated context windows, blind to the parent session
  • Delegate when a task is independent, expensive, or parallelisable
  • Orchestrator plans and assembles; workers execute; reviewer validates
  • Every delegation prompt must be self-contained with all needed context

Hook events: the lifecycle

Claude Code exposes a hook system that lets you run your own scripts at precise moments during a session. Each moment is called a hook event. You register a hook in settings.json by mapping an event name to a shell command. Claude Code runs that command automatically when the event fires.

The main hook events are:

Hooks receive structured JSON on stdin describing the event: which tool was called, what arguments were passed, what the result was, and so on. Your script reads that JSON, does its work, and exits. A non-zero exit code on a PreToolUse hook cancels the tool call entirely, giving you a lightweight gatekeeper.

Key points
  • PreToolUse runs before every tool call and can cancel it
  • PostToolUse runs after the result is returned
  • Stop fires once when Claude finishes its final reply
  • SessionStart fires once at the beginning of each session

Writing a hook script

A hook script is a small program that Claude Code runs automatically at a specific moment, such as before a tool executes or after a file is saved. Hooks let you enforce policies, log actions, or feed extra information back to Claude without changing your prompts.

Every hook receives a JSON payload (a structured data object) on standard input (stdin) describing what Claude is about to do. The payload includes a tool_name field you can match against to decide whether your script should act. Common tool names include Bash, Edit, Write, and Read.

Your script controls what happens next through its exit code (a number your script returns to the operating system when it finishes) and its standard output (stdout):

If you print a JSON object to stdout with a continue field set to true and a stopReason string, Claude reads that text and can adjust its next action. This is how you feed context back to the model mid-task, turning a passive guard into an active advisor.

Key points
  • Hook scripts run at defined moments and receive a JSON payload on stdin.
  • Match tool_name to decide whether your hook applies to the current call.
  • Exit 0 allows, exit 2 blocks and surfaces your message to the user.
  • Print JSON with continue:true and stopReason to feed guidance back to Claude.

Plugins: bundling everything

A Claude Code skill is a directory that ships as one installable unit. Inside it you can combine all the extension points you have learned: slash commands, hooks, MCP server declarations, and even sub-agent definitions. When someone installs your skill, all of those pieces activate together, without manual wiring.

The entry point is a SKILL.md file. Claude reads it at invocation time to understand the skill's purpose, its available commands, and any setup instructions. Alongside it, the skill directory typically contains the supporting scripts, config snippets, and MCP manifests that back those commands.

A well-structured skill covers four layers:

Skills live in ~/.claude/skills/<skill-name>/ for user-wide use, or in .claude/skills/<skill-name>/ inside a repo for project-scoped use. Invoking a skill is as simple as typing /skill-name in the Claude Code prompt.

Key points
  • A skill bundles commands, hooks, MCP servers, and agents in one directory
  • SKILL.md is the entry point Claude reads when the skill is invoked
  • User-wide skills go in ~/.claude/skills/, project skills in .claude/skills/
  • Installing a skill activates all its extension points without extra configuration

settings.json in depth

settings.json is the configuration file that controls how Claude Code behaves in a project or globally. It covers four main areas: permissions (what tools Claude may use without asking), environment variables (values injected into every session), hooks (shell commands triggered automatically at certain moments), and file location plus precedence rules.

There are two scopes. The user-level file at ~/.claude/settings.json applies to every project you open. The project-level file at .claude/settings.json inside a repo applies only to that repo. When both exist, project settings override user settings for any key they share, and the rest is inherited.

The permissions block uses an allow list and a deny list. Each entry is a tool identifier such as Bash, Edit, or an MCP tool name. Entries in allow let Claude call that tool without a prompt; entries in deny block it entirely. The env block is a plain key-value object: every key becomes an environment variable available to hooks and to any subprocess Claude spawns.

The hooks block maps lifecycle events to shell commands:

Each hook entry is an object with a matcher (which tool name or "*" for all) and a command string executed in your shell. Hooks run as the current user, so they have full system access: keep them short and audited.

Key points
  • Project settings.json overrides user settings.json for shared keys.
  • The allow/deny lists in permissions control which tools Claude can use without prompting.
  • The env block injects variables into every Claude Code session and subprocess.
  • Hooks (PreToolUse, PostToolUse, Stop) run shell commands at lifecycle events.

Output styles

Claude Code defaults to a conversational, verbose style: it explains its reasoning, lists steps, and confirms actions. That default is helpful when you are learning, but it adds noise when you are in a fast iteration loop or piping output into another tool.

You control output style through two main levers: flags on the command line and instructions inside the prompt itself. Flags are reliable and machine-readable; prompt instructions are flexible and portable.

The most important flags are:

Inside the prompt you can add style directives such as "reply with only the file contents, no commentary" or "return a single shell command, nothing else." Claude Code respects these consistently across claude-opus-4-8, claude-sonnet-4-6, and claude-haiku-4-5.

Key points
  • --output-format json for machine-readable output
  • --verbose to expose tool calls and reasoning
  • Prompt directives override the default chatty style
  • Match output style to the consumer (human vs script)

Background tasks and web tools

Claude Code can launch long-running processes in the background so you do not have to wait for them to finish before giving the next instruction. The flag run_in_background tells the Bash tool to start a command without blocking: Claude fires it off, moves on, and notifies you when it completes. This is useful for builds, test suites, or dev servers that would otherwise freeze the conversation.

Two web tools extend Claude Code beyond your local files. WebSearch queries the web and returns a ranked list of results with titles, URLs, and short excerpts. WebFetch retrieves the full content of a specific URL, strips the HTML, and hands the readable text to Claude. Together they let Claude answer questions that require up-to-date information or external documentation without you having to copy-paste anything.

Knowing when to use each tool matters. Use WebSearch when you need to discover sources (you do not yet know the right URL). Use WebFetch when you already have a URL and want Claude to read the page in full (for example, an API reference or a changelog). Use run_in_background when a shell command would take more than a few seconds and you want to keep working in parallel.

Key points
  • run_in_background lets long shell commands run without blocking the chat
  • WebSearch finds sources when you do not know the URL yet
  • WebFetch reads a full page when you already have the URL
  • Combine them: search first, then fetch the most relevant result

MCP grows up: the 2026-07-28 revision

MCP (Model Context Protocol) is the open standard that lets an AI client, like Claude Code, talk to external tools and data sources through independent servers instead of custom one-off integrations. Since its launch, MCP has gone through incremental updates, but the version with a release candidate locked on May 21, 2026 and a final spec dated 2026-07-28 is the biggest revision the protocol has seen. It changes how connections are established, adds two new capabilities (interactive UI and long-running tasks), tightens security, and introduces formal governance for how future changes get approved.

The headline change is that the protocol core becomes stateless, meaning the server no longer needs to remember anything about a specific client connection between requests. In the old model, a client opened a connection through an initialize handshake (a setup exchange where client and server agree on capabilities before real work starts) and the server tracked that session using an Mcp-Session-Id header attached to every request. Both are removed in this revision. Instead, client metadata (identifying details like client name and version) now travels inside a _meta field on every single request, so each request is self-contained. This matters because stateless requests can be handled by any available server instance, which means a load balancer can spread requests across a pool of MCP servers round-robin (rotating through servers in order) instead of pinning a client to one server for the life of a session. That is the difference between an MCP server that can only run as a single fragile process and one that can scale horizontally like a normal web API.

Two new official extensions unlock capabilities that were previously bolted on ad hoc. MCP Apps lets a server ship an interactive user interface that renders inside a sandboxed iframe (an embedded browser frame isolated from the host page for security), so a tool is no longer limited to returning plain text or JSON; it can hand the user a real interactive panel. The Tasks extension gives the protocol a standard way to represent long-running work, such as a job that takes minutes rather than seconds, so a client can check status or receive updates without holding a connection open and waiting.

Security and interoperability also got real upgrades. OAuth/OIDC (the standard protocols for delegated login and identity verification used across the web) were hardened in this revision, tightening how MCP servers authenticate clients. The spec now also supports W3C trace context, a standard format for passing tracing identifiers between systems so a request can be followed across multiple hops, useful when debugging a chain of tool calls. On top of that, MCP now has a formal deprecation policy with three states, Active, Deprecated, and Removed, and a rule that at least 12 months must pass between marking something Deprecated and actually Removing it, giving teams a predictable runway instead of surprise breakage.

Governance changed too. Standards Track proposals (changes meant to become part of the official spec) now require passing a mandatory conformance test suite before acceptance, under the oversight of the AAIF (Agentic AI Foundation), the governance body now responsible for the protocol's direction. Beta SDKs (software development kits, the libraries developers use to build MCP clients and servers) for this new revision shipped on June 29, 2026 for Python, TypeScript, Go, and C#, so builders could start testing against the new behavior before the spec was finalized a month later.

The ecosystem around MCP by mid-2026 gives a sense of scale and where to place trust. The official registry at registry.modelcontextprotocol.io was in an API freeze at version 0.1 heading toward a 1.0 general availability release, listing about 2,000 servers, a curated but comparatively small number. Third-party registries are much larger: Glama listed roughly 52,581 open-source servers, PulseMCP about 15,930, and Smithery around 7,300. Scale differs sharply from vetting, so a huge count on a third-party registry is not the same guarantee as a smaller, more curated official listing. Cloud providers are also standardizing around MCP: the AWS MCP Server reached general availability on May 6, 2026 with more than 60 official servers, and at Cloud Next 26, Google opened its Google-managed MCP servers to everyone, with more than 50 in general availability or preview.

Key points
  • The MCP core is now stateless: no initialize handshake, no Mcp-Session-Id header, client metadata travels in _meta on every request, enabling round-robin load balancing.
  • MCP Apps (sandboxed iframe UI) and the Tasks extension (long-running work) are now official parts of the protocol, not workarounds.
  • A formal deprecation policy (Active, Deprecated, Removed, 12-month minimum runway) and a mandatory conformance test suite under AAIF governance make MCP changes predictable.
  • Registry trust and registry size are different things: the official registry has about 2,000 vetted servers versus tens of thousands on third-party registries like Glama.

The skills library: a curated map

A skill is a packaged set of instructions, and sometimes scripts, that teaches Claude Code how to handle a specific kind of task well: debugging a certain way, designing an interface a certain way, writing a certain document format. You install skills, then invoke them by name (typing /skill-name) or let Claude Code pick one automatically when the task matches its description. As of July 2026 the ecosystem has grown large enough that the real skill is knowing which skill to reach for.

Two mechanics changed recently and both matter for how you work day to day. First, since Claude Code v2.1.199 (July 2, 2026), skills can be stacked: typing /skill-a /skill-b task loads several skills onto a single prompt, so Claude can, for example, apply a design skill and a verification skill to the same piece of work at once instead of running them as separate passes. Second, a /dataviz skill for building charts and data visualizations has shipped bundled with Claude Code since v2.1.198, meaning it is available out of the box with no install step.

Distribution itself is decentralized, and that is worth understanding before you install anything. The official path is a git plugin marketplace: a git repository that packages one or more skills for installation, added with /plugin marketplace add owner/repo and then installed with /plugin install. Beyond that official path, third-party directories have grown enormous: SkillsMP indexes over 2 million skills, and claudemarketplaces.com claims more than 300,000 monthly developers browsing its listings. Nobody runs a central index or a single approval process, so quality and safety vary wildly from one skill to the next; treat an unfamiliar skill the way you would treat an unfamiliar npm package, not the way you would treat an Anthropic-shipped feature.

Here is a curated map of the landscape by category, so you know what to look for rather than searching blind.

A simple rule of thumb keeps this from becoming overwhelming: load process skills first, implementation skills second. Brainstorm or debug systematically before you reach for a design or coding skill, otherwise you end up polishing the wrong solution. If a skill might plausibly apply to the task in front of you, load it before acting rather than after; stacking is cheap since v2.1.199, so there is little cost to loading one extra skill and some cost to skipping one you needed. And because distribution is decentralized and unpoliced, always audit third-party skills before installing them, particularly anything that bundles executable scripts; a later lesson in the safety module covers exactly how to do that audit.

For scale, the superpowers collection (hosted at the repository obra/superpowers) is treated as the reference framework for process discipline, and had reached roughly 150,000 GitHub stars by April 2026. Its v6.1.0 release, dated June 30, 2026, specifically reduced the token cost of loading the collection per session, a meaningful change if you stack it with other skills regularly.

Update, July 11, 2026: the curated map described here went public. This course now hosts a searchable directory of 496 skills, plugins and marketplaces at mastering-claude.com/skills/, with a local semantic finder that answers "which skill for this task" in three languages, real install counts from the ecosystem, and the vetting checklist built in. Also note the ecosystem moved: the everything-claude-code repository was renamed to affaan-m/ECC and now installs as a plugin, and superpowers sits in the official Anthropic marketplace.

Key points
  • Skills stack since Claude Code v2.1.199 (July 2, 2026): /skill-a /skill-b task loads several at once.
  • /dataviz ships bundled since v2.1.198; everything else installs via git plugin marketplaces or huge third-party directories like SkillsMP.
  • Load process skills (brainstorming, debugging, verification) before implementation skills (design, coding).
  • Distribution is decentralized and unpoliced: audit third-party skills before installing them.
Work with me

Need this level of execution on your project?

I am Pierre Bottazzi. I built this entire course solo, end to end: 237 lessons in 3 languages, the app, the design, the SEO, the accounts system. That is what I do for clients too: web apps, mobile apps, AI automation, SEO/GEO. First call is free, no strings attached.

Contact me on LinkedInSee sept-tools.com (industry)See totemsauvage.com (art gallery)
Inspiration

Inspired by 0xloucash

One of my inspirations. Loucash (0xloucash) has a gift for always digging up the sharpest AI tips and tricks, then turning them into setups that actually work. With InstallClaw he configures your own OpenClaw AI agent, at your place, in 48 hours.

His InstagramInstallClaw