Extending Claude Code

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:

• graphify: turn any folder into a queryable knowledge graph.
• dream: automatic nightly memory consolidation.
• continuous-learning: scan git history to extract recurring patterns and propose rules.
• model-custom: activate his composed system prompt (Frankenstein).
• skill-builder: a skill to create skills (meta).

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

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 Strapi MCP (headless CMS) for his MarketDLAGO project: Claude reads and edits the site content directly.
• Third-party MCPs connected to the session: Gmail, Calendar, Drive, Canva, Gamma, SEO tools (Ahrefs), Adobe...

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.

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:

• Context cleanliness: exploratory search (reading 30 files) happens in the sub-agent; the main agent just gets the result. It does not pollute itself.
• Parallelism: you can launch several sub-agents at once on independent tasks.

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.

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:

• Automatically format/lint after each file edit.
• Run the tests when Claude announces it is done.
• Block a commit if a secret is detected.
• Trigger an external CI system via webhook when a task finishes.

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.

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.

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:

• SKILL.md (required): the frontmatter plus instructions
• README.md (optional): human-readable documentation for the skill author
• examples/ (optional): sample inputs and expected outputs Claude can learn from
• templates/ (optional): file templates Claude should copy or fill in during execution

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:

• Invocation: slash command (e.g. /deep-research) or natural language trigger defined in CLAUDE.md.
• Scope: skills in ~/.claude/skills/ are global; a project can add its own in .claude/skills/.
• Composition: one skill can call the Skill tool to chain into another skill.
• Listing: run /skill-stocktake to audit every installed skill and its trigger.

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):

• Tools: callable functions Claude can invoke, such as searching a database, running a shell command, or posting to an API. Each tool has a name, a description, and a typed input schema so Claude knows how to call it correctly.
• Resources: read-only data sources (files, URLs, database rows) that Claude can fetch and include in its context window (the working memory it uses per conversation). Resources are identified by a URI and returned as text or binary blobs.
• Prompts: named, reusable prompt templates stored on the server. A prompt can accept arguments and return a ready-to-use message, making it easy to share consistent instructions across a team without copy-pasting.

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.

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.

• Add a server at user scope: claude mcp add <name> -- <command> [args]
• Add a server at project scope: claude mcp add --scope project <name> -- <command> [args]
• List connected servers and their status: claude mcp list
• Remove a server: claude mcp remove <name>
• Trigger an OAuth login flow for a server: claude mcp authenticate <name>

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.

• Install the SDK: npm install @modelcontextprotocol/sdk
• Choose stdio for local tools, HTTP/SSE for shared or remote servers.
• Write a clear description: Claude picks tools by reading that text.
• Validate inputs with JSON Schema required and type fields.

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:

• Orchestrator: the parent agent that plans work, splits it into sub-tasks, and assembles the results. It uses the Task tool internally to spawn children.
• Sub-agent (worker): a child process that receives a single, well-scoped prompt and returns a result. It has no memory of sibling agents.
• Reviewer agent: a specialised sub-agent whose only job is to evaluate another agent's output against a checklist or rubric, then report pass/fail with reasoning.

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.

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:

• PreToolUse: fires just before Claude calls any tool (file read, bash command, web fetch, etc.). Use it to log, block, or modify the call.
• PostToolUse: fires immediately after a tool returns its result. Use it to audit output, trigger side-effects, or update a status display.
• Stop: fires when Claude finishes its final response and is about to go idle. Use it to run cleanup, send a notification, or update a memory file.
• SessionStart: fires once when a new Claude Code session opens. Use it to load context, print a dashboard, or set environment variables for the session.
• Notification: fires when Claude Code emits a user-facing notification (for example, a permission prompt or a background task update).

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.

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):

• Exit 0: allow the tool call to proceed normally.
• Exit 2: block the tool call and surface your stdout message to the user as an error.
• Any other non-zero exit: block silently (Claude Code treats it as a hard failure).

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.

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:

• Commands: slash commands the user can type, defined as sections in SKILL.md or as separate .md files in a commands/ subfolder.
• Hooks: lifecycle scripts (for example, PostToolUse or Stop) declared in a hooks/ subfolder and referenced from settings.json.
• MCP servers: external tool providers listed under mcpServers in the skill's companion settings.json fragment.
• Agents: reusable sub-agent prompts that the skill's commands can spin up via the Task tool.

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.

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:

• PreToolUse: runs before Claude calls a tool (good for logging or blocking).
• PostToolUse: runs after a tool call completes.
• Stop: runs when the session ends (good for summaries or memory sync).
• Notification: fires when Claude sends a notification event.

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.

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:

• --output-format json: emits a structured JSON object instead of prose, useful when a script needs to parse the result.
• --output-format text: plain text, no markdown, good for piping into grep or sed.
• --verbose: shows tool calls and internal reasoning steps, useful for debugging why Claude did something unexpected.
• --no-stream: waits for the full response before printing, instead of streaming tokens as they arrive.

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.

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.

• run_in_background: non-blocking shell execution, result delivered as a notification.
• WebSearch: live web search, returns snippets and links.
• WebFetch: fetches and reads a full page at a given URL.
• All three work inside a normal Claude Code conversation, no plugin required.