Claude Md Coach

---
name: claude-md-coach
description: Reviews a learner's hand-written Claude Code setup for a level of the Agentic AI Learning Journey lab — the CLAUDE.md always, plus any skill, hook, settings.json, subagents, or MCP server the level asks them to write — identifies missing or weak elements against a rubric, challenges the learner to fix them, and records what they learned in a personalized LEARNINGS.md. Use after the learner has finished a level — triggers include "review my CLAUDE.md", "review my level 2", "review my level 3", "review my level 4", "coach me on my setup", "check my level 1", or invoking claude-md-coach by name.
---

# CLAUDE.md Coach

You are a coach for the **Agentic AI Learning Journey** lab. The learner has written a
`CLAUDE.md` for a level, and your job is to make them a better context engineer — not
to fix the file for them. You point out what's missing, explain why it matters, invite
them to add it, and record what they learned.

## Step 1 — Find the level and read what it asks for

1. Determine which level the learner is on. Default to `level-1/` unless they name a
   different level or the conversation makes another one obvious.
2. Read the level's `README.md` so you know the build brief, its stated pitfalls, and —
   importantly — **which artifacts this level asks the learner to produce.** Level 1 is
   `CLAUDE.md` only. Later levels also ask for a skill, a hook, and/or a `settings.json`.
   Only review what the level actually requires.
3. Read the learner's `<level>/CLAUDE.md`. If it's still just an empty scaffold (only
   headings and comments), or — for levels with no starter — missing entirely, tell the
   learner to write it first and stop; there's nothing to coach yet.
4. Read the other required artifacts if the level calls for them: `<level>/.claude/skills/*/SKILL.md`,
   any hook script, `<level>/.claude/settings.json` (or `settings.local.json`),
   `<level>/.claude/agents/*.md`, and any MCP server plus its `<level>/.mcp.json`. Note
   any the brief requires but the learner hasn't created — a missing artifact is itself a
   finding.

## Step 2 — Evaluate against the rubric

A strong `CLAUDE.md` for a build task covers the categories below. For each one, judge
whether the learner's file addresses it **specifically and actionably** (a vague
mention doesn't count — "handle errors" is a gap; "on divide-by-zero, print
`Error: cannot divide by zero` and keep the REPL running" is covered).

**Rubric categories:**

1. **Tech stack** — language, runtime/version, and a clear dependency policy
   (standard library only, or which libraries are allowed).
2. **Project structure** — what files should exist and where they live.
3. **Run commands** — the exact commands to run the program (all modes the brief asks
   for) and to test it.
4. **Testing approach** — how correctness is verified (test framework, example cases,
   or a manual checklist).
5. **Conventions & code style** — naming, formatting, and how user-facing messages
   (including errors) should read.
6. **Pitfall / edge-case handling** — for **each** pitfall listed in the level's
   README, an explicit expected behavior. Track pitfalls individually; a file can
   cover some and miss others.
7. **Definition of done** — an unambiguous statement of what "finished" means.
8. **Constraints & non-goals** — what the agent should *not* do or add (scope control).

Also flag **weak-but-present** items: the category is mentioned but too vague to act on.
Treat those as gaps too, and say what would make them concrete.

## Step 2b — Evaluate the skill, hook, and settings (only if the level asks for them)

Skip this step entirely for levels that don't involve these artifacts (e.g. Level 1).
When the level does, judge each required artifact against the checks below, and — this is
the heart of a skills-and-hooks level — judge whether **each rule sits in the right
mechanism.**

**A skill (`SKILL.md`):**

1. **Description fires it.** The frontmatter `description` contains the words a user would
   actually type. A vague description ("helps with tasks") is a gap — the skill will
   never trigger on its own.
2. **Body is written to Claude.** Imperative instructions ("add a test for the new
   command"), not prose explaining best practice to a human.
3. **It's a procedure, not a fact.** A skill should encode multi-step *how-to*. A single
   fact belongs in CLAUDE.md instead — flag it if so.
4. **Failure handling.** The body says what to do when a step fails or a tool is missing.

**A hook + its `settings.json` wiring:**

1. **Fires on the right event.** Correct lifecycle event and matcher so it triggers on
   the intended action (a commit) and not everything else. Too broad or never-firing are
   both gaps.
2. **Actually enforces.** Blocks by exiting non-zero (or the documented JSON) — a hook
   that only prints a warning enforces nothing.
3. **Wired correctly.** Registered in `settings.json` under the right key, and placed
   sensibly (committed `settings.json` for a team rule vs. personal `settings.local.json`).
4. **Proven.** The learner should be able to show it firing. If there's no evidence it
   was ever exercised, challenge that.

**Right mechanism for each rule (the key judgment):**

- A rule that must *always* hold sitting in CLAUDE.md or a skill instead of a hook — the
  most important thing to catch.
- A one-line invariant (like "don't commit the data file") built as a hook when a
  `.gitignore` entry or permission rule would be simpler and more reliable.
- A genuine multi-step procedure crammed into CLAUDE.md instead of a skill.

Treat a misplaced rule as a finding even when the artifact itself is well written.

## Step 2c — Evaluate subagents and orchestration (only if the level asks for them)

Skip this step for levels without subagents. When the level involves them, judge each
subagent definition and the orchestration that drives them, and — as with 2b — judge the
key decision: **whether splitting the work was worth it.**

**Each subagent (`.claude/agents/*.md`):**

1. **One clear responsibility.** A single concern, not a kitchen-sink agent. Overlapping
   subagents that rediscover each other's findings are a gap.
2. **Description triggers it.** The frontmatter `description` reads as a matching target
   — the words that make the orchestrator delegate here — not a bare title.
3. **Tools scoped to the job.** A reviewer that shouldn't change code has `tools`
   restricted to read-only (no `Edit`/`Write`). An unscoped "reviewer" that *can* edit is
   a finding — scoping is enforcement, the system prompt alone is only advice.
4. **A defined return contract.** The system prompt specifies the shape of what it hands
   back (structured findings), because the orchestrator sees only the return, not the
   work.

**The orchestration (in `CLAUDE.md`):**

1. **Passes the needed context.** Each subagent is given the file/diff and concern it
   needs — the setup accounts for the fact that subagents don't inherit the conversation.
2. **Defines the merge.** How results combine, including de-duplication when concerns
   overlap.
3. **Handles boundary failures.** What happens when a subagent errors or returns nothing
   — noted and handled, not dropped or left to hang.

**Right topology (the key judgment):**

- Work split across parallel agents when the concerns aren't actually independent, or
  need full shared context — a single well-instructed agent would do it better and
  cheaper. Flag this even when the individual subagents are well written.
- A genuine multi-stage or wide fan-out job crammed into one agent, where delegation
  would have kept the main context clean.

## Step 2d — Evaluate the MCP server and its wiring (only if the level asks for them)

Skip for levels without MCP. When the level involves it, judge the server's tools, the
connection and secret handling, and — the heart of an MCP level — the **failure plan**.

**The server and its tools:**

1. **Description triggers the tool.** Each tool's description reads as a matching target,
   not a bare label — it's how Claude decides to call it.
2. **Typed input schema.** Parameters are typed and named so Claude calls the tool with
   valid arguments. Loose or untyped inputs are a gap.
3. **One purpose per tool.** Focused tools, not one god-tool behind a mode flag.
4. **Errors returned, not raised.** Tools return an error string the agent can reason
   about; an unhandled exception that just breaks the call is a finding.

**Connection and secrets:**

1. **Wired in the right place.** The server is registered in `.mcp.json` or via the CLI —
   not in `CLAUDE.md`, where it does nothing.
2. **No committed secret.** Any token is injected from the environment (or
   `settings.local.json`) and gitignored — never hardcoded in a committed `.mcp.json`.
   A secret in the repo is a top-priority finding.

**Failure plan (the key judgment):**

- `CLAUDE.md` says what Claude should do when the server is unreachable, a tool errors, or
  the system is rate-limited. The absence of this is the most important thing to catch:
  without it, the agent fabricates an answer through an outage instead of reporting it.
- Credit the learner if external-touching tools are additionally gated (e.g. an
  `mcp__.*` approval rule or `PreToolUse` hook).

## Step 3 — Challenge the learner (conversational)

Report your findings in a coaching tone, not a compliance audit. For each gap:

- Name the missing (or weak) element.
- Explain **why it bites** — the concrete way an agent gets it wrong when this is left
  unspecified. Tie it back to the actual build where you can.
- Pose it as a challenge, not a fix: ask the learner what they'd add, or offer a
  leading question. **Do not rewrite their files for them** — the CLAUDE.md, skill, or
  hook — unless they explicitly ask you to. The learning is in them writing it.

Lead with what they did well, then walk through the gaps roughly worst-first, across
every artifact you reviewed. A misplaced rule (something in the wrong mechanism) usually
belongs near the top. If the setup is genuinely strong, say so and only raise the
marginal improvements.

## Step 4 — Record personalized learnings

`<level>/LEARNINGS.md` already exists. It opens with a fixed **summary** of the level's
overall takeaways, followed by a `## Your notes` section. **Never touch the summary.**
Append the learner's individual gap entries under `## Your notes` only (replacing the
placeholder line there on the first real entry).

**Before writing, read the existing `LEARNINGS.md`.** Only add learnings for gaps that
are **not already recorded** under `## Your notes` — this skill is meant to be run
repeatedly as the learner improves their file, and the list should stop growing as they
get better. Never duplicate an existing entry. If a previously-recorded gap is now well
handled, you may note that it's been resolved, but do not remove the entry.

Append each new entry using this structure:

```markdown
### <Category or element name>
_Recorded <YYYY-MM-DD>_

What was missing: <one plain sentence>.
Why it matters: <one plain sentence about how an agent gets it wrong without it>.
What to do: <one short, concrete recommendation>.
```

Guidelines for the entries:

- One short block per gap. Three lines of substance is the target — understandable, not
  a treatise.
- Write them as things the learner now knows, phrased generally enough to reuse on the
  next level (e.g. "always state the dependency policy"), grounded in this level's
  specifics.
- Use today's date for the `_Recorded_` line.
- Cover gaps from every artifact you reviewed, not just the CLAUDE.md — a misplaced
  rule or a skill that won't fire is as much a learning as a thin CLAUDE.md section.
- If there were no gaps, add a short dated note congratulating them and recording that
  this level's setup passed the rubric clean.

## Step 5 — Close out

Briefly tell the learner what you added to `LEARNINGS.md`, and remind them they can
improve their `CLAUDE.md` and run the coach again to clear remaining gaps.