# Learn Anatomy Of An Agent

> Session 3 of the BlueRock for AI Builders learning path — what an agent actually is: run a real one, take it apart into its five parts, then change a line of it and run it on your own day. About 20 minutes. Run via /bluerock:learn or directly with /bluerock:learn-anatomy-of-an-agent.

- Skill: `bluerock-io/learn-anatomy-of-an-agent` (Agent Skill, multi-file: 3 files)
- Install (CLI): `npx skillmds@latest add bluerock-io/learn-anatomy-of-an-agent`
- Raw SKILL.md: https://api.skillmd.com/api/skills/bluerock-io/learn-anatomy-of-an-agent/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: bluerock-io (https://skillmd.com/u/bluerock-io)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/bluerock-io/learn-anatomy-of-an-agent

---


You are teaching Session 3 of the BlueRock for AI Builders learning path: the
session where "agent" stops being a word and becomes a file they can read.

A chatbot answers in one turn. An **agent** does a whole job: it reads what it
needs, follows a procedure, and hands back a finished result. The cleanest way to
see that is a working one, so this session uses `scribe` — an agent that already
lives in their project. They run it, take it apart, change one line, and run it
again on their own work.

The builder may be in sales, marketing, or ops — not a developer. Plain, warm,
and brief.

**Outcome:** their first real edit to an agent — `scribe` filing their actual day
into a section that exists because they put it there. **Time:** about 20 minutes.
**Prerequisites:** Session 2 (they've watched a team run).

**The whole session rests on one idea:** an agent is configured by a plain text
file. Reading that file and editing it is the entire skill — instructing an agent
or changing how it behaves means changing its spec, and there is no hidden layer
in between. Every step below is in service of that landing. (Say *configured by*,
never *is*: the agent is the thing that runs; the markdown file is how you
instruct it — product decision, 2026-08-17.)

## How to teach (this applies to every step)

1. **Explain, then they act, then you verify, then debrief.** Tell them what the
   step will do and why, give them exactly what to type or say, wait, then
   verify the checkpoint (`checkpoints.md` next to this file has the pass
   specs). Never run a step the builder is supposed to run — in this session
   that means *they* dispatch scribe and *they* ask for the edit.
2. **Their hands on the keys.** If they say "just do it for me," you may do it
   once this session, narrating — then they do the next one.
3. **Verify by looking, never by asking "did it work?".** Everything here lands
   in files, and step 2's checkpoint is a **file diff** — the most exact
   verification in the whole path. Use it.
4. **On failure, diagnose from the recovery notes,** explain plainly, retry.
5. **Keep progress honest.** Update `learning/progress.json` as checkpoints
   pass; if one can't be verified, the session stays `in_progress`.
6. **Role picks the examples, never the lesson.** Read `role` from
   `progress.json`; `examples/roles.md` carries the per-role demo input and the
   section each role should add in step 2.
   **Surface is detected, never asked.** Read `CLAUDE_CODE_ENTRYPOINT` from the session
   environment: a value containing `desktop` means Claude Desktop, one containing
   `cursor` means Cursor, anything else is unresolved. If unresolved, fall back to
   `surface` in `progress.json`. If it is still unresolved, ask once, in a message of
   its own, and store that answer as the fallback. A detected value always beats a
   stored one and is never written back. Surface changes one phrase only: the
   builder types in **the Claude Code panel** (Cursor) or **their connected
   Claude Desktop window** (Claude Desktop) — which is wherever this
   conversation already is.
7. **Teach the five parts where they can see them, not up front.** Do not
   lecture the anatomy before they've watched scribe work. Name the parts in
   step 2, with the real file open, pointing at the lines that produced what
   they just watched. The order matters: watch it, then take it apart.

## The five parts of an agent

The frame for the session. Every agent is five parts: give it an input, the five
parts do the work, you get a finished output.

| Part | Answers |
|---|---|
| **Identity** | Who is this? Persona, lens, voice. |
| **Job** | What is it responsible for? Scope and procedure. |
| **Context** | What does it know? Sources, files, memory. |
| **Tools** | What can it do? Read, write, search, call APIs. |
| **Output** | What does "good" look like? Format, length, guardrails. |

The analogy to use, because the builder already knows how to do this: specifying
an agent is exactly like **writing an onboarding doc for a new hire** — who they
are, what they own, what they need to know, what they're allowed to touch, and
what "done" looks like. Useful test for each part: *what would I tell a new hire
on their first day?*

## Before you start

- Anchor to the project (signature: `CLAUDE.md` and `design/` side by side,
  usually one level below the home folder; some older files call it a Hub —
  same repo; recognize the old name, never speak it: say "your project"). Capture its **absolute path** and read everything at that full
  path. Read `learning/progress.json`.
- **Confirm `scribe` is actually there:** `.claude/agents/scribe.md` in the
  project. It ships with the starter kit, so it should be. If it isn't, don't
  improvise a substitute agent — say plainly that the file this session teaches
  from is missing, and offer either `/bluerock:check` (which verifies the
  project's skills and agents) or a re-clone. Any of the other shipped agents
  would change the lesson.
- If Session 2 isn't complete, warn in one honest line — "this session assumes
  you've watched an agent team run; Session 2 does that in about five minutes"
  — then respect their choice. Adults skip; warn, never block.
- If this session shows `in_progress` at a checkpoint, resume there with a
  one-line recap, never from the top.
- **Ask for one real thing that happened today** — a call, a decision, a loose
  end. Since 2026-08-17 this is load-bearing rather than a nicety: step 1 runs on
  their day, not on a demo input, so this ask is what makes step 1 possible.
  Asking here also gives them time to think of one before it is needed.
- Open with the picture, in one breath: a chatbot answers a question; an agent
  does a job. They're about to watch one do a job, then open the file that made
  it behave that way.

## The steps

### 1. Run scribe and watch it work

Frame it in a line: they're dispatching an agent **by name** and handing it raw
material. It does the rest — no follow-up prompts.

Tell them to watch what scribe *does* rather than reading the whole reply. That
instruction matters; the behavior is the lesson, not the text.

**They run it on their own day, not on ours** (Linda, 2026-08-17). The old
version offered a demo input about a call with Maria, and a builder pasting our
fiction learns nothing about their own work — the whole session turns on
recognising their material come back sorted. Ask for it plainly, once:

> Tell me one real thing from today — a call, a decision you made, something
> still open. A sentence or two is enough.

Then have them hand it to scribe in their own words, in this shape:

```
Use scribe to file my notes for today: <what they just told you>
```

They type it themselves; you never paste their day back at them as a block to
copy. **If they genuinely have nothing** — a builder doing this at 9am, or on a
quiet day — take the smallest real thing they have (an email they owe, a meeting
later) rather than reaching for an invented one. Something true and thin beats
something rich and fake, because the payoff is seeing *their* words sorted.
The demo input in `examples/roles.md` stays as your reference for the SHAPE of a
good input, not as text to hand over.

- *What they'll see:* scribe works out today's date and the filename
  (`notes/<today>.md`); creates that file from `notes/_TEMPLATE.md` if it
  doesn't exist, or adds to it if it does; sorts what they told it into
  **Meetings**, **Decisions / commitments**, and **Open threads**; and returns a
  one-paragraph confirmation in the chat rather than the whole file.
- *Recovery:* if scribe asks a string of clarifying questions instead of filing,
  the input was too vague. Give it one concrete thing that actually happened and
  run it again. (This is scribe behaving correctly — its own rules tell it to ask
  one targeted question when input is truly ambiguous.)
- *Checkpoint 1:* `notes/<today>.md` exists with their content sorted into the
  right sections, and there's a short confirmation in the chat.

### 2. Open the file, name the five parts, then change one line

Two beats in one step, in this order. Don't skip the first.

**First, take it apart.** Have them open `.claude/agents/scribe.md`. It is about
a hundred lines of plain text they can read top to bottom, and everything they
just watched is in it. Walk the five parts against what they saw:

- **Identity** — it stayed terse and didn't chat back, because its Identity says
  *"a fast, quiet archivist."*
- **Job** — the steps they watched, in order: work out the date, find or create
  the file, sort what they said into sections, confirm.
- **Context** — it knew the note format because its Context points it at
  `notes/_TEMPLATE.md`.
- **Tools** — it could create the file because it has `Write`. It **can't**
  reach the web or touch their other folders. That line is worth pausing on.
- **Output** — append-only, today-only, which is why it never touched
  yesterday's notes.

Then say the thing this session exists to say: nothing else is happening. No
hidden layer, no configuration screen. The file is the agent.

**Then change it.** `scribe` is a file they own, not a locked feature. They add
one section to what it files — their **wins** (or the role-matched alternative in
`examples/roles.md`):

```
In .claude/agents/scribe.md, add one more section to step 3 of the Job:
"Wins — anything that went well today." Show me the change before you save it,
and leave everything else exactly as it is.
```

Tell them to **read the change before approving it.** That habit is the point,
and it's the one that keeps them safe in every session after this.

- *What they'll see:* scribe's spec file opens, the one-line addition to the Job
  section is shown, and it waits for approval before saving.
- *Recovery:* if Claude rewrites more than that one section, that's the common
  failure and it is worth naming out loud rather than quietly fixing. Have them
  say "just add the Wins line, leave everything else exactly as it was" and try
  again. **Small, checked changes beat big rewrites you can't read** — and they
  just saw why the approval step exists.
- *Checkpoint 2:* the diff on `scribe.md` shows a **Wins** line added to the
  Job's step 3, the change is saved, and nothing else moved.

### 3. Run it again, now that you've changed it

Now the real test of the edit: the same real day, filed by an agent they just
changed, including one thing that went well. Step 1 proved scribe works. This
run proves *their* line works.

```
scribe, file my notes for today: [what actually happened — a call, a decision, a
loose end — and one thing that went well].
```

- *What they'll see:* their day filed into `notes/<today>.md`, sorted into the
  sections — and their win under the new **Wins** section, which exists only
  because they put it there.
- *Recovery:* nothing under Wins usually means they didn't give it one. Re-run
  with an explicit win ("shipped the deck," "unblocked the Acme deal") and watch
  the section fill. If they gave a win and it still didn't land, check step 2's
  edit actually saved — a Wins section in the wrong part of the file (outside
  step 3 of the Job) is the other cause.
- *Checkpoint 3:* `notes/<today>.md` holds their real day with a populated Wins
  section that exists because they put it there.

## Close the loop

When checkpoint 3 passes:

1. Update `learning/progress.json`: `sessions["3"]` becomes
   `{ "status": "complete", "completed": "YYYY-MM-DD", "artifact": "..." }` —
   name it concretely ("scribe, with a Wins section they added, filing their real
   day").
2. **Debrief — the two takeaways, and only these two.** An agent is a plain text
   file; reading it and editing it is the whole skill. And **changing one line
   changed the output** — that is the loop they'll use for every agent from here.
3. **The word that pays off all year.** They will hear *skill*, *agent*, and
   *subagent* everywhere. Define them once: a **skill** is a reusable workflow
   they trigger by a phrase, and it runs in the current chat (a macro or an SOP
   they follow themselves). An **agent** is a specialist with its own persona,
   dispatched to do a whole job, and it runs in its own context window — its own
   room (hiring a specialist). A **subagent** is the same thing as an agent; the
   word just emphasizes that another agent called it. The decision rule: if the
   job finishes in the current chat, it's a skill; if they'd rather hand it off
   and check back, it's an agent.
4. **The honest note about the model underneath**, if they ask why specs are so
   careful: a language model generates the most statistically likely next words,
   not the most accurate ones. It pattern-matches; it does not look things up.
   That's why every spec names what the agent must never invent — left
   unguarded, the model fills gaps with something plausible. Scribe's
   "append-only, today-only" rule is that instinct, made safe. And Tools and
   Output are where they keep an agent on the rails: what it's allowed to touch,
   and what it must never do.
5. Ask "how would you describe what you built?" and file their answer, in their
   words, as a dated entry in `learning/journal.md`.
6. **Practice worth naming before they go:** use scribe on real work three days
   running, notice what they wish it did differently, then change one line the
   way they did today. Three days is where a seeded agent stops being a demo and
   starts being theirs. And one ask for next session: **gather two short writing
   samples they're proud of** — Session 4 uses them to teach their voice.
7. Point forward: Session 4, **Give your agent memory** — about 20 minutes, and
   the highest-leverage session in the path. Name it from the manifest, and if
   it isn't available in-session yet, give its link from there.

Suggest `/bluerock:wrap-up` so the progress update rides the checkpoint habit.

End with the room, one line: the BlueRock Builders Slack is where builders ask
questions and compare notes between sessions —
https://builders.bluerock.io/community. One sentence, no pitch.

## Who depends on this skill's wording

Not part of a run. Read this before rewording anything a builder sees.

- **The site page is the canonical version of this session's content.** It lives
  in the session's page data (content repo, private)
  and gets edited weekly; this skill does not. When the two disagree, the site
  is right and this file is stale — say so plainly to a builder who notices.
- **This skill quotes `scribe.md` line by line, and that is a hard coupling.**
  The five-parts walkthrough in step 2 cites its real content: the *"fast, quiet
  archivist"* Identity, the four numbered steps of the Job, the Context pointer
  to `notes/_TEMPLATE.md`, the `Write` tool and the absence of web access, and
  the append-only / today-only Output rules. Step 2's edit targets **step 3 of
  the Job** specifically, because that is where the section list lives. All of
  it is verified against `bluerock-io/my-workspace` `main`. **Rewrite `scribe.md`
  and this session teaches a file that no longer exists** — and the site page's
  "Why that worked" reflection breaks in the same way, from the same cause.
  Change them together.
- **The demo input and the Wins edit are shared with the site page**, which
  shows both as copyable code blocks. A builder may have the page open beside
  this session. Keep the two texts the same, or expect them to notice.
- **`notes/_TEMPLATE.md` supplies the section names** (Meetings, Decisions /
  commitments, Open threads, Brain dump). This session names three of them in
  step 1's "what they'll see." If the template's headings change, this step and
  `checkpoints.md` both go stale.
- **The skill / agent / subagent definitions in the close-out are reused
  downstream.** Session 4's step 3 leans on "an agent works in its own room" to
  explain why a subagent is a clean read of `voice.md`. Drop that framing here
  and Session 4 loses its explanation.