The landscape: what all these things are

Read ~20 min · Lab ~20 min · Total ~40 min · No setup required

Before touching anything, get the map straight. Most confusion about "Claude vs Claude Code vs Cowork vs skills vs MCP" comes from conflating models, surfaces, and extension mechanisms. They're three different axes.

Axis 1 — Models

The model is the reasoning engine. As of mid-2026 the current line is Claude Opus 5 (deepest reasoning, hardest problems), Claude Sonnet 5 (the workhorse — most agentic and coding work), Claude Haiku 4.5 (fast/cheap, high-volume classification and simple tool loops), and Claude Fable 5. API strings: claude-opus-5, claude-sonnet-5, claude-haiku-4-5-20251001, claude-fable-5.

Axis 2 — Surfaces (where you talk to Claude)

Cowork and Claude Code are the same engine underneath — local, agentic, capable of spawning subagents and sustaining long tasks. Cowork is that engine pointed at documents and business workflows; Claude Code is it pointed at a codebase.

Axis 3 — Extension mechanisms (how you make Claude yours)

This is where the leverage is, and where most people stop too early. Five mechanisms, each answering a different question:

Plugins are the packaging layer: one installable bundle that can ship skills + subagents + slash commands + hooks + MCP server definitions together. Marketplaces are how plugins get distributed.

One real scenario, all five mechanisms

Your platform team gets paged at 02:00. Someone has to write the postmortem, and quality varies wildly depending on who's on call. Here's how each mechanism plays a distinct part:

Notice that none of these substitutes for another. Understanding why each piece is a different mechanism is the whole point of this module.

The decision tree you'll use constantly

Need Claude to behave differently?
├─ Always, in this project?          → CLAUDE.md / project instructions
├─ Only for a recurring task type?   → Skill
├─ It needs external data/actions?   → MCP server (connector)
├─ It needs an isolated context or
│  parallelism?                      → Subagent
├─ It must happen 100% of the time,
│  no model judgment?                → Hook
└─ Ship several of the above to
   a team as one unit?               → Plugin (+ marketplace)

Claude Desktop: Chat, Cowork, Code

Read ~20 min · Setup + lab ~45 min · Total ~1h 5m

The desktop app is one window with three modes. Knowing which mode a task belongs in is half the skill.

Chat

Standard conversational Claude, plus:

• Projects — a persistent workspace with its own instructions and knowledge files. Project instructions are prepended to every conversation in that project. This is your first "always-on context" lever.
• Artifacts — substantial code/documents rendered in a side panel. Special rendering for .md, .html, .jsx, .mermaid, .svg, .pdf.
• Connectors — MCP servers (Gmail, Calendar, Drive, GitHub, Slack, Linear, Notion…) enabled per-account in settings.
• Extended thinking — toggle deeper reasoning for hard problems.

Cowork

Agent mode. You give an outcome, not a question. Claude then plans, uses tools, and produces files. Its distinguishing capabilities:

• Local file access to a folder you explicitly select. Read, write, edit, reorganize.
• A sandboxed Linux shell (separate VM from your machine) with Python, Node, and CLI tools — for running code, data processing, conversions.
• Document generation skills — real .docx, .xlsx, .pptx, .pdf output, not markdown pretending to be one.
• Computer use — screenshot and control native desktop apps, with per-app permission tiers.
• Claude in Chrome — DOM-aware browser automation.
• Scheduled tasks — recurring or one-off future runs.
• Live artifacts — persistent HTML pages that re-fetch from your connectors each time you open them.
• Subagents — parallel workers with isolated context.

Code

Claude Code in the desktop app (or terminal, or IDE). Repo-aware: it greps, reads, edits, runs tests, makes commits, opens PRs. Module 11 goes deep.

Choosing the mode

Setup checklist

1. Install the desktop app; sign in on a paid plan.
2. Create a dedicated working folder (e.g. ~/Desktop/Claude_Cowork) and select it in Cowork. Never point Claude at your entire home directory on day one.
3. Connect two connectors you actually use daily (Calendar + one work system).
4. Install the Claude in Chrome extension if you do any browser-based work.
5. Install Claude Code CLI: npm install -g @anthropic-ai/claude-code, then run claude in a repo.

Context engineering & prompting that scales

Read ~30 min · Lab ~35 min · Total ~1h 5m · The highest-ROI module in the course

"Prompt engineering" undersells it. What you're really doing is context engineering: deciding what information is in the window at the moment the model decides. For agents, this matters more than clever wording.

The five levers

1. Task specification — what "done" looks like, concretely.
2. Context supply — the facts, files, and schemas needed, and nothing else.
3. Constraints — format, length, what to avoid, what to never do.
4. Examples — positive and, critically, negative.
5. Reasoning scaffold — step order, checkpoints, self-verification.

Techniques that actually move the needle

1. Be specific and detailed — but about the right things

Vague: "Review this PR."
Strong: "Review this PR for (a) N+1 query risk, (b) unhandled error paths in the async branch, (c) backward-compatibility of the API change. For each finding give file:line, severity, and a concrete fix. Ignore style."

2. Give role and audience

"You're reviewing for a team that deploys 12x/day and cannot take downtime" changes the entire risk calculus of the output.

3. Use XML tags for structure

<context>
Service handles 40k rps. Postgres 15. Deploy = blue/green.
</context>

<task>
Propose a migration plan for adding a NOT NULL column to `orders`.
</task>

<constraints>
- Zero downtime, no table rewrite lock > 100ms
- Must be revertible at every step
</constraints>

<output_format>
Numbered steps. Each step: SQL, expected duration, rollback.
</output_format>

Tags make boundaries unambiguous and let you reuse the template programmatically. This is the single formatting habit worth adopting today.

4. Encourage step-by-step reasoning

"Before answering, list the assumptions you're making and the information you'd need to be more confident." Then answer. For hard problems, ask Claude to enumerate options and reject them explicitly before choosing.

5. Negative examples beat more positive examples

<good_example>
"auth: reject expired refresh tokens (#4412)"
</good_example>
<bad_example reason="describes the diff, not the intent">
"changed if statement in token.py"
</bad_example>

6. Prefill and format-forcing

Specify exact output shape, and say what not to include ("no preamble, no summary of what you did").

7. Ask for the failure mode

"What's the most likely way this plan is wrong?" is the cheapest quality upgrade available. Use it on every architecture answer.

Agentic prompting is different

In agent mode you're not writing one prompt — you're setting up a loop. What matters shifts:

Context rot and how to avoid it

• Long conversations degrade. Start fresh sessions at natural boundaries rather than pushing a 200-turn thread.
• Don't dump whole repos or 300-page PDFs. Point at them; let Claude search. Retrieval beats stuffing.
• Isolate noisy work in subagents so the exploration transcript doesn't pollute the main context — you get back only the conclusion.
• Prompt caching (API): put stable content — system prompt, schemas, long docs — at the front so it can be cached and reused cheaply across calls.

CLAUDE.md, rules & memory in depth

Read ~35 min · Lab ~40 min · Total ~1h 15m

Every session starts with an empty context window. Everything Claude "knows" about your project on turn one got there because you or Claude put it there. Four mechanisms do that, and they behave very differently.

The memory hierarchy

Where CLAUDE.md lives — and the load order

Listed broadest to most specific. Later entries appear later in context, so instructions closest to where you launched Claude are read last.

Claude walks up the directory tree from your working directory, loading every CLAUDE.md and CLAUDE.local.md it finds, root-down. Files in subdirectories aren't loaded at launch — they load on demand when Claude reads a file in that directory.

{ "claudeMdExcludes": ["**/monorepo/CLAUDE.md",
                      "/abs/path/monorepo/other-team/.claude/rules/**"] }

Writing a CLAUDE.md that actually works

• Size: target under 200 lines. Longer files consume more context and measurably reduce adherence. This is the single most-violated rule in practice.
• Structure with headers and bullets. Claude scans structure the way readers do; dense paragraphs get skimmed.
• Be verifiable. "Use 2-space indentation" beats "format code properly". "Run npm test before committing" beats "test your changes".
• Hunt contradictions. If two files disagree, Claude may pick either one arbitrarily. Review nested CLAUDE.md files and rules periodically.
• Use HTML comments for humans. Block-level <!-- maintainer note --> comments are stripped before injection — they cost zero tokens.

When to add something

Treat CLAUDE.md as the place you write down what you'd otherwise re-explain. Add when: Claude makes the same mistake twice · code review catches something Claude should have known · you type the same correction you typed last session · a new teammate would need the same context.

# Project: payments-gateway

## What this is
Go service handling card auth + capture. gRPC in, Kafka out.

## Commands
- build:  make build
- test:   make test          # must pass before any commit
- lint:   golangci-lint run

## Conventions
- Errors: wrap with %w, never swallow.
- Money is always int64 minor units. Never float.
- No new deps without an ADR in docs/adr/.

## Gotchas
- `internal/ledger` is append-only. Never write an UPDATE against it.
- Integration tests need `docker compose up -d` first.

/init generates a starting CLAUDE.md by analysing your codebase; if one exists it proposes improvements rather than overwriting. /doctor can propose trims — it cuts what Claude can derive from the code itself (directory layouts, dependency lists) and keeps pitfalls, rationale, and conventions that differ from tool defaults.

Imports with @path

See @README for project overview and @package.json for npm commands.

# Additional instructions
- git workflow @docs/git-instructions.md
- personal prefs @~/.claude/my-project-instructions.md

• Relative paths resolve against the importing file, not the working directory. Recursive imports allowed, max depth 4.
• Imports inside backticks or fenced code blocks are not expanded — write `@README` to mention a path literally.
• Imports do not save context. Imported files are expanded and loaded at launch, same as inline text. Use them for organization, use rules to actually reduce load.
• An import in a project file that resolves outside your working directory is "external" and triggers a one-time approval dialog — protection against files someone commits to a shared repo.

AGENTS.md

Claude Code reads CLAUDE.md, not AGENTS.md. If your repo already has one, bridge them:

@AGENTS.md

## Claude Code
Use plan mode for changes under `src/billing/`.

A symlink works too (ln -s AGENTS.md CLAUDE.md), except on Windows where you need Developer Mode. /init also reads Cursor and Copilot rule files; /import brings across another agent's config wholesale.

.claude/rules/ — modular and path-scoped

your-project/
├── .claude/
│   ├── CLAUDE.md
│   └── rules/
│       ├── code-style.md
│       ├── testing.md
│       └── frontend/accessibility.md

All .md files are discovered recursively. Rules without paths frontmatter load at launch with the same priority as .claude/CLAUDE.md. Rules with it load only when Claude reads a matching file:

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

# API development rules
- All endpoints must include input validation
- Use the standard error response format

Glob notes: brace expansion works (src/**/*.{ts,tsx}) but a rule's whole paths list shares a budget of 1,000 expanded patterns; over-budget patterns are used unexpanded and match nothing. [ starts a bracket expression — escape it as \[ to match literally. Symlinks in .claude/rules/ are resolved, so you can link a shared company rules directory into many repos. User-level rules live in ~/.claude/rules/ and load before project rules.

Auto memory — the notes Claude keeps for itself

On by default. Claude decides what's worth remembering — build commands, debugging insights, your preferences — and writes it without being asked. Storage is per-repository and machine-local:

~/.claude/projects/<project>/memory/
├── MEMORY.md          # concise index — loaded every session
├── debugging.md       # topic file — loaded on demand
└── api-conventions.md

Frontmatter and block HTML comments are stripped before the index loads, so they don't count toward the limits. Claude records a modified ISO timestamp in frontmatter so both of you can see how current a fact is. "Saved 2 memories" / "Recalled 2 memories" in the UI is this system working.

What survives /compact

Because skill bodies truncate from the end, put the most important instructions near the top of every SKILL.md. And if a rule must survive compaction, drop its paths: frontmatter or move it into the project-root CLAUDE.md.

Organization-wide memory

Deploy a managed CLAUDE.md to the policy path via MDM/Group Policy/Ansible, or put the content inline in managed-settings.json under the claudeMd key. Only honored from managed or policy settings.

{ "claudeMd": "Always run `make lint` before committing.\nNever push directly to main." }

Settings are enforced by the client regardless of what Claude decides. CLAUDE.md shapes behaviour but is not enforcement. Keep that line clear when you write policy.

Debugging "Claude isn't following my CLAUDE.md"

1. /context — check the Memory files list. If your file isn't there, Claude cannot see it. This is the answer about half the time.
2. /memory — open and edit any memory file, toggle auto memory, browse what Claude saved.
3. Make the instruction concrete and verifiable.
4. Look for a contradicting instruction in an ancestor CLAUDE.md or a rule.
5. Still unreliable? It isn't a memory problem — make it a hook.
6. Need it at system-prompt level? --append-system-prompt, though that must be passed every invocation, so it suits scripts more than interactive use.
7. Use the InstructionsLoaded hook to log exactly which instruction files loaded, when, and why — the precise tool for debugging path-scoped rules.

CLAUDE.md content is delivered as a user message after the system prompt, not as part of it. That's why specificity matters so much.

Cowork: files and artifacts

• Uploads land in an uploads folder; text, CSV, markdown, images and PDFs often arrive directly in context, others must be read from disk.
• Outputs must go to your selected folder — the temp scratchpad doesn't persist between sessions.
• Chat artifacts are single-file renders; never use localStorage or sessionStorage in them (unsupported — use in-memory state).
• Live artifacts persist and re-call your connectors on open. If you just answered a connector question as a table, that's a live-artifact candidate.

Cowork deep dive: agent mode in anger

Read ~25 min · Lab ~60 min · Total ~1h 25m · Heavily hands-on

The anatomy of a Cowork run

A good Cowork task has five parts. Learn to supply all five and your hit rate jumps:

1. Goal — the outcome, not the steps.
2. Inputs — where the source material is.
3. Constraints — format, audience, length, what to exclude.
4. Deliverable — exact file(s) and where to save them.
5. Verification — how it should check itself.

Goal: A vendor comparison for the platform team's caching decision.

Inputs: ./vendors/ has 6 PDFs of pricing + SLA docs.
        ./current-usage.csv has our last 90 days of cache traffic.

Constraints: Audience is engineering leadership. Max 2 pages of prose
plus one table. Assume they know what Redis is. No marketing language.
Call out anything the vendor docs are silent on.

Deliverable: ./out/caching-vendor-analysis.docx plus a supporting
./out/cost-model.xlsx with the per-vendor monthly cost at our volumes.

Verify: recompute the top-line cost figure two different ways and tell
me if they disagree. List any claim you could not source to a document.

Tool tiers — pick the right one

Cowork can reach the outside world four ways, in descending order of preference:

1. A dedicated MCP connector for the app (Gmail, Calendar, Linear, GitHub). Fast, structured, reliable.
2. Claude in Chrome for web apps with no connector. DOM-aware, far better than pixel-clicking.
3. Computer use for native desktop apps and cross-app workflows.
4. Web fetch/search for public content.

Computer-use permission tiers are worth knowing because they explain surprising failures: browsers are granted read (visible, not clickable — use Chrome tools instead), terminals and IDEs are click (no typing — use the shell tool instead), everything else is full.

Scheduled tasks

Anything you'd do on a cadence — a morning brief, a weekly digest, a nightly repo health check, a "tell me if X changes" watcher — should be a scheduled task rather than a habit. Cron for recurring, a single fire time for one-offs.

Every weekday at 07:30:
  1. Pull yesterday's merged PRs and closed incidents.
  2. Pull today's calendar.
  3. Flag anything where I'm the blocker.
  4. Write a < 300 word brief and save it to ./briefs/YYYY-MM-DD.md

Subagents in Cowork

Spawn them when work is (a) genuinely parallel or (b) context-polluting. Each starts cold, so a subagent must be given everything it needs in its prompt. Typical wins: fan-out research across 8 sources, reviewing 5 documents independently, or a dedicated verification agent that re-checks the primary agent's numbers without having seen its reasoning.

Live artifacts

A saved HTML page that calls your connectors on load. Inside the page you get, roughly:

• window.cowork.callMcpTool(name, args) — call any connector tool you declared.
• window.cowork.askClaude(prompt, data[]) — cheap inference over data you just fetched (summaries, classification).
• window.cowork.runScheduledTask(id) — trigger a scheduled task.

Build order that works: call the tool once in chat first, look at the actual response shape, then write the page's parser against what you observed. MCP wrappers reshape upstream APIs; assumptions will bite you.

Skills you already have

Cowork ships document skills — docx, xlsx, pptx, pdf — plus skill-creator, schedule, and whatever plugins you've installed. Two rules:

• Research first, format second. Gather all facts before invoking a document skill; reading the format instructions early anchors the model on mechanics instead of substance.
• Skills compose. "Generate an image and put it in the report" = imagegen skill + docx skill.

MCP as a user: connectors that earn their keep

Read ~20 min · Lab ~30 min · Total ~50 min

MCP — the Model Context Protocol — is the open standard for connecting models to tools and data. In the Claude apps you meet it as connectors. You'll build servers in Module 9; first, learn to use them well, because that teaches you what a good server looks like.

The mental model

  ┌─────────────┐         JSON-RPC          ┌──────────────┐
  │   HOST      │  ◄───────────────────►    │  MCP SERVER  │
  │ (Claude app)│                            │  (Linear,    │
  │  + CLIENT   │   stdio  or  HTTP+SSE      │   your API)  │
  └─────────────┘                            └──────────────┘

  Server offers:  tools · resources · prompts
  Client offers:  sampling · roots · elicitation

• Tools — actions the model can invoke (create_issue, search_threads).
• Resources — read-only addressable data the client can pull in.
• Prompts — reusable templates the server exposes, often surfaced as slash commands.
• Sampling — the server asks the client for a model completion. Lets servers be smart without holding API keys.
• Roots — the client tells the server which filesystem/URI boundaries it may operate in.
• Elicitation — the server asks the user a question mid-flow.

Transports: stdio for local, single-user servers; Streamable HTTP for remote, multi-client servers over HTTPS. Recent spec work has moved server→client requests (sampling, elicitation) toward multi-round-trip requests rather than requiring persistent bidirectional streams, and added ttlMs/cacheScope on list/read responses so clients can cache tool and resource listings.

Using connectors well

• Enable narrowly. Every connected server's tool schemas consume context and expand your attack surface. Ten well-chosen connectors beat forty.
• Know each tool's granularity. "Search Slack" vs "get thread" vs "list channels" produce wildly different token costs. Ask Claude which tool it will use before an expensive run.
• Auth is per-server. OAuth-based connectors need an interactive authorization; they simply won't work in a background/scheduled run until authorized.
• Discoverability. If a task implies an external service, search the connector registry before falling back to browser automation.

Security posture (start caring now)

Reading a tool result like an engineer

When a connector misbehaves, the debugging ladder is: (1) does the tool exist and is the server authorized? (2) call it with minimal args and inspect raw output; (3) check whether the wrapper renamed parameters; (4) check pagination and limits — most "the data is missing" bugs are actually "you got page 1 of 12".

Skills: what they are and how to use them

Read ~18 min · Lab ~30 min · Total ~50 min

An Agent Skill is a folder containing a SKILL.md — YAML frontmatter plus markdown instructions — and optionally scripts, templates, and reference files. It's an open format: the same skill works in Claude apps, Cowork, Claude Code, and the Agent SDK.

The three-stage load

1. Discovery — at session start, Claude sees only every skill's name and description. Cheap.
2. Activation — when a task matches a description, the full SKILL.md body enters context.
3. Execution — the instructions may then read reference.md, run scripts/convert.py, or open a template. Loaded only as reached.

Anatomy

my-skill/
├── SKILL.md            # frontmatter + instructions (keep < ~500 lines)
├── reference.md        # deep detail, loaded on demand
├── templates/
│   └── report.docx
└── scripts/
    └── validate.py     # deterministic work — don't make the model do math

---
name: incident-postmortem
description: Write a blameless postmortem after an incident is resolved.
  Use when the user mentions a postmortem, RCA, incident writeup, or says
  an incident has been resolved and needs documenting. Not for live
  incident triage.
---

# Incident postmortem

## When to use
After resolution only. For an active incident, use `incident-response`.

## Procedure
1. Gather: timeline, detection time, mitigation time, customer impact.
2. Ask for anything missing before drafting. Do not invent timestamps.
3. Draft using templates/postmortem.md.
4. Contributing factors, never individual blame.
5. Every action item needs an owner and a date.

## Output
Markdown at docs/postmortems/YYYY-MM-DD-<slug>.md

Where skills come from

• Built-in — document skills (docx, xlsx, pptx, pdf), skill-creator, schedule, and others.
• Plugins — installing a plugin installs its skills (you likely have engineering/data/productivity bundles).
• Your own — personal or team skills, in a skills directory or shipped in a plugin.

Invoking

Skills mostly fire automatically from their descriptions. You can also name one directly (many surface as /name). Custom slash commands and skills have converged — a slash command is essentially a prompt-template skill.

Skill vs the alternatives — the honest comparison

Authoring skills I: design and write

Read ~20 min · Lab ~50 min · Total ~1h 10m · You will ship a working skill

Step 1 — Pick something that deserves a skill

Good candidates share three traits: recurring, opinionated (there's a right way people get wrong), and bounded (you can describe done). Bad candidates: one-offs, pure knowledge lookups, and "be smarter."

Step 2 — Write the description first

Seriously. Before any instructions. The description is the classifier. A strong one has four elements:

1. What it does, in one clause.
2. When to use it — concrete triggers, using the vocabulary users actually type.
3. What form the input/output takes, if it's distinguishing.
4. When not to use it — the negative boundary.

description: >
  Review a pull request or diff for security, performance, and
  correctness issues. Use when the user shares a PR URL or a diff,
  asks "review this before I merge", or asks whether a change is safe,
  or mentions N+1 queries, injection risk, missing error handling, or
  race conditions. Do NOT use for style/formatting-only feedback, for
  writing new code, or for reviewing an entire codebase.

Step 3 — Structure the body

---
name: kebab-case-name
description: <the classifier, per above>
---

# Human-readable title

## When to use / when not to use
<restate the boundary for the model that has now loaded you>

## Inputs you need
<what to gather; explicitly say "ask if missing, don't invent">

## Procedure
1. Numbered, imperative steps.
2. Decision points as explicit conditionals.
3. Point at scripts/ for anything deterministic.
4. Point at reference.md for detail you don't always need.

## Output
<exact format and location>

## Failure modes
<what commonly goes wrong and what to do instead>

Step 4 — Apply progressive disclosure ruthlessly

• Keep SKILL.md under ~500 lines. If it's longer, you're inlining reference material.
• Move exhaustive detail (API field lists, style guides, edge-case catalogs) to reference.md and link it: "For the full field mapping, read reference.md."
• Move determinism to scripts/. Models are excellent at orchestrating scripts and mediocre at being one.
• Ship templates/ rather than describing a template in prose.

Writing style that models follow well

Where to put it

• Personal — your user-level skills directory; available everywhere you work.
• Project — .claude/skills/<name>/SKILL.md in the repo; versioned with the code, available to everyone who clones it. This is usually the right default for team skills.
• Distributed — inside a plugin (Module 10).

In Cowork you can also have Claude save a skill for you directly — describe the workflow and ask it to create one. Use skill-creator to scaffold, then edit by hand; the scaffold is a starting point, not the deliverable.

Authoring skills II: scripts, evals, iteration

Read ~25 min · Lab ~60 min · Total ~1h 25m · Python

Bundling scripts

A skill script is ordinary code Claude runs. Design it like a CLI someone else will use: clear args, useful errors, exit codes, and output the model can parse.

# scripts/validate_postmortem.py
"""Validate a postmortem markdown file against team requirements.

Usage: python validate_postmortem.py <path>
Exit 0 = valid. Exit 1 = problems (printed to stdout, one per line).
"""
import re, sys, pathlib

REQUIRED = ["## Summary", "## Timeline", "## Contributing factors",
            "## Action items", "## Detection"]

def main(path: str) -> int:
    text = pathlib.Path(path).read_text(encoding="utf-8")
    problems: list[str] = []

    for section in REQUIRED:
        if section not in text:
            problems.append(f"MISSING SECTION: {section}")

    # every action item needs an owner and a date
    for line in text.splitlines():
        if line.strip().startswith("- [ ]"):
            if "@" not in line:
                problems.append(f"ACTION ITEM WITHOUT OWNER: {line.strip()}")
            if not re.search(r"\d{4}-\d{2}-\d{2}", line):
                problems.append(f"ACTION ITEM WITHOUT DATE: {line.strip()}")

    # blameless check
    for name in re.findall(r"\b[A-Z][a-z]+ (?:caused|broke|forgot)\b", text):
        problems.append(f"POSSIBLE BLAME LANGUAGE: {name}")

    for p in problems:
        print(p)
    return 1 if problems else 0

if __name__ == "__main__":
    if len(sys.argv) != 2:
        print("usage: validate_postmortem.py <path>"); sys.exit(2)
    sys.exit(main(sys.argv[1]))

Then in SKILL.md:

5. Validate the draft:
   `python scripts/validate_postmortem.py <path>`
   If it exits non-zero, fix every reported problem and re-run.
   Do not present the postmortem to the user until it exits 0.

Evaluating a skill

You're an engineering leader — you know an unmeasured system drifts. Skills are no different. Evaluate two things separately:

A. Triggering accuracy

Build a small labelled set: 10–15 prompts that should fire the skill (varied phrasing, including terse and oblique), and 10–15 that shouldn't (especially ones that should fire a neighbouring skill). Run each in a fresh session; record fired/didn't. Anything below ~90% on the positive set means the description is under-specified; false positives mean it's over-broad.

B. Output quality

Define 4–6 binary criteria for a good output, then grade. Binary beats 1–5 scales — "does every action item have an owner?" is checkable; "is it well-written?" isn't.

# evals/cases.yaml
- id: pm-basic
  prompt: "We resolved the checkout outage. Write it up."
  should_trigger: incident-postmortem
  criteria:
    - has_all_required_sections
    - every_action_item_has_owner_and_date
    - no_individual_named_as_cause
    - asked_for_missing_timeline_rather_than_inventing

- id: pm-negative
  prompt: "Checkout is down right now, help me triage."
  should_trigger: incident-response   # NOT postmortem

Run the suite whenever you change a description. Note that model outputs vary — run each case 3× and look at the pass rate, not a single sample.

The iteration loop

observe failure → classify it
   ├─ didn't fire            → fix the DESCRIPTION
   ├─ fired on wrong task    → add NEGATIVE BOUNDARY
   ├─ fired, wrong steps     → fix the PROCEDURE (more explicit conditionals)
   ├─ fired, right steps,
   │  bad artifact           → add a TEMPLATE or SCRIPT + gate
   └─ inconsistent across
      runs                   → replace judgment with determinism

Team skills as code

• Version them in the repo under .claude/skills/. PR review applies.
• Treat description changes like API changes — they alter routing behaviour for everyone.
• Keep a CHANGELOG for non-trivial skills; people will wonder why behaviour shifted.
• Add the eval suite to CI if the skill is load-bearing.

Building MCP servers in Python

Read ~30 min · Lab ~75 min · Total ~1h 45m · Python · You will ship a working server

Now the other half of extension: giving Claude reach. We'll use the official Python SDK's FastMCP, which handles the JSON-RPC plumbing so you write plain functions.

Hello, server

pip install "mcp[cli]" httpx

# server.py
from mcp.server.fastmcp import FastMCP

mcp = FastMCP("deploy-tools")

@mcp.tool()
def get_service_status(service: str, env: str = "prod") -> dict:
    """Get current deploy status for a service.

    Use when the user asks whether a service is healthy, what version
    is deployed, or when it last shipped. Returns version, health, and
    last deploy timestamp.

    Args:
        service: Service slug, e.g. "payments-gateway".
        env: One of "prod", "staging", "dev". Defaults to "prod".
    """
    # ... call your real internal API here ...
    return {
        "service": service,
        "env": env,
        "version": "1.42.3",
        "healthy": True,
        "deployed_at": "2026-08-07T14:02:11Z",
    }

if __name__ == "__main__":
    mcp.run()   # stdio transport

Resources and prompts

@mcp.resource("runbook://{service}")
def runbook(service: str) -> str:
    """The on-call runbook for a service, as markdown."""
    return (RUNBOOKS / f"{service}.md").read_text()

@mcp.prompt()
def rollback_plan(service: str, from_version: str) -> str:
    """Template: produce a rollback plan for a bad deploy."""
    return f"""Produce a rollback plan for {service} from {from_version}.
Include: blast radius, DB migration reversibility, feature flags to
flip, and the verification step after rollback."""

Rule: tools do, resources read, prompts template. Don't make a tool that just returns a static document — make it a resource.

Designing tools models use well

Async, HTTP calls, and remote transport

import httpx
from typing import Literal
from mcp.server.fastmcp import FastMCP

mcp = FastMCP("deploy-tools")

@mcp.tool()
async def recent_deploys(
    service: str,
    env: Literal["prod", "staging", "dev"] = "prod",
    limit: int = 10,
) -> list[dict]:
    """List recent deploys for a service, newest first.

    Use for questions like "when did X last ship" or "what changed
    in the last N deploys". limit is capped at 50.
    """
    limit = min(limit, 50)
    async with httpx.AsyncClient(timeout=10) as c:
        r = await c.get(
            f"{API}/deploys",
            params={"service": service, "env": env, "limit": limit},
            headers={"Authorization": f"Bearer {TOKEN}"},
        )
    if r.status_code == 404:
        return [{"error": f"No service named {service!r}. "
                          f"Call list_services to see valid names."}]
    r.raise_for_status()
    return [
        {"version": d["version"], "at": d["finished_at"],
         "author": d["author"], "sha": d["sha"][:8]}
        for d in r.json()["items"]
    ]

if __name__ == "__main__":
    mcp.run(transport="streamable-http")   # remote, multi-client

Connecting it

For local development, register the stdio server with your client (Claude Desktop config, or claude mcp add for Claude Code). For remote servers, deploy behind HTTPS with OAuth and register the URL. Inside a plugin, ship a .mcp.json and it's installed with the plugin (Module 10).

{
  "mcpServers": {
    "deploy-tools": {
      "command": "python",
      "args": ["/abs/path/to/server.py"],
      "env": { "DEPLOY_API_TOKEN": "..." }
    }
  }
}

Testing

• Use the MCP Inspector (mcp dev server.py) to list and call tools without a model in the loop.
• Unit-test the underlying functions directly — they're just Python.
• Then test selection: give Claude the server and 10 natural questions; check it picks the right tool with the right args. Bad selection is almost always a docstring problem.

Security

Plugins & marketplaces: distribution

Read ~25 min · Lab ~50 min · Total ~1h 15m

You now have skills and an MCP server. A plugin is how you hand all of it to 200 people as one install, and update it centrally afterwards. For a director, this is the module that turns individual productivity into org capability.

What a plugin can contain

my-plugin/
├── .claude-plugin/
│   └── plugin.json          # required manifest
├── .mcp.json                # MCP server definitions (optional)
├── skills/
│   └── incident-postmortem/
│       ├── SKILL.md
│       └── scripts/validate_postmortem.py
├── agents/
│   └── security-reviewer.md # subagent definitions
├── commands/
│   └── ship.md              # slash commands
├── hooks/
│   └── hooks.json           # lifecycle automation
└── README.md

plugin.json

{
  "name": "platform-eng",
  "displayName": "Platform Engineering",
  "version": "1.4.0",
  "description": "Skills, connectors and guardrails for the platform org: postmortems, ADRs, deploy checks, and deploy-tools MCP access.",
  "author": { "name": "Platform Eng", "email": "platform@example.com" },
  "keywords": ["incident", "adr", "deploy", "postmortem", "review"]
}

Bundling your MCP server

{
  "mcpServers": {
    "deploy-tools": {
      "command": "python",
      "args": ["${CLAUDE_PLUGIN_ROOT}/mcp/server.py"],
      "env": { "DEPLOY_API_URL": "https://deploy.internal.example.com" }
    }
  }
}

Secrets don't go in the plugin. Read them from the user's environment or an OAuth flow.

Subagent definitions

---
name: security-reviewer
description: Reviews a diff for security issues only. Use when
  explicitly asked for a security review, or before a release.
tools: Read, Grep, Glob, Bash
model: opus
---

You review code changes for security defects and nothing else.

Focus, in order: injection (SQL/command/template), authn/authz gaps,
secrets in code or logs, unsafe deserialization, SSRF, path traversal,
missing rate limits on unauthenticated endpoints.

For each finding output: file:line · severity (crit/high/med/low) ·
the concrete exploit path · the minimal fix.

Report "no findings in scope" rather than padding with style notes.

Hooks

{
  "hooks": {
    "PreToolUse": [{
      "matcher": "Bash",
      "hooks": [{
        "type": "command",
        "command": "${CLAUDE_PLUGIN_ROOT}/hooks/guard_bash.sh"
      }]
    }],
    "PostToolUse": [{
      "matcher": "Edit|Write",
      "hooks": [{
        "type": "command",
        "command": "${CLAUDE_PLUGIN_ROOT}/hooks/scan_secrets.sh"
      }]
    }]
  }
}

A PreToolUse hook receives the tool name and input on stdin and decides by exit code: 0 allow, 1 allow with a warning, 2 deny. This is your enforcement point — secret scanning, blocking rm -rf patterns, forbidding writes outside allowed paths, requiring a ticket reference on commits.

Marketplaces

A marketplace is a git repo with .claude-plugin/marketplace.json listing plugins. Users add the marketplace once, then install and update plugins from it.

{
  "name": "example-internal",
  "owner": { "name": "Developer Experience" },
  "plugins": [
    { "name": "platform-eng",  "source": "./plugins/platform-eng",
      "description": "Platform org skills, connectors and guardrails." },
    { "name": "data-platform", "source": "./plugins/data-platform",
      "description": "Warehouse context, SQL conventions, dbt helpers." }
  ]
}

Internal marketplace = a private git repo your org can reach. That gives you review, versioning, rollback, and a single place to see what's deployed — the same properties you'd demand of any internal platform.

Design guidance for org plugins

• One plugin per team or domain, not one giant plugin. Installing should be a statement about what work you do.
• Keep skill counts modest. Every installed skill's description competes in the classifier. 6 sharp skills beat 30 fuzzy ones.
• Separate "guardrails" from "capabilities." A mandatory security/hooks plugin everyone installs, plus optional capability plugins.
• Document the trigger phrases in the README so people know what to say.
• Own it like a service. Owner, changelog, issue tracker, deprecation policy.

Claude Code: interactive mastery

Read ~40 min · Lab ~70 min · Total ~1h 50m · Terminal + a real repo

Claude Code is the agentic coding surface: terminal, IDE, desktop app, and CI. Everything you learned about context engineering applies, plus a repo-specific toolkit.

The seven levers

There are seven ways to steer Claude Code. Knowing which to reach for is the whole skill:

Daily workflow that works

1. Plan before code. Ask for a plan; approve or correct it; then let it implement. Planning is cheap, wrong implementations aren't.
2. Small, verifiable increments. "Implement X and make make test pass" beats "implement the whole feature."
3. Let it read first. Point at files; let it grep. Don't paste.
4. Tight feedback loops. If tests are slow, give it a fast subset command in CLAUDE.md.
5. Fresh sessions at boundaries. New feature, new session.
6. Review the diff, always. You're the approver, not the audience.

Subagents in a repo

The highest-value pattern for engineering teams: a coordinator that dispatches focused agents.

Explore agent   → "find every place we construct a DB session" (read-only,
                   returns a list, doesn't dump 40 files into main context)
Plan agent      → "given these findings, design the migration" (opus)
Implement       → main session does the edits
Review agent    → independent security + correctness pass on the diff
Test agent      → runs the suite, reports failures

The review agent is the one people underuse. An agent that hasn't seen your reasoning catches things the author-agent rationalized.

Hooks worth having on day one

#!/usr/bin/env bash
# hooks/guard_bash.sh — PreToolUse matcher: Bash
input=$(cat)
cmd=$(printf '%s' "$input" | python3 -c \
  'import sys,json; print(json.load(sys.stdin).get("tool_input",{}).get("command",""))')

deny() { echo "BLOCKED: $1" >&2; exit 2; }

case "$cmd" in
  *"rm -rf /"*)              deny "destructive rm" ;;
  *"git push --force"*)      deny "force push" ;;
  *"curl "*"| sh"*)          deny "pipe-to-shell" ;;
  *"AWS_SECRET"*)            deny "secret in command" ;;
esac
exit 0

Others to consider: PostToolUse formatter/linter on every edit; secret scan before commit; a hook that appends the current ticket ID to commit messages; a hook that refuses writes outside the repo root.

Slash commands

Custom slash commands have merged into skills — a command is a prompt template invoked as /name. Ship the ones your team retypes constantly: /adr, /standup, /review, /postmortem.

Permission modes — the dial you'll touch most

Shift+Tab cycles modes mid-session (Alt+M on some Windows setups). Start a session in one with --permission-mode.

Permission rules and settings

Permissions are rules, not just modes. The rule syntax is Tool(pattern):

// .claude/settings.json  (committed — team-wide)
{
  "permissions": {
    "allow": [
      "Bash(git status)", "Bash(git diff *)", "Bash(git log *)",
      "Bash(make test)", "Read", "Grep", "Glob"
    ],
    "deny": [
      "Bash(git push --force *)",
      "Bash(rm -rf *)",
      "Read(./.env)", "Read(./secrets/**)"
    ],
    "additionalDirectories": ["../shared-lib"]
  },
  "model": "claude-sonnet-5",
  "env": { "MAKEFLAGS": "-j8" }
}

Settings resolve in layers, later overriding earlier: user (~/.claude/settings.json) → project (.claude/settings.json, committed) → local (.claude/settings.local.json, gitignored) → --settings flag. Managed policy settings sit above all of them and can't be overridden — that's your enterprise control point.

Interactive mode: the shortcuts that matter

Input prefixes

• @path/to/file — mention a file (with autocomplete) so Claude reads it.
• ! — shell mode. ! npm test runs directly and drops the output into the transcript; Claude responds to it automatically.
• # — comment lines above your prompt that Claude Code strips on save; also the memory shorthand for adding a fact.
• / — skills and commands. /help, /doctor, /context, /compact, /resume, /rename, /agents, /hooks, /mcp, /add-dir, /autocompact, /import.

Checkpointing and rewind

Claude Code checkpoints as it works. Esc Esc opens the rewind menu, which can restore code, conversation, or both to a prior point. This changes how you should work: be willing to let Claude attempt an aggressive change, because backing it out is one keystroke — not a git reset archaeology session.

Worktrees, background sessions, and parallelism

• claude -w feature-auth starts in an isolated git worktree at <repo>/.claude/worktrees/<name>. Add --tmux for panes. -w '#1234' branches from a PR.
• claude --bg "investigate the flaky test" launches a background session and returns immediately with an ID.
• Manage them from the shell: claude agents (the agent view), claude agents --json, claude logs <id>, claude attach <id>, claude stop <id>, claude respawn <id>, claude rm <id>.
• claude --bg --exec 'pytest -x' runs a plain shell command as a PTY-backed background job.

Diagnostics and recovery

• claude doctor — install and settings diagnostics without starting a session.
• claude --safe-mode — start with all customizations disabled (CLAUDE.md, skills, plugins, hooks, MCP, commands, output styles). The first thing to try when behaviour goes strange.
• claude --debug='mcp,startup' — category-filtered debug output.
• /context — see what's actually occupying the window. Run this when quality degrades.

Claude Code in CI

Headless mode makes Claude a pipeline step: auto-review every PR against your team's checklist, triage failing tests, draft release notes from merged PRs, or open a follow-up issue when a TODO ages past 90 days. Keep permissions minimal and make the output a comment, not a commit, until you trust it. Module 12 covers this in full.

The claude CLI: headless, scripting & automation loops

Read ~40 min · Labs ~90 min · Total ~2h 10m

Interactive Claude Code makes you faster. Headless Claude Code makes your systems smarter. This is the module that turns an assistant into infrastructure.

The command surface

Flags that matter for automation

System prompt flags — choosing correctly

Replace only when the agent isn't a coding assistant at all — e.g. a classification step in a pipeline no human watches. Otherwise append.

Pattern 1 — structured output instead of prose parsing

claude -p --bare \
  --output-format json \
  --json-schema '{
    "type":"object",
    "required":["risk","findings"],
    "properties":{
      "risk":{"type":"string","enum":["low","medium","high"]},
      "findings":{"type":"array","items":{
        "type":"object",
        "required":["file","line","severity","issue"],
        "properties":{
          "file":{"type":"string"},"line":{"type":"integer"},
          "severity":{"type":"string","enum":["crit","high","med","low"]},
          "issue":{"type":"string"}}}}}}' \
  --max-turns 8 --max-budget-usd 1.00 \
  --allowedTools "Read" "Grep" "Glob" "Bash(git diff *)" \
  "Review the staged diff for security issues." \
| jq -r '.risk'

Pattern 2 — the self-correcting loop

Give Claude a checkable goal and let it iterate until the check passes or the budget runs out. This is the shape behind most successful agentic automation.

#!/usr/bin/env bash
set -euo pipefail
MAX=5

for i in $(seq 1 $MAX); do
  if make test >/tmp/test.log 2>&1; then
    echo "✅ green on attempt $i"; exit 0
  fi

  echo "❌ attempt $i failed — dispatching Claude"
  claude -p \
    --permission-mode acceptEdits \
    --allowedTools "Read" "Edit" "Grep" "Glob" "Bash(make test)" \
    --max-turns 20 --max-budget-usd 2.00 \
    --append-system-prompt "Fix only the failing tests. Do not change test
      assertions to make them pass. Do not add dependencies." \
    "The test suite fails. Here is the output:
$(tail -100 /tmp/test.log)
Diagnose the root cause and fix the source. Re-run \`make test\` to verify."
done

echo "still failing after $MAX attempts — escalating"; exit 1

Note the three guardrails: a bounded loop, an external verifier (make test, not Claude's opinion), and an explicit anti-cheat instruction. Agentic loops without an external verifier drift.

Pattern 3 — streaming events into your own harness

import json, subprocess

cmd = [
    "claude", "-p", "--output-format", "stream-json", "--verbose",
    "--include-partial-messages", "--forward-subagent-text",
    "--max-turns", "25", "--max-budget-usd", "3.00",
    "--allowedTools", "Read", "Grep", "Glob",
    "Audit this service for unbounded queries.",
]

proc = subprocess.Popen(cmd, stdout=subprocess.PIPE, text=True, bufsize=1)
tool_calls, cost = [], 0.0

for line in proc.stdout:                      # newline-delimited JSON
    if not line.strip():
        continue
    ev = json.loads(line)
    kind = ev.get("type")

    if kind == "assistant":
        for block in ev["message"]["content"]:
            if block.get("type") == "tool_use":
                tool_calls.append(block["name"])
                print("→", block["name"])
    elif kind == "result":
        cost = ev.get("total_cost_usd", 0.0)
        print("done:", ev.get("subtype"), f"${cost:.4f}")

print("tools used:", tool_calls)

This is how you build dashboards, cost attribution, and trajectory evals (Module 16) on top of the CLI without touching the SDK.

Pattern 4 — multi-turn scripted conversations

# stage 1: plan, capture the session id
SID=$(uuidgen)
claude -p --session-id "$SID" --permission-mode plan \
  --output-format json \
  "Plan the migration to add tenant_id to all queries." | jq -r '.result' > plan.md

# human reviews plan.md here, or a second agent critiques it

# stage 2: resume that exact session to execute
claude -p -r "$SID" --permission-mode acceptEdits \
  --max-turns 40 --max-budget-usd 10 \
  "The plan is approved. Implement step 1 only, then stop."

--fork-session lets you branch from a resumed session without mutating the original — useful for trying two implementations from the same approved plan.

Pattern 5 — fan-out with worktrees

for svc in auth billing search; do
  claude --bg -w "bump-$svc" \
    --max-turns 30 --max-budget-usd 4 \
    "In services/$svc, upgrade the http client to v3, fix all
     call sites, and make the tests pass. Do not touch other services."
done

claude agents --json | jq -r '.[] | "\(.id) \(.status) \(.name)"'

Three isolated worktrees, three background sessions, no interference. Poll claude agents --json, collect with claude logs <id>, attach with claude attach <id> when one needs a human.

Pattern 6 — CI integration

# .github/workflows/claude-review.yml
name: Claude review
on: pull_request

jobs:
  review:
    runs-on: ubuntu-latest
    permissions: { contents: read, pull-requests: write }
    steps:
      - uses: actions/checkout@v4
        with: { fetch-depth: 0 }
      - run: npm install -g @anthropic-ai/claude-code
      - name: Review
        env:
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
        run: |
          git diff origin/${{ github.base_ref }}...HEAD > /tmp/diff.patch
          claude -p --bare \
            --settings .claude/ci-settings.json \
            --strict-mcp-config \
            --tools "Read,Grep,Glob" \
            --max-turns 12 --max-budget-usd 1.50 \
            --output-format json \
            --json-schema "$(cat .claude/review-schema.json)" \
            --append-system-prompt-file .claude/review-rules.md \
            "Review /tmp/diff.patch against our checklist." \
          | jq -r '.result' > review.json
      - run: gh pr comment ${{ github.event.number }} \
               --body-file <(jq -r '.summary' review.json)

Pattern 7 — scheduled automations

# crontab: nightly dependency-risk triage, 02:00
0 2 * * * cd /srv/repo && /usr/local/bin/claude -p --bare \
  --tools "Read,Grep,Glob,Bash" \
  --allowedTools "Bash(npm audit *)" "Bash(git log *)" \
  --max-turns 15 --max-budget-usd 1 \
  --output-format json \
  "Run npm audit. For each high/critical finding, check whether the
   vulnerable path is actually reachable from our entrypoints. Output
   only genuinely reachable issues." \
  >> /var/log/dep-triage.jsonl 2>&1

Other high-value cron jobs: flaky-test detection across last night's runs, stale-PR nudges, changelog drafting, docs drift checks (does the README still match the CLI?), and log-anomaly triage.

Setup hooks for CI

--init and --maintenance (print mode) and --init-only fire Setup hooks before the session — the right place for one-time environment preparation in a pipeline (warm caches, install deps, fetch fixtures) without baking it into your prompt.

Hooks in depth: deterministic control

Read ~35 min · Labs ~55 min · Total ~1h 30m

Hooks are where you stop hoping and start enforcing. Every other mechanism asks the model to behave; hooks make behaviour structurally impossible to violate.

The three levels of nesting

{
  "hooks": {
    "PreToolUse": [                      // 1. the EVENT
      {
        "matcher": "Bash",               // 2. the MATCHER GROUP
        "hooks": [                       // 3. the HANDLERS
          { "type": "command",
            "command": "./.claude/hooks/guard.sh",
            "if": "Bash(git *)",
            "timeout": 10,
            "statusMessage": "Checking git safety…" }
        ]
      }
    ]
  }
}

Where hooks can live

Hooks merge across levels rather than replacing each other, and they also fire inside subagents (the input carries agent_id and agent_type). Enterprise admins can set allowManagedHooksOnly to block user, project, and plugin hooks entirely — the governance lever from Module 17.

The event catalogue

Far more than the usual four. Grouped by what they're actually for:

Session lifecycle

Prompt and turn

Tools and permissions

Agents, tasks, and teams

Environment and context

Five handler types — not just shell scripts

All matching handlers run in parallel. Common fields on every type: timeout, statusMessage, once (skill frontmatter only), and if.

Command handlers also support async: true (runs in the background, doesn't block) and asyncRewake: true (background, but wakes Claude on exit code 2 and shows the output as a system reminder — how you surface a long-running background failure).

Two ways to signal a decision

A. Exit codes (simple)

0  → success, stdout added as context
1  → non-blocking error, execution continues
2  → BLOCKING error, stderr goes to Claude

What exit 2 blocks depends on the event: PreToolUse blocks the call · UserPromptSubmit erases the prompt · Stop/SubagentStop refuses to end the turn · PreCompact blocks compaction · TaskCompleted refuses the completion · PostToolUse can't block (the tool already ran) but its stderr reaches Claude.

B. JSON on stdout (precise)

{ "continue": false, "stopReason": "Build failed, fix errors before continuing" }

Universal fields: continue (false stops Claude entirely, overriding event-specific decisions), stopReason, suppressOutput, systemMessage, and terminalSequence (allowlisted OSC escapes for desktop notifications and window titles — hooks have no /dev/tty). Event-specific control goes in hookSpecificOutput with a hookEventName.

Recipes worth stealing

1. Block reads of secrets

#!/usr/bin/env bash
# PreToolUse, matcher: "Read|Edit|Write"
p=$(jq -r '.tool_input.file_path // ""')
case "$p" in
  *.env|*.env.*|*/secrets/*|*id_rsa*|*.pem)
    echo "BLOCKED: $p is a secret-bearing path" >&2; exit 2 ;;
esac
exit 0

2. Auto-format after every edit

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

3. Don't let the turn end on a red build

#!/usr/bin/env bash
# Stop hook — exit 2 hands control back to Claude with a reason
if ! make test >/tmp/t.log 2>&1; then
  echo "Tests are failing. Fix them before finishing:" >&2
  tail -40 /tmp/t.log >&2
  exit 2
fi
exit 0

This is the deterministic version of "verify your work" — and unlike an instruction, the model can't decide to skip it.

4. Inject fresh context on every prompt

#!/usr/bin/env bash
# UserPromptSubmit — stdout on exit 0 becomes context
echo "Current branch: $(git branch --show-current)"
echo "Uncommitted files: $(git status --porcelain | wc -l)"
echo "Open incidents: $(curl -s "$STATUS_API/count")"
exit 0

5. Model-judged commit messages (prompt hook)

{ "PreToolUse": [{ "matcher": "Bash",
  "hooks": [{ "type": "prompt", "if": "Bash(git commit *)",
    "prompt": "Does this git command have a commit message that explains WHY, not just what? Answer with a decision. Input: $ARGUMENTS",
    "model": "haiku" }] }] }

6. Central audit sink (http hook)

{ "PostToolUse": [{ "hooks": [{ "type": "http",
    "url": "https://audit.internal.example.com/claude-events",
    "headers": { "Authorization": "Bearer ${AUDIT_TOKEN}" },
    "allowedEnvVars": ["AUDIT_TOKEN"] }] }] }

HTTP hooks signal through the response: 2xx + JSON body uses the same schema as command hooks; non-2xx or a timeout is a non-blocking error. They can't block via status code alone — return 2xx with a decision in the body. Note the org-level allowlists allowedHttpHookUrls and httpHookAllowedEnvVars.

Managing hooks

• /hooks — inspect and manage hooks in-session.
• claude -p --output-format stream-json --verbose --include-hook-events — see every hook firing in the event stream. Essential for debugging.
• disableAllHooks — kill switch (can't disable managed hooks from outside managed settings).
• claude --safe-mode — start with hooks and everything else off.

settings.json & the configuration system

Read ~35 min · Lab ~50 min · Total ~1h 25m

CLAUDE.md shapes behaviour. Settings enforce it. This is the layer where an engineering leader actually gets control — and the layer most people never open.

The five scopes

Precedence runs managed > command line > local > project > user. Managed can't be overridden by anything below it. Scalars override; permission rules merge across scopes rather than replacing each other — remember that, it surprises people.

File-based managed settings also support a managed-settings.d/ drop-in directory (systemd convention): the base file merges first, then *.json fragments alphabetically. Later files win on scalars, arrays concatenate and de-duplicate, objects deep-merge. This lets security and platform teams ship independent policy without editing one shared file.

A project settings file worth committing

// .claude/settings.json
{
  "model": "claude-sonnet-5",
  "permissions": {
    "allow": [
      "Bash(git status)", "Bash(git diff *)", "Bash(git log *)",
      "Bash(make test)", "Bash(make lint)",
      "Read", "Grep", "Glob"
    ],
    "ask":  [ "Bash(git push *)" ],
    "deny": [
      "Bash(rm -rf *)", "Bash(git push --force *)",
      "Read(./.env)", "Read(./.env.*)", "Read(./secrets/**)"
    ],
    "additionalDirectories": ["../shared-lib"],
    "defaultMode": "acceptEdits"
  },
  "env": { "MAKEFLAGS": "-j8", "CI": "0" },
  "hooks": { "PreToolUse": [ /* Module 13 */ ] },
  "autoCompactWindow": "500k",
  "claudeMdExcludes": ["**/monorepo/other-team/CLAUDE.md"],
  "includeGitInstructions": true,
  "cleanupPeriodDays": 30
}

Settings worth knowing by name

Behaviour & models

Context & memory

Safety & guardrails

Enterprise levers (managed settings only)

The env block and environment variables

{ "env": {
    "ANTHROPIC_MODEL": "claude-sonnet-5",
    "MAX_THINKING_TOKENS": "8000",
    "ENABLE_PROMPT_CACHING_1H": "1",
    "CLAUDE_CODE_AUTO_COMPACT_WINDOW": "500000",
    "BASH_DEFAULT_TIMEOUT_MS": "120000"
} }

Applied to every session and to subprocesses Claude Code spawns. Set a variable to "" to override a shell export. Environment variables generally take precedence over the equivalent settings key — useful in CI, dangerous if a developer's shell profile is quietly overriding your project policy.

Debugging configuration

Claude Agent SDK in Python

Read ~45 min · Labs ~90 min · Total ~2h 15m · The deepest build in the course

The Agent SDK is the harness behind Claude Code, exposed as a library. You get the agent loop, the file/bash/search tools, permissions, subagents, hooks, and MCP integration — so you build the agent, not the plumbing.

pip install claude-agent-sdk
# requires the Claude Code CLI on PATH:
npm install -g @anthropic-ai/claude-code

Level 1 — one-shot: query()

import anyio
from claude_agent_sdk import query, ClaudeAgentOptions

async def main():
    options = ClaudeAgentOptions(
        system_prompt="You are a release engineer. Be terse and precise.",
        allowed_tools=["Read", "Grep", "Glob"],
        cwd="/path/to/repo",
        permission_mode="acceptEdits",
        model="claude-sonnet-5",
    )
    async for message in query(
        prompt="Summarize what changed in the last 20 commits, grouped by subsystem.",
        options=options,
    ):
        print(message)

anyio.run(main)

query() is stateless and streaming — perfect for scripts, CI steps, and batch jobs.

Level 2 — conversational + custom tools + hooks: ClaudeSDKClient

ClaudeSDKClient keeps a session alive and, importantly, is the only way to use custom in-process tools and hooks.

import anyio
from claude_agent_sdk import (
    ClaudeSDKClient, ClaudeAgentOptions, tool, create_sdk_mcp_server
)

@tool("cost_estimate", "Estimate monthly cost for a service at a given RPS. "
      "Use when the user asks what something will cost to run.",
      {"service": str, "rps": int})
async def cost_estimate(args):
    monthly = args["rps"] * 2_592_000 * 0.0000004
    return {"content": [{
        "type": "text",
        "text": f"{args['service']}: ~${monthly:,.2f}/month at {args['rps']} rps",
    }]}

tools_server = create_sdk_mcp_server(
    name="finops", version="1.0.0", tools=[cost_estimate]
)

async def main():
    options = ClaudeAgentOptions(
        mcp_servers={"finops": tools_server},
        allowed_tools=["Read", "Grep", "mcp__finops__cost_estimate"],
        system_prompt="You are a platform cost analyst.",
    )
    async with ClaudeSDKClient(options=options) as client:
        await client.query("What would the search service cost at 8000 rps?")
        async for msg in client.receive_response():
            print(msg)

        # follow-up in the same session — context is retained
        await client.query("And if we cut it to 3000?")
        async for msg in client.receive_response():
            print(msg)

anyio.run(main)

Level 3 — hooks: deterministic control of the loop

from claude_agent_sdk import ClaudeSDKClient, ClaudeAgentOptions, HookMatcher

BLOCKED = ("rm -rf", "git push --force", "DROP TABLE")

async def guard(input_data, tool_use_id, context):
    cmd = input_data.get("tool_input", {}).get("command", "")
    if any(b in cmd for b in BLOCKED):
        return {
            "hookSpecificOutput": {
                "hookEventName": "PreToolUse",
                "permissionDecision": "deny",
                "permissionDecisionReason": f"Blocked by policy: {cmd!r}",
            }
        }
    return {}

async def audit(input_data, tool_use_id, context):
    log.info("tool_call", extra={"tool": input_data.get("tool_name"),
                                 "args": input_data.get("tool_input")})
    return {}

options = ClaudeAgentOptions(
    allowed_tools=["Read", "Write", "Bash"],
    hooks={
        "PreToolUse":  [HookMatcher(matcher="Bash", hooks=[guard]),
                        HookMatcher(hooks=[audit])],
        "PostToolUse": [HookMatcher(matcher="Write", hooks=[audit])],
    },
)

Hooks require ClaudeSDKClient (not query()), and the Python SDK doesn't support SessionStart, SessionEnd, or Notification hooks. Use them for policy enforcement, audit logging, redaction, and injecting fresh context before a tool runs.

Level 4 — subagents and orchestration

options = ClaudeAgentOptions(
    agents={
        "researcher": {
            "description": "Gathers facts from the codebase and docs. Read-only.",
            "prompt": ("You gather evidence. Cite file:line for every claim. "
                       "Never speculate; say 'not found' instead."),
            "tools": ["Read", "Grep", "Glob", "WebSearch"],
            "model": "haiku",
        },
        "auditor": {
            "description": "Independently verifies another agent's conclusions.",
            "prompt": ("You are given a conclusion and the evidence. Attempt to "
                       "falsify it. Report every claim you could not verify."),
            "tools": ["Read", "Grep"],
            "model": "opus",
        },
    },
    allowed_tools=["Task", "Read", "Grep"],
)

Model routing per subagent is where cost and quality get decided: Haiku for fan-out gathering, Sonnet for the main loop, Opus for the calls that are expensive to get wrong.

Permissions

You can also supply a can_use_tool callback for programmatic, per-call decisions — e.g. allow writes only under ./out/, or require a human approval for anything touching production.

Production concerns

• Streaming — consume messages incrementally; don't block on the whole run.
• Session resumption — persist session IDs so long tasks survive restarts.
• Timeouts and turn caps — always bound max_turns. An unbounded agent loop is an unbounded bill.
• Structured output — ask for JSON to a file and parse the file, rather than parsing prose.
• Observability — log every tool call, token count, and turn. Hooks are the natural place.
• Idempotency — assume any run may be retried. Design tools accordingly.

The Claude API & platform

Read ~35 min · Labs ~55 min · Total ~1h 30m · Python

The Agent SDK gives you an agent. The API gives you the primitives — and when you're building product, you often want the primitives. This module is the layer beneath everything else in the course.

Messages API — the base

from anthropic import Anthropic
client = Anthropic()

resp = client.messages.create(
    model="claude-sonnet-5",
    max_tokens=2000,
    system="You are a release engineer. Be terse.",
    messages=[{"role": "user", "content": "Summarize this changelog: ..."}],
)
print(resp.content[0].text)
print(resp.usage.input_tokens, resp.usage.output_tokens)

Everything else is a variation: streaming (client.messages.stream), extended thinking, vision (image blocks), and tool use.

Tool use — the manual loop

tools = [{
    "name": "get_deploy_status",
    "description": ("Get current deploy status for a service. Use when asked "
                    "whether a service is healthy or what version is live."),
    "input_schema": {
        "type": "object",
        "properties": {
            "service": {"type": "string", "description": "Service slug"},
            "env": {"type": "string", "enum": ["prod", "staging", "dev"]},
        },
        "required": ["service"],
    },
}]

messages = [{"role": "user", "content": "Is payments-gateway healthy?"}]

while True:
    resp = client.messages.create(
        model="claude-sonnet-5", max_tokens=2000,
        tools=tools, messages=messages,
    )
    messages.append({"role": "assistant", "content": resp.content})

    if resp.stop_reason != "tool_use":
        break

    results = []
    for block in resp.content:
        if block.type == "tool_use":
            out = dispatch(block.name, block.input)      # your code
            results.append({
                "type": "tool_result",
                "tool_use_id": block.id,
                "content": json.dumps(out),
            })
    messages.append({"role": "user", "content": results})

print(resp.content[-1].text)

Tool Runner (client.beta.messages.tool_runner) runs this loop over your own Python functions so you don't hand-roll it. Managed Agents go further: server-hosted agents with a managed sandbox, when you'd rather not operate the harness at all.

Choosing your altitude

Go one level lower than the default only when you have a concrete reason. Most teams over-build here.

Prompt caching — the biggest cost lever after routing

resp = client.messages.create(
    model="claude-sonnet-5",
    max_tokens=1500,
    system=[
        {"type": "text", "text": "You are a compliance analyst."},
        {"type": "text",
         "text": POLICY_HANDBOOK,                 # 60k tokens, stable
         "cache_control": {"type": "ephemeral"}},  # ← cache breakpoint
    ],
    messages=[{"role": "user", "content": question}],
)

Rules that matter: put stable content first (system prompt, schemas, long documents), volatile content last. Cache hits are dramatically cheaper than fresh input tokens, and cache writes cost slightly more than normal input — so caching pays off from roughly the second call onward. In Claude Code, --exclude-dynamic-system-prompt-sections exists precisely to keep the cacheable prefix identical across machines.

Batch, files, and long context

• Message Batches — submit many requests for asynchronous processing at a substantial discount. Use for backfills, bulk classification, and eval suites where latency doesn't matter.
• Files API — upload once, reference across many requests instead of re-sending bytes.
• Citations — have the model ground claims in supplied documents with references you can verify. Pairs well with the "require citations" pattern from Module 16.
• Structured outputs / JSON schema — same discipline as --json-schema: declare the shape, don't parse prose.

Model routing, concretely

Also relevant: fallback chains (--fallback-model sonnet,haiku in the CLI, retry logic in your own code) so an overloaded model degrades rather than fails.

Production hygiene

• Retries with jitter on 429/529. Respect retry-after.
• Streaming for anything a human waits on.
• Token accounting per request, attributed to a feature or team. You cannot manage spend you can't attribute.
• Idempotency keys on anything that triggers a side effect.
• Never put untrusted content in the system prompt. User and tool content belongs in messages, clearly demarcated.
• Deployment options — the API directly, or through Amazon Bedrock, Google Cloud's agent platform, or Microsoft Foundry when procurement or data residency requires it.

Tokens, context, performance & limits

Read ~40 min · Lab ~60 min · Total ~1h 40m

This is the module that separates people who use Claude from people who can operate it. Everything here is measurable, and almost all of it is under your control.

Where your context actually goes

Before you type a single character, the window already contains: the system prompt, CLAUDE.md and rules, auto memory, MCP tool names, skill descriptions, and any output style or --append-system-prompt text. Then as Claude works: every file read, every tool result, every path-scoped rule that matched, every hook output.

Compaction

When the conversation approaches the limit, Claude Code summarizes older history to free space. A full window doesn't end your session — but compaction is itself a large, expensive request, because it reads everything it summarizes.

Controlling it

Accepted window forms: a plain count (200000), a suffix (500k, 1M), or a bare 100–1000 meaning thousands. Range 100K–1M, capped at the model's window. Fable 5, Sonnet 5, Opus 4.6+ and Sonnet 4.6 support a 1M-token context window.

Why usage climbs in a long session

A session open for hours can consume far more than your activity suggests. The causes, in rough order of impact:

Background usage is small but nonzero — conversation summarization for --resume and status commands typically run under $0.04 per session.

Measuring: /usage

Total cost:            $0.55
Total duration (API):  6m 20s
Total duration (wall): 6h 33m 10s
Usage by model:
   claude-sonnet-…:  1.2k input, 5.3k output, 940.0k cache read, 50.0k cache write

Note the shape of a real session: 940k cache reads against 1.2k fresh input. That ratio is the whole game — caching is doing almost all the work, and a cache miss is what makes a cheap turn suddenly expensive.

• On paid plans, /usage also shows attribution — recent usage broken down by skill, subagent, plugin and individual MCP server — and behavior flags for anything accounting for ≥10% of usage, like long context or cache misses. Press d/w to toggle 24 hours vs 7 days.
• The dollar figure is computed locally at list rates, so it won't match a contracted bill. For authoritative numbers use the Console usage page.
• Totals reset on /clear.
• Configure your status line to show context usage continuously so you never have to ask.

The optimization playbook, ordered by impact

1. Clear between unrelated tasks. Free, and the single biggest lever on a long day.
2. Match the model to the job. Sonnet handles most coding; reserve Opus for architecture and multi-step reasoning; model: haiku for simple subagents. Opus-left-as-default is one of the two classic causes of surprise spend.
3. Move workflow instructions out of CLAUDE.md into skills, and detail into path-scoped rules. Standing context is paid on every turn.
4. Delegate verbose operations to subagents — test runs, log processing, doc fetching. The output stays in their window; only a summary returns.
5. Cut MCP overhead. Tool definitions are deferred by default so only names load until used, but names still cost. Disable unused servers via /mcp. Prefer CLI tools (gh, aws, gcloud) where they exist — they add no per-tool listing at all.
6. Tune extended thinking. Thinking tokens bill as output and the default budget can be tens of thousands per request. Lower with /effort, disable in /config, or set MAX_THINKING_TOKENS=8000 on fixed-budget models. Adaptive-reasoning models ignore nonzero budgets — use effort levels there.
7. Preprocess with hooks. The highest-craft move in this list.
8. Write specific prompts. "Improve this codebase" triggers broad scanning; "add input validation to the login function in auth.ts" doesn't.
9. Use plan mode for complex tasks. Preventing one wrong implementation pays for a lot of planning.
10. Install code intelligence plugins for typed languages — "go to definition" replaces a grep plus several speculative file reads.

The hook that pays for itself

Instead of Claude reading a 10,000-line log to find errors, a PreToolUse hook rewrites the command so only failures come back — tens of thousands of tokens down to hundreds:

#!/bin/bash
input=$(cat)
cmd=$(echo "$input" | jq -r '.tool_input.command')

if [[ "$cmd" =~ ^(npm test|pytest|go test) ]]; then
  filtered="$cmd 2>&1 | grep -A 5 -E '(FAIL|ERROR|error:)' | head -100"
  echo "{\"hookSpecificOutput\":{\"hookEventName\":\"PreToolUse\",\
\"permissionDecision\":\"allow\",\"updatedInput\":{\"command\":\"$filtered\"}}}"
else
  echo "{}"
fi

Verify with /hooks, then claude --debug and run a test command — the log shows modified tool input keys: [command] when the rewrite fires.

Limits: which ceiling did you hit?

Cost at organization scale

• Published enterprise averages: roughly $13 per developer per active day and $150–250 per developer per month, with 90% of users under $30 per active day. Pilot small, measure, then extrapolate — don't budget from a vendor page.
• Budget more for a coding seat than a chat seat. Each Claude Code turn carries file contents, tool calls and multi-step reasoning; one debugging session can exceed a day of chat.
• Agent teams use roughly 7× the tokens of a standard session when teammates run in plan mode — each is a separate instance with its own window. Keep teams small, use Sonnet for teammates, keep spawn prompts tight, shut them down when done.

Where to see and cap spend

OpenTelemetry export works on every setup and is the only option that streams per-user token and cost metrics into your own observability stack in near real time. If you're serious about attribution, start there.

Rate limit sizing (per user, API organizations)

Per-user allocation drops as the org grows because concurrency falls. Limits apply at the organization level, so individuals can burst above their share. Budget extra for live training sessions, where concurrency spikes hard. Also consider a workspace rate limit on the auto-created "Claude Code" workspace so it can't starve your production workloads.

Agent architecture patterns & evaluation

Read ~30 min · Labs ~50 min · Total ~1h 20m

Patterns, and when each is right

1. Single agent with tools

One loop, a handful of tools. Default choice. Most "we need a multi-agent system" instincts are premature. Reach for more structure only when this demonstrably fails.

Real example: the PR reviewer. Read the diff, grep for related call sites, check the test file, report findings. One agent, four tools, done.

2. Router

A cheap classifier (Haiku) picks a specialist path. Good when you have distinct task families with different tools or system prompts, and cost matters.

Real example: an inbound support triage agent. Haiku classifies each ticket as billing / bug / how-to, then routes to a specialist prompt with its own tools. 90% of the volume never touches an expensive model.

3. Orchestrator + workers (fan-out/fan-in)

A coordinator decomposes, dispatches N workers in parallel, synthesizes. Good for genuinely independent subtasks — research across sources, per-file analysis, multi-vendor comparison. Cost scales with N; make sure the parallelism is real.

Real example: the dependency-upgrade sweep. One worker per service, each in its own git worktree, each bumping the library and fixing its own call sites. Genuinely independent, so N× the workers really is N× the throughput.

4. Evaluator–optimizer

Generator produces, a separate critic scores against explicit criteria, loop until pass or budget exhausted. Excellent where quality is checkable and iteration is cheap: code that must pass tests, documents that must satisfy a rubric.

Real example: the flaky-test fixer. Generate a fix, run the suite 20 times, loop while it still flakes. The critic here isn't a model at all — it's the test runner, which is exactly why it works.

5. Pipeline / prompt chaining

Fixed stages with validation between them. Use when the steps are known and stable — you get determinism and debuggability that an open loop can't give you.

Real example: release-note generation. Fetch merged PRs → classify each → group by area → draft → validate against a schema. Five known steps; an autonomous agent here would only add variance.

Context management at scale

• Compaction — summarize completed phases; keep the summary, drop the transcript.
• Externalize state — write findings to files, not to context. The filesystem is your long-term memory and it's free.
• Structured handoffs — subagents should return a defined shape (JSON), not prose. You control what re-enters the parent's context.
• Prompt caching — put stable prefixes (system prompt, schemas, long reference docs) first so they're cacheable across calls.
• Tool result trimming — cap tool output size at the tool, not in the prompt.

Evaluation, properly

You can't manage what you don't measure, and agent quality drifts with every prompt, skill, model, and tool change. Build the eval before you scale the agent.

Four layers

1. Unit — tools and scripts, tested as ordinary code.
2. Selection — given a prompt, does it choose the right tool/skill/subagent? Cheap, catches most regressions.
3. Trajectory — did it take a sane path? Turn count, tool-call count, redundant calls, dead ends.
4. Outcome — is the final artifact correct? Binary criteria, graded programmatically where possible, by an LLM judge with a rubric where not.

Metrics to track per release

Failure modes to design against

Security, governance, and cost

Read ~30 min · Labs ~40 min · Total ~1h 10m

Threat model for agentic systems

Governance you can actually operate

• Tiered autonomy. Tier 0: suggests only. Tier 1: acts in a sandbox. Tier 2: acts in prod with human approval. Tier 3: acts autonomously with audit. Promote workflows between tiers on evidence, not enthusiasm.
• An internal marketplace as the control point. Everything the org uses ships through it; that gives you review, versioning, and an inventory.
• A mandatory guardrail plugin everyone installs: hooks for secret scanning, dangerous-command blocking, and audit logging.
• Audit trail. Log tool calls, args, and outcomes centrally. If you can't answer "what did the agent do last Tuesday," you're not ready for tier 3.
• Data classification. Be explicit about which connectors may touch which classes of data, and enforce it via which plugins a group can install.
• Human accountability stays human. Someone signs off. "The agent did it" is not a control.

Cost engineering

• Model routing is the biggest lever. Haiku for fan-out and extraction, Sonnet for the main loop, Opus reserved for high-stakes reasoning. A well-routed system is often 5–10× cheaper than an all-Opus one with no measurable quality loss.
• Prompt caching for stable prefixes — large system prompts, schemas, reference docs.
• Context discipline — retrieval over stuffing; compaction between phases; trimmed tool results.
• Bound the loop — turn caps and timeouts.
• Measure per-task unit cost, not monthly spend. "$0.34 per PR reviewed" is a number you can reason about and defend; "$9k/month" isn't.

Measuring value honestly

Resist "hours saved" — it's unfalsifiable and everyone knows it. Better instruments:

• Cycle time on a defined workflow, before and after.
• Escaped-defect rate for reviews the agent participated in.
• Throughput of a queue that was previously the bottleneck.
• Adoption depth — % of the team using it weekly for a defined workflow, not % who tried it.
• Human-intervention rate trending down over releases.

Director's playbook: rollout & org design

Read ~30 min · Lab ~45 min · Total ~1h 15m · Strategy, not syntax

Everything above makes you effective. This module is about making an organization effective, which is a different problem with different failure modes.

The maturity curve

The three artifacts that unlock stage 2→3

1. An internal marketplace repo. One git repo, plugins per domain, PR review. This is the single highest-leverage thing you can fund. It gives you distribution, versioning, rollback, and inventory in one move.
2. A guardrail plugin everyone installs. Secret scanning, dangerous-command blocking, audit logging. Non-optional. It's what lets you say yes to everything else.
3. An MCP layer over your top 5 internal systems. Deploy status, service catalog, incident history, ticket system, metrics. Read-only first. This is where "Claude knows about our company" actually comes from — not from a bigger context window.

Where to start: picking the first three workflows

Score candidates on four axes; pick the highest total, not the flashiest:

Strong first candidates for a software org: PR review against a checklist · incident postmortems · ADR drafting · on-call handoff summaries · dependency-upgrade triage · release notes · test-gap analysis. Weak first candidates: anything customer-facing, anything unverifiable, anything requiring write access to prod.

Roles you need

• Skill/plugin owner per domain (part-time, embedded). Owns descriptions, evals, changelog.
• Platform owner for the marketplace, MCP layer, and guardrails. This should be a real, staffed responsibility, not a volunteer.
• An evaluation habit — whoever owns a skill owns its eval suite. No eval, no promotion to org-wide.

Enablement that works

• Teach mechanisms, not prompts. A person who understands skill-vs-hook-vs-MCP will out-perform one with a prompt library forever.
• Ship the workflow, then teach it. "Here's /postmortem, it produces our exact format" beats a prompting workshop.
• Make trigger phrases discoverable. READMEs that say what to type.
• Office hours > documentation in the first 90 days.
• Celebrate a codified workflow, not a clever prompt. You're shaping what people invest in.

Anti-patterns to kill early

Talking to your leadership

Frame it as platform investment with unit economics, not as a productivity miracle:

• "We codified our review checklist as an agent. Escaped defects on participating PRs are down X%. Unit cost is $Y per PR."
• "We built an MCP layer over deploy + incident data. Time to answer 'what changed' went from 20 minutes to 40 seconds."
• "Autonomy is tiered. Nothing writes to production without a human approval. Here's the audit trail."

Capstone, 30/60/90, and reference

Capstone ~6–10 hours · Reference: keep open

Capstone: ship an end-to-end internal capability

Build one thing that exercises every layer. Suggested: an engineering intelligence capability for your org.

1. MCP server (Module 9) — read-only tools over your deploy/incident/service-catalog data. At least 4 tools, 1 resource, 1 prompt. Docstrings written as the sole documentation.
2. Skills (Modules 7–8) — three: incident-postmortem, service-health-brief, adr. Each with a validating script and a hard gate.
3. Subagent (Modules 11 & 15) — an independent auditor that falsifies claims in generated briefs.
4. Hooks (Module 13) — secret scan, dangerous-command block, tool-call audit log.
5. Plugin + marketplace (Module 10) — package all of it; install from a clean profile.
6. Scheduled task (Module 4) — Monday 07:00 service health brief saved to the team folder.
7. Live artifact (Module 4) — a page the team opens to see current state.
8. Eval suite (Modules 8 & 18) — trigger accuracy + outcome criteria, run 3× per case, results in a report.
9. Threat model + unit cost (Modules 17 & 19) — one page each.
10. Rollout plan (Module 20) — owners, autonomy tier, metrics.

Your 30/60/90

Days 1–30 — become the proof

• Complete Modules 0–8. Ship two personal skills you use daily.
• Write CLAUDE.md for your main repo. Build your memory layer.
• Audit and prune connectors.
• Pick the three org workflows (Lab 15) and socialize the list.

Days 31–60 — build the platform floor

• Complete Modules 9–14. Ship the first read-only MCP server over one internal system.
• Stand up the internal marketplace with one plugin.
• Ship the guardrail plugin; make it the default install.
• Codify workflow #1 as a skill with an eval suite. Get 3–5 people using it.

Days 61–90 — measure and scale

• Complete Modules 15–20. Put evals in CI for load-bearing skills.
• Ship workflows #2 and #3; name owners for each domain plugin.
• Define autonomy tiers; promote one workflow with evidence.
• Report three real metrics upward, with unit economics.

Reference — the decision tree, condensed

Always true here?              → CLAUDE.md
Recurring task procedure?      → Skill
Needs external data/actions?   → MCP server
Needs isolation/parallelism?   → Subagent
Must happen 100% of the time?  → Hook
Ship to a team as one unit?    → Plugin + marketplace
Runs on a cadence?             → Scheduled task
Re-checked over time?          → Live artifact
Embedded in your own product?  → Agent SDK

Reference — prompt skeletons

Agentic task

Goal: <outcome>
Inputs: <where the material is>
Constraints: <audience, format, length, exclusions>
Deliverable: <exact file(s) and path>
Verify: <concrete self-check>, and report what you verified.

Technical decision

<context>scale, stack, constraints</context>
<task>the decision to make</task>
<constraints>hard requirements</constraints>
<output_format>options table, recommendation, consequences, what would
change my mind</output_format>

Before recommending, list the 2 strongest arguments against your choice.

Review

Review <target> for: (a) ..., (b) ..., (c) ...
For each finding: location · severity · concrete fix.
Ignore <out of scope>. Report "no findings in scope" rather than padding.

Reference — skill frontmatter template

---
name: kebab-case-name
description: <what it does>. Use when <trigger 1>, <trigger 2>,
  <trigger 3>, or when the user says <literal phrasing>.
  Do NOT use for <negative boundary 1> or <negative boundary 2>.
---

Reference — official docs

• docs.claude.com — product and API documentation
• support.claude.com — Claude apps & Cowork help center
• code.claude.com/docs — Claude Code, plugins, marketplaces
• Agent SDK overview
• Prompt engineering guide
• modelcontextprotocol.io — MCP spec
• claude-agent-sdk-python
• anthropics/skills — open-source reference skills
• claude-plugins-official
• Steering Claude Code: CLAUDE.md, skills, hooks, subagents

Product surfaces evolve quickly. When a detail here disagrees with the official docs, the docs win — and ask Claude to search them for you.

Final knowledge check

Final certification exam

30 questions drawn from every module · 85% to pass · unlimited retakes with fresh questions

This is the end-to-end check. Questions are drawn at random across all twenty-two modules and the options are reshuffled every attempt, so passing means you actually hold the material rather than having memorised an ordering.