Block 1 / Topic 1.3 — AI coding tools + decision framework

1.3.1

CLI-first vs IDE-chat

5 min Lecture

Slide 1 / 3 · Two shapes

Where does the model live?

Shape	Examples	Why it matters
IDE chat	Cursor, Copilot Chat, JetBrains AI	Tight loop, lower engineering ceiling
CLI agent	Claude Code, Codex CLI, Gemini CLI	Composable, scriptable, higher ceiling

Slide 2 / 3 · Why CLI

CLI = composability

Pipes to other tools (grep, jq, gh)
Triggers from CI, hooks, cron, MCP servers
Versionable config — settings, skills, plugins on disk
Multi-CLI verification (run Codex + Claude on the same task)
This is why Sam's block lives at the CLI altitude

Slide 3 / 3 · Convergent shape

The shape is convergent

Prompt → plan → tool use → diff → confirm
Most CLIs implement some variation of this loop
Differences are surface, not deep
We'll demo with Claude Code; portability is the point

Speaker notes

Slide 1: "Two shapes of AI coding tool. IDE chat — Cursor, Copilot, JetBrains. Lives inside your editor. Tight loop, low friction, lower engineering ceiling. CLI agent — Claude Code, Codex CLI, Gemini CLI. Lives in your terminal. Composable, scriptable, higher ceiling."

Slide 2: "Why CLI matters at the engineering altitude? Composability. Pipes. Hooks. CI triggers. Multi-CLI verification — Sam will show you how to run Codex and Claude on the same task and use one to verify the other. None of that is possible inside an IDE chat. This is why every block from here on lives at the CLI altitude."

Slide 3: "The shape across CLIs is convergent. Prompt, plan, tool use, diff, confirm. Most CLIs implement some version. We'll demo with Claude Code today, but the patterns are portable."

Calibration check (from Topic 1.1 tool poll): if the room is mostly Claude Code, move on. If it's mixed, spend an extra 30s on the Codex/Gemini analogues.

Demo piece

Optional — if the room is mixed CLIs, project a one-screen comparison of the launch commands:

claude       # Claude Code REPL
codex        # OpenAI Codex CLI
gemini       # Google Gemini CLI

1.3.2

Claude Code core flow

5 min Lecture

Slide 1 / 3 · The loop

Claude Code core flow

PROMPT  →  PLAN  →  TOOL USE  →  DIFF  →  CONFIRM
                                      ↑                 ↓
                                      └──── iterate ←───┘

Slide 2 / 3 · One turn

Anatomy of one turn

Prompt — you describe the goal
Plan — model proposes steps (you can edit)
Tool use — model edits files, runs commands, reads diagnostics
Diff — every write is staged as a diff
Confirm — you accept, reject, or redirect

Slide 3 / 3 · Plugins extend the loop

Plugins extend the loop

A plugin can inject skills (extra knowledge)
A plugin can inject slash commands (new entry points)
A plugin can ship its own subagents
The skill-creator plugin we'll use next: all three

Speaker notes

Slide 1: "Claude Code's core flow. Five nodes. Prompt, plan, tool use, diff, confirm. The loop iterates until you accept the result or quit."

Slide 2 — walk each step in ~30 sec: "Plan is the step most people skip — they hit Enter on the prompt and let the model dive in. The plan step is where you redirect early before tool-use happens. Diff is where every write lands — nothing gets written to disk without you seeing the diff first. Confirm is the human gate."

Slide 3 — bridge to Block 2: "Plugins extend this loop. They inject skills — extra knowledge the model can pull in. They inject slash commands — new entry points like /skill-creator. They can ship subagents. The skill-creator plugin we'll use in Block 2 does all three."

1.3.3

★ Skill vs plugin vs agent decision framework

10 min Lecture LOAD-BEARING — DO NOT CUT

Block 2 depends on this mental model. Without it, attendees don't know why they're promoting a prompt to a skill.

Slide 1 / 4 · Four surfaces

Four ways to package AI behavior

Surface	What it is	When to reach for it
Prompt	Plain text, one-off	Single use, exploratory, you don't need it again
Skill	`SKILL.md` with frontmatter + body + references	Repeatable workflow with specific triggers; you'll want this again next week
Plugin	Folder bundling skills + commands + MCP servers	Shipping a capability to a team; needs versioning + distribution + multiple skills bundled
Agent	Specialized subagent dispatched for a task	Isolated context, parallel work, narrow capability — when you want a fresh model, not a fresh prompt

Slide 2 / 4 · Hierarchy

The packaging hierarchy

PLUGIN
  ├── SKILL  (1..N)
  │     └── prompt body + references
  ├── slash commands
  ├── MCP servers
  └── subagents (AGENTS)

Skill is the atom. Plugin is the package. Agent is the dispatcher.

Slide 3 / 4 · Decision flow

Decision questions, in order

Will I use this again? No → prompt. Yes → keep going.
Does it need its own context window? Yes → agent.
Will I ship it to others? Yes → plugin. No → skill.
Does it bundle commands + MCP + multiple skills? Yes → plugin.

Slide 4 / 4 · Five examples

Where does each example land?

Example	Surface	Why
One-off PR description for a single PR	Prompt	Single use
Generating PR descriptions for all PRs going forward	Skill	Repeatable trigger
Running 5 different code reviewers in parallel on one PR	Agent(s)	Isolated contexts, parallel work
Standardized incident-response toolkit for a team	Plugin	Bundles skills + commands + RBAC
Reading a single file to answer a question	Prompt	Single use, exploratory

Speaker notes

Slide 1 — walk the four surfaces: "Four ways to package AI behavior. Prompt — plain text, one-off, exploratory. Skill — a SKILL.md file with frontmatter and a body. Repeatable workflow with specific triggers. The thing you'll want next week. Plugin — a folder that bundles skills, slash commands, MCP servers, sometimes subagents. The thing you ship to a team. Agent — a specialized subagent dispatched for one task. Isolated context, parallel work, narrow capability."

Slide 2 — mental model: "Skill is the atom. Plugin is the package. Agent is the dispatcher. A plugin contains skills, but a skill doesn't need a plugin. An agent is a thing you dispatch to — not a thing you bundle. The packaging hierarchy is one of the most-asked questions on the Anthropic forums; this slide is the answer."

Slide 3 — the decision flow: "Four questions, in order. One: will I use this again? If no, prompt. If yes, keep going. Two: does it need its own context window? If yes, agent. Three: will I ship it to others? If yes, plugin. Four: does it bundle multiple skills + commands + MCP? If yes, plugin."

Slide 4 — quick test: "Five examples. Let's read them. [Walk the table.] Note that 'reading a single file' lands at prompt — you don't need a skill for one-shot reads. And 'running 5 reviewers in parallel' lands at agents, not plugins — because the parallelism + isolated context is the requirement."

Anchor: "Atom on this is Atom - Skills vs Plugins vs Agents — Decision Framework. Single most-referenced atom in this workshop. In Block 2, we'll take your v5 prompt and walk it across the boundary from prompt to skill. You'll see exactly what that promotion looks like in code."

1.3.4

Plugin marketplace tour

3 min Lecture

Slide 1 / 2 · Marketplace

The Anthropic plugin marketplace

Discovery layer for plugins
Already includes: skill-creator, frontend-design, superpowers, context7, more
Installed via /plugin inside the Claude Code REPL
An ecosystem maturity signal — plugins are how the platform is shipping fast

Slide 2 / 2 · Today's plugin

`skill-creator` — our Block 2 spine

Plugin we'll use in Block 2 (the next ~75 min)
Should already be installed (Prerequisites)
We'll verify in Beat 1.3.5 hands-on
The plugin marketplace itself is worth a tour after the workshop

1.3.5

HO Beat A — Boot Claude Code + verify skill-creator

5 min Hands-on

Slide 1 / 2 · Two commands

Boot + verify

Open a terminal in the workshop repo
Run the verify one-liner below

Verify command:

grep -q '"skill-creator@' ~/.claude/plugins/installed_plugins.json \
  && echo "✓ skill-creator installed" \
  || echo "✗ NOT installed"

Slide 2 / 2 · Red X path

If you get the red X

claude (launch the REPL)
/plugin (interactive picker)
Search "skill-creator" → install
Re-run the verify command above

Don't try claude /plugin list — /plugin is an interactive REPL command, not a CLI subcommand.

Demo piece — attendees run, instructor mirrors

Attendees: run the verify one-liner.

Instructor mirror on projector:

cd ~/code/ai-engineering-workshop
grep -q '"skill-creator@' ~/.claude/plugins/installed_plugins.json \
  && echo "✓ skill-creator installed" \
  || echo "✗ NOT installed"

If room has stragglers: project the claude → /plugin flow once at the front so they can follow.

1.3.6

HO Beat B — Tour the skill-creator on disk

5 min Hands-on

Slide 1 / 3 · Where it lives

A plugin is a folder

~/.claude/plugins/marketplaces/
  claude-plugins-official/
    plugins/
      skill-creator/

Slide 2 / 3 · What's inside

The four things every plugin can ship

SKILL.md — the plugin's primary skill (the one Claude reads first)
scripts/ — Python/shell helpers the plugin invokes
references/ — long-form docs the skill links to (lazy-loaded)
agents/ — specialized subagents the plugin dispatches (e.g. grader, analyzer)
(skill-creator adds) eval-viewer/ — the HTML report we'll see in Block 2

Slide 3 / 3 · Why this matters

The plugin is just files

You can read every line of a plugin before it touches your machine
The grader subagent is agents/grader.md
The eval-viewer is a Python script you can run yourself
No magic. Just structured files.

Speaker notes

Slide 1: "A plugin is a folder. Yours is at ~/.claude/plugins/marketplaces/claude-plugins-official/plugins/skill-creator/. Open it in your editor or just ls it. Look at it."

Slide 2 — walk the folder shape: "Inside, you'll see four kinds of things every plugin can ship. SKILL.md is the primary skill — what Claude reads first. The scripts directory holds helpers — the description optimizer we'll use in Block 2.3 lives there. References are long-form docs lazy-loaded when the skill needs them. Agents are specialized subagents — skill-creator ships a grader and an analyzer. And skill-creator adds an eval-viewer — the HTML report we'll meet in Block 2 Beat E."

Slide 3 — the anchor: "The plugin is just files. No magic. You can read every line before it touches your machine. That's why we're spending five minutes on disk-tour — when something doesn't work in Block 2, you can cat the agent prompts and see exactly what's happening."

Demo piece — attendees + instructor mirror

Attendees: open the skill-creator folder in their editor.

Instructor mirror:

ls -la ~/.claude/plugins/marketplaces/claude-plugins-official/plugins/skill-creator/
cat ~/.claude/plugins/marketplaces/claude-plugins-official/plugins/skill-creator/SKILL.md | head -30
ls ~/.claude/plugins/marketplaces/claude-plugins-official/plugins/skill-creator/agents/

Read 2-3 lines of the SKILL.md frontmatter aloud — "see how this plugin describes itself? That's exactly the pattern you'll write in Block 2 for project-inspector."

1.3.7

HO Beat C — "Which is this?" classification

10 min Hands-on · discussion

Slide 1 / 6 · Setup

Which surface is this?

5 scenarios on screen, one at a time
Vote: prompt / skill / plugin / agent
1 min per scenario, then group discussion
No wrong answers — only better justifications

Slide 2 / 6 · Scenario 1