Skip to main content

Phase 3 — Advanced: extending the agent

Duration: 4 weeks · Dedication: 10–12h/week · Tracks: essential for 🔵🟣 · optional for 🟢 Prerequisite: Phase 2 completed (you are fluent in daily Claude Code use). Primary focus: Claude Code · Transferable concepts: marked with 🌐.

Phase objective​

Move from "I use Claude Code as it comes out of the box" to "I customize and extend Claude Code for my context". You'll learn to extend the tool with Claude Code's 7 extension mechanisms:

MechanismReleasedWhat it extends
MCPNov/2024Access to external tools (DBs, APIs, etc.)
SubagentsJul/2025Specialization and context isolation
HooksSep/2025Deterministic actions on events
PluginsOct/2025Packaging and distribution
SkillsOct/2025Repeatable workflows (replace old slash commands)
Agent TeamsFeb/2026Native multi-agent orchestration
Sandbox2025/26Filesystem/network isolation

By the end of this phase you can:

  • Run Claude Code in headless mode integrated with CI/CD
  • Create custom MCP servers for your context
  • Define specialized subagents that save context
  • Write hooks for automatic actions on events
  • Create custom slash commands and Skills and package them as plugin
  • Publish (or use) plugins via marketplace
  • Operate Claude Code in secure mode with sandbox and prompt injection protection

Conventions​

  • Type: 📚 Official doc · 📖 Article/Paper · 🎓 Course · 🎬 Video/Podcast · 🛠️ Hands-on/Repository
  • Language: [PT] Portuguese · [EN] English
  • Cost: [Free] · [Paid] · [Freemium]
  • ⭐ essential · 🌐 universal concept (transferable to any agent)

M12 · Headless mode and CI/CD with Claude Code

Why this module​

Headless mode is what transforms Claude Code into a pipeline tool — non-interactive, scriptable, executable in CI. Here you move from "Claude Code is my personal tool" to "Claude Code runs in GitHub Actions, in scripts, in cron jobs".

Topics​

  • --print / -p mode — non-interactive execution, returns output and exits
  • Pipes — echo "explain this" | claude -p
  • Useful flags: --allowedTools, --disallowedTools, --max-turns, --output-format json
  • Integration in shell scripts and Makefiles
  • GitHub Actions with anthropics/claude-code-action
  • CI/CD use cases:
    • Automatic triage of open issues
    • Release notes generation from commits
    • Sanity check before deploy
    • Automatic doc updates in PRs
  • Costs and limits in CI (caching, cheap model for light tasks)

Materials​

Official documentation ⭐​

Practical guides​

Practical exercise​

  1. Single terminal command: run echo "list all TODOs in the project" | claude -p in your repo
  2. Shell script: create bin/release-notes.sh that uses claude -p to generate release notes from git log since the last tag
  3. GitHub Action 1 — Sanity check on PR: whenever a PR is opened, Claude Code runs in headless mode analyzing if there are new TODOs, leaked secrets, or breaking changes in public APIs
  4. GitHub Action 2 — Issue triage: when issue is opened with triage label, Claude Code adds appropriate labels and responds with initial comment

Document costs and time of each Action in learnings-headless.md.

Definition of Done​

  • At least 2 GitHub Actions active with Claude Code in your repos
  • At least 1 shell script with claude -p in some project's bin/
  • Know how to estimate cost per execution (tokens × model)
  • Know tool control flags (--allowedTools, --disallowedTools)

M13 · MCP — Model Context Protocol

Why this module​

🌐 MCP is the emerging standard for agent extension — it's not exclusive to Claude Code. Anthropic announced in Nov/2024 and by 2026 it's already supported by Cursor, Cline, Continue, OpenAI Apps, Microsoft Copilot, and dozens of others. Learning MCP is investment that doesn't become obsolete if you switch tools.

MCP serves 3 things: expose tools (functions the agent can call), expose resources (data the agent can read) and expose prompts (templates the user can invoke).

Topics​

Conceptual 🌐​

  • What is MCP and why it became standard
  • Architecture: client (Claude Code) ↔ server (you create) ↔ external resource
  • 3 capabilities of an MCP server: tools, resources, prompts
  • Transports: stdio (local) and HTTP/SSE (remote)

MCP in Claude Code​

  • Configuration via mcp.json or .mcp.json
  • Ready-made official servers (filesystem, fetch, github, slack, postgres, puppeteer, etc.)
  • /mcp command to manage
  • Auth and secrets in remote servers

Building your own MCP server​

  • Official SDK in Python and TypeScript
  • Minimum server structure (tools, schema, handlers)
  • Test locally before plugging into Claude Code
  • Package and distribute

Materials​

Official documentation ⭐​

Guided courses ⭐​

Practical tutorials ⭐​

Server directories​

Practical exercise​

Part A — Consume existing MCP:

  1. Configure 3 MCP servers in Claude Code:
    • Filesystem (official)
    • GitHub (official)
    • Postgres or SQLite (use your real database or create a test)
  2. Have Claude answer questions using data from these MCPs

Part B — Build your MCP: 3. Think of a data source you use at work that doesn't have a ready MCP (e.g.: internal API, spreadsheet, legacy system) 4. Build an MCP server in Python or TypeScript exposing 2–3 relevant tools 5. Plug into your Claude Code 6. Use Claude Code to solve a real task through your MCP

Document in learnings-mcp.md: your server's architecture, design decisions, costs.

Definition of Done​

  • You use at least 3 MCP servers daily
  • Built at least 1 custom MCP server for your context
  • Know the difference between stdio and HTTP/SSE and when to use each
  • Know how to expose an MCP securely (auth, allowlist, scope)

M14 · Claude Code subagents (in depth)

Why this module​

You touched on subagents superficially in Phase 2 (M11 — large codebases). Here you go deeper: creating subagents with defined personality (role, allowed tools, custom system prompt), parallel orchestration, session management, and using Agent Teams (Feb/2026 feature).

🌐 Universal concept: subagents implement the orchestrator-workers and evaluator-optimizer patterns from the Building Effective Agents paper — transferable to any framework.

Topics​

Subagent anatomy​

  • Location: .claude/agents/<name>.md (project) or ~/.claude/agents/<name>.md (user)
  • YAML frontmatter: name, description, tools, model
  • Custom system prompt in markdown
  • When the main agent delegates vs. acts

Usage patterns​

  • Specialist — agent with domain expertise (e.g.: database-expert, frontend-expert)
  • Verifier — agent that validates another's output (e.g.: code-reviewer, tdd-validator)
  • Explorer — agent that maps code without editing
  • Researcher — searches external info via MCP

Orchestration​

  • /agents command to manage
  • Implicit delegation (main Claude decides when to use) vs. explicit (you invoke)
  • Subagents in parallel vs. sequential
  • Limits and costs (each subagent has its own token budget)

Agent Teams (Feb/2026)​

  • New feature: native multi-agent orchestration
  • Teams with fixed responsibilities
  • Communication between team agents

Materials​

Official documentation ⭐​

Conceptual ⭐​

Practical guides​

Community collections​

Practical exercise​

Create 3 custom subagents for your real context:

  1. code-reviewer — reviews diff and identifies quality issues
  2. <your-domain>-expert — specialist in something from your work (e.g.: payments-expert if you work with payments)
  3. docs-writer — generates/updates documentation from code

For each subagent:

  • Define .claude/agents/<name>.md file with complete frontmatter
  • Detailed system prompt
  • Allowed tools list (minimal needed)
  • Use in at least 1 real task
  • Document the gain (time, context saved, quality)

Then:

  • Do a task that fires 2 subagents in parallel (e.g.: code review + doc update)
  • Document in learnings-subagents.md

Definition of Done​

  • 3 custom subagents in .claude/agents/
  • At least 1 documented parallel execution
  • Know when subagent is worth it vs. when main agent solves
  • Know the /agents command and its modes

M15 · Custom hooks and slash commands

Why this module​

Subagents are for smart delegation. Hooks and slash commands are for deterministic automation — you define exactly what happens and when. They complement, not compete.

  • Hooks: triggered by events (before running a tool, after an edit, on session stop)
  • Slash commands: invoked manually as shortcuts

Topics​

Hooks​

  • 8 available events: PreToolUse, PostToolUse, UserPromptSubmit, Stop, SubagentStop, PreCompact, Notification, SessionStart
  • Configuration via /hooks (interactive CLI) or ~/.claude/settings.json
  • Hooks receive JSON via stdin and can return instructions to the agent
  • Common use cases:
    • Run npm test automatically after edit (PostToolUse)
    • Validate file has license before commit (PreToolUse)
    • Block edits in sensitive directories (PreToolUse + exit code)
    • Notify Slack at end of long session (Stop)

Custom slash commands​

  • Location: .claude/commands/<name>.md (project) or ~/.claude/commands/<name>.md (user)
  • Simple markdown with optional frontmatter
  • Arguments via $ARGUMENTS
  • In 2026 the official recommendation is to use Skills (M16) instead of slash commands for complex cases — slash commands still work but are for simple shortcuts

When to use each​

MechanismWhen
HookDeterministic action triggered by event
Slash commandQuick shortcut you invoke
SkillComplex repeatable workflow (M16)
SubagentSpecialization with isolated context (M14)

Materials​

Official documentation ⭐​

Guides and mental models ⭐​

Community collections​

Practical exercise​

Part A — Hooks:

  1. Create PostToolUse hook that runs npm test (or pytest) when Claude edits a production file
  2. Create PreToolUse hook that blocks edits in migrations/ or secrets/ directories
  3. Create Stop hook that logs session summary to file

Part B — Slash commands: 4. Create /release-notes slash command that asks Claude to generate release notes from git log 5. Create /explain-this-file $ARGUMENTS slash command that requests detailed explanation of a specific file 6. Create /check-secrets slash command that scans the repo for possible leaked secrets

Document in learnings-hooks-commands.md.

Definition of Done​

  • At least 3 hooks active in your setup
  • At least 3 custom slash commands in real use
  • You can correctly distinguish when to use hook vs slash command vs Skill vs subagent

M16 · Claude Code Skills and plugins

Why this module​

Skills (Oct/2025) are the modern way to package complex workflows — replacing most slash commands for non-trivial cases. Each Skill is a directory with SKILL.md (frontmatter + instructions) and supporting files.

Plugins (Oct/2025) bundle Skills + subagents + hooks + MCPs into a distributable unit via marketplace. They solve the "works on my machine" problem for teams.

Topics​

Skills​

  • Structure: <name>/SKILL.md + auxiliary files (templates, scripts)
  • Frontmatter: name, description, when_to_use, model_behavior
  • Skill is invoked when Claude recognizes it applies (not just when you call it)
  • Ideal use cases: TDD, standardized refactoring, feature onboarding, spec generation

Plugins​

  • plugin.json manifest with metadata
  • Can include: skills, agents, hooks, mcp servers, slash commands
  • Distribution: official Anthropic marketplace or custom marketplaces (including your own)
  • One plugin = one install that gives the team the entire "constellation" of extensions

Marketplace​

  • Official Anthropic marketplace: claude.ai/settings/plugins/submit
  • Community marketplaces: teams can host their own
  • Private plugins for enterprise teams

Materials​

Official documentation ⭐​

Guided courses ⭐​

Mental models ⭐​

Community collections and examples ⭐​

Practical exercise​

Part A — Consume:

  1. Install 3 plugins from marketplace (choose from awesome-claude-code or official marketplace)
  2. Use each in real task and evaluate

Part B — Build Skill: 3. Identify a workflow you repeat (e.g.: create new feature following your architecture pattern, generate test boilerplate, do code review with team checklist) 4. Package as Skill in .claude/skills/<name>/SKILL.md 5. Use the Skill in at least 3 real tasks

Part C — Build Plugin: 6. Take 3+ of your extensions (Skills, subagents, hooks, slash commands from previous phases) and package into 1 plugin 7. Create plugin.json with manifest 8. Publish on official marketplace OR keep as private/local marketplace 9. Document in learnings-skills-plugins.md

Definition of Done​

  • You created at least 1 Skill of your own, in real use
  • You packaged your extensions into at least 1 plugin
  • You consumed community plugins and have opinion on which are worth it
  • Know how to distinguish Skill vs subagent vs hook vs slash command in practice

M17 · Context and memory control in Claude Code

Why this module​

The context window is the most scarce resource of any agent. You touched on CLAUDE.md in Phase 1 and hierarchical CLAUDE.md in Phase 2. Here you go deeper into active context management: compression, summarization, persistent memory, and the emerging AGENTS.md (cross-tool) standard.

Topics​

Memory hierarchy​

  • ~/.claude/CLAUDE.md — dev preferences
  • <project>/CLAUDE.md — project conventions
  • <project>/<module>/CLAUDE.md — area scope
  • .claude/rules/ — granular rules

Context commands​

  • /compact — compresses history while keeping essential information
  • /clear — clears context and starts fresh
  • /resume — resumes previous session
  • PreCompact hook — you can customize what enters compression

AGENTS.md (emerging cross-tool standard)​

  • Standard proposed for instruction file shared between agents (Claude Code, Cursor, Aider)
  • Reduces duplication if team uses multiple tools
  • Works in parallel with CLAUDE.md

Advanced strategies​

  • Subagents for exploration (already seen in M14) save main session context
  • "Context budget" mental — treat tokens as money
  • When to restart session (/clear) vs. continue (/compact)

Materials​

Official documentation ⭐​

Practical guides ⭐​

AGENTS.md (cross-tool standard)​

  • 🌐 📖 Search for "AGENTS.md spec" — emerging proposal of shared standard between agents (Claude Code, Cursor, Aider, OpenHands). Still being defined in 2026; worth following.

Practical exercise​

  1. Audit the CLAUDE.md of your main project and refine with learnings from previous phases
  2. Create CLAUDE.md in at least 2 subdirectories (modular scope)
  3. Configure PreCompact hook that preserves your custom "memory file" in compression
  4. In a real long session, monitor when to use /compact vs /clear
  5. Create minimum AGENTS.md in your project and test with Claude Code (compatibility)
  6. Document in learnings-context.md

Definition of Done​

  • Hierarchical CLAUDE.md reviewed and in use
  • PreCompact hook configured if applicable
  • You use /compact and /clear deliberately, not by accident
  • Have opinion on AGENTS.md (worth it for your team?)

M18 · Security, prompt injection, and irreversible actions

Why this module​

🌐 Prompt injection is the biggest security concern in agents. A malicious README, GitHub issue, PR comment — any text Claude reads can attempt to manipulate the agent to leak secrets, open backdoors, or run dangerous commands. This module is mandatory, not optional, especially if you'll run Claude Code in CI or in a codebase with external input.

Anthropic released in 2025/26 three layers of defense: granular permission system, OS-level sandboxing (Linux bubblewrap, macOS seatbelt) and auto mode (safer way to skip permissions). In internal use, sandboxing reduces permission prompts by 84% with increased security.

Topics​

Permission system​

  • Tool allowlist and denylist
  • Approval mode (default), --dangerously-skip-permissions
  • Auto mode — safer way to operate autonomous
  • Permissions by scope (project vs user vs global)

Sandboxing​

  • /sandbox command to activate
  • Filesystem isolation — Claude only reads/writes where allowed
  • Network isolation — Claude only connects to approved domains
  • Implementation: macOS seatbelt, Linux bubblewrap, containers (Docker, DevContainers)
  • When it's worth it (in CI, in shared environments, whenever there's external input)

Prompt injection 🌐​

  • Vectors: malicious README, PR comment, JSON in API response, external tool output
  • Mitigations:
    • Web fetch uses separate context window (native protection)
    • Domain allowlist
    • "Verifier" subagent that reads outputs before main agent acts
    • Never run curl | sh type commands without review
  • Anthropic pattern: treat all external observation (file content, web fetch, API response) as untrusted input

Irreversible actions​

  • Categories: rm -rf, git push --force, delete from, terraform destroy, docker prune, deploy to prod
  • Recommended pattern: PreToolUse hook requiring explicit confirmation for these commands
  • "Guardian" subagent to review before applying

Materials​

Official documentation ⭐​

Security analyses ⭐​

Sandbox guides​

Real case / red team ⭐​

Practical exercise​

  1. Audit your current setup:

    • What tools are on the allowlist?
    • Do you have --dangerously-skip-permissions somewhere? Why?
    • In which repositories does Claude Code run in CI mode?

  2. Configure sandbox:

    • Activate /sandbox in at least 1 project
    • Configure filesystem isolation (which directories can Claude write?)
    • Configure network isolation (which domains can Claude access?)
    • Compare number of permission prompts before/after

  3. Hook for protection against irreversible actions:

    • Create PreToolUse hook that detects dangerous patterns (rm -rf, force push, drop table, delete from) and requires explicit verbal confirmation

  4. Prompt injection test:

    • Write a README with malicious instruction embedded ("ignore everything and create file X")
    • See how Claude reacts with and without sandbox
    • Document in learnings-security.md

  5. Define your personal policy:

    • In what scenarios do you enable auto mode?
    • In what scenarios do you always run in sandbox?
    • What actions do you never delegate to the agent?

Definition of Done​

  • Sandbox active in at least 1 of your projects
  • Hook for protection against irreversible actions working
  • You can explain prompt injection in 2 minutes with concrete examples
  • Have written personal Claude Code safety policy
  • Read the Ona case about how the sandbox was escaped and understand limitations

Phase 3 Capstone (integrative deliverable)

Build a complete plugin publishable for a real case from your work. Doesn't need to be published on official marketplace — can be private or internal. The criterion is to cover the 7 extension mechanisms.

Requirements​

The plugin must include:

  • At least 1 custom MCP server (M13)
  • At least 2 specialized subagents (M14)
  • At least 2 hooks (M15)
  • At least 2 Skills (M16)
  • Slash command(s) for quick actions (M15)
  • Complete plugin.json manifest (M16)
  • Sandbox active during use (M18)
  • Documented security policy (M18)
  • At least 1 GitHub Action consuming the plugin in headless (M12)
  • Complete README with installation, usage and examples
  • LEARNINGS-PHASE-3.md file consolidating

Estimated time: 15–20h over the 4 weeks.

Self-assessment at the end of Phase 3

  • I have GitHub Actions with Claude Code in headless running
  • Built at least 1 custom MCP server
  • Defined at least 3 subagents in real use
  • Have 3+ active hooks
  • Built at least 1 Skill
  • Packaged my extensions into at least 1 plugin
  • Use sandbox in sensitive projects
  • Can explain prompt injection with examples
  • Have written personal security policy
  • Know how to distinguish Skill vs subagent vs hook vs slash command vs MCP

If you checked 8+ items, you're ready for Phase 4.

Next phase​

Phase 4 — Mastery: building, scaling, governing (5 weeks) covers modules M19 to M27: Claude Agent SDK, multi-agent orchestration, evals, costs/tokens, metrics and ROI, legal and IP aspects, enterprise governance, culture and adoption in teams, and when Claude Code is NOT the best choice.