🗣️ The vocabulary: runtime, harness, skill, MCP, hook, handoff
Six words will show up throughout the entire course. Each one has a precise meaning and a place on disk. This module defines all of them from scratch, shows where Claude Code and Codex look for each thing, and separates what is yours from what belongs to the tool.
🧱 Model vs runtime vs harness
When someone says "I use Claude", they could be talking about three different things. The model is the AI brain that generates text (Claude Opus, GPT, DeepSeek). The runtime is the program you open in the terminal that talks to that model (Claude Code, Codex CLI, dsh). The harness is the structure around the model that gives it hands and eyes: reading files, running commands, keeping history, calling tools. In practice, runtime and harness are usually the same program; the distinction matters when you swap one and keep the other.
New here? An LLM (language model) is just the model: it receives text, returns text. On its own it doesn't open any file. What makes Claude Code "edit your code" is the harness around it, which turns the model's text into real actions and returns the result. The model thinks; the harness acts.
From left to right: the model sits at the bottom of two blue boxes that belong to the tool. What is yours stays outside them, on the right, and is read by any harness. Switching harness means switching the blue boxes; the green box on the right doesn't change.
✓ Yours (portable)
- ✓The project instructions, in Markdown.
- ✓The skills (procedures in SKILL.md).
- ✓The context, the decisions and the handoffs.
✗ The tool's (native)
- ✗The execution loop and the history format.
- ✗Sandbox, permissions, per-folder trust.
- ✗Plugins, hooks and automatic memory.
Key concepts
The LLM: text in, text out. Never touches a file.
The program that runs the loop: read → think → act.
Tools, history, hooks, permissions wrapped around the model.
Model + harness seen from the outside: the thing that reads your project.
📜 Instructions (CLAUDE.md / AGENTS.md) and reading order
Every harness opens a folder and looks for an instructions file. Claude Code looks for CLAUDE.md; Codex, Gemini and OpenCode look for AGENTS.md. This is the only point in the system that is truly tied to the provider, and the fix is simple: AGENTS.md becomes the source, and CLAUDE.md starts with a single line that imports AGENTS.md. One rule, written once, read by everyone.
Goal: make Claude read the same file Codex reads. This is the entire CLAUDE.md of an adapted project:
@AGENTS.md
# Claude Code specific
- Never use AskUserQuestion; ask in free text.
- The superpowers / context-mode / claude-mem plugins belong to Claude; don't mention them in anything portable.How to verify: open a fresh Claude session in the project and ask "quote one project rule and the file it comes from". The answer should point to AGENTS.md.
New here? Reading order is the list, written at the top of AGENTS.md, of what the agent should read and in what sequence: first the rules, then the context, then the current task, and finally the latest handoff. No harness loads these folders on its own; it only reads what the instructions tell it to read. That is why the order has to be written down.
AGENTS.md
Stable rules and the reading order. Short. Changes when a rule changes.
context/overview.md and current-state.md
What the project is and what is true today.
tasks/current.md
What we are doing right now, who owns it, what the definition of done is.
handoffs/latest.md
Where the last session stopped and what the exact next action is.
Key concepts
Source of the instructions. Read by Codex, Gemini, OpenCode.
The line that makes CLAUDE.md import the source.
The little that only Claude understands, below the import line.
Written at the top; nothing is auto-loaded.
🧩 Skill (SKILL.md) and where each runtime looks
A skill is a written procedure for the agent: a folder with a SKILL.md file (name, description, when to use it, steps) and, optionally, scripts and references alongside it. The format is the same across Claude Code and Codex; what changes is where each one looks. That folder difference is what leads to manual copies, and manual copies are the shortest path to diverging versions.
📂 Where each runtime looks for skills
- •Claude Code:
~/.claude/skills/(global) and.claude/skills/in the project. - •Codex CLI:
~/.codex/skills/and~/.agents/skills/(global),.agents/skills/in the project. - •dsh (DeepSeek in a container): a folder mounted as
/work/.dsh/skills. - •On the audited machine: 117 skills in Claude, 27 in Codex, 3 hand-made copies in dsh, 16 of its own in a bot. Four consumers, no single source.
New here? A canonical skill is the source version, kept in a single place. Each runtime's folders receive generated copies made from it by a tool (the course uses polyskill), with a drift check: if someone edited the copy instead of the source, the system warns you. You edit one file; the N copies are regenerated.
✗ Without a canonical source
- ✗skill-claude, skill-codex, skill-gemini, skill-glm: four files to maintain.
- ✗You fix a bug in one and forget the others.
- ✗Nobody knows which version is the right one.
✓ With a canonical source
- ✓One canonical SKILL.md → Claude adapter, Codex adapter, dsh adapter.
- ✓The build regenerates every copy at once.
- ✓Drift check: [ok] or [DRIFT] per runtime.
Key concepts
A procedure in Markdown: name, when to use it, steps.
Where each runtime looks. It differs between them.
The only editable version; the others are generated.
Divergence between copy and source. It should be detected, not discovered by accident.
🔌 MCP: tools and data, not memory
MCP (Model Context Protocol) is a standard for connecting an agent to external services: an image generator, a post scheduler, a database. The agent gains new tools ("generate image", "list posts") that any compatible harness can use. It is the easiest part to get confused about: MCP gives access, it does not give memory. It does not merge chat histories, does not resolve memory conflicts, does not separate clients.
New here? Think of MCP as a standardized power outlet. The service (Magnific, Metricool) offers the outlet; the harness (Claude, Codex) has the plug. Each harness needs to register the outlet on its own, but the access key is the same and lives in a referenced .env file, never copied.
📊 The real state on the audited machine
- •Claude: global MCP magnific and metricool, plus two per project.
- •Codex: no MCP registered.
- •Consequence: 15 skills that depend on MCP only work in Claude until Codex registers the same outlets.
✓ What MCP solves
- ✓Standardized access to external tools and data.
- ✓Same service, plugged into N harnesses.
- ✓Memory exposed via MCP becomes portable (the source text does this).
✗ What MCP does not do on its own
- ✗Merge chat histories from different tools.
- ✗Decide which version of a fact is the right one.
- ✗Enforce separation between clients: that is backend permission.
Key concepts
Tools and data protocol for agents.
Each runtime plugs into the same outlet on its own.
The key lives in the .env; the registration points to it.
MCP does not remember anything for you.
⚙️ Hooks, plugins, subagents: what is native
Three things from Claude Code do not cross the bridge, and it is good to know that before trying. A hook is a script the harness fires on an event (when the session opens, after editing a file). A plugin is a package that adds commands and behaviors to the harness. A subagent is a child agent with its own role, summoned by the main one. All three depend on the harness having that event, that package format, that summoning mechanism. Codex has hooks, but different events; it does not have Claude's plugins; it does not have subagents in the same format.
🔍 Real comparison of the two harnesses
- •Hooks: Claude fires on SessionStart (injects a playbook, adjusts cache); Codex fires on PostToolUse and Stop. The "on session open" event does not exist in Codex.
- •Plugins: 7 in Claude (superpowers, claude-mem, context-mode…); 1 in Codex (github). Incompatible formats.
- •Subagents: 7 in Claude (a "council" of roles); no 1:1 equivalent in Codex.
Hook becomes text
Whatever the hook injected when the session opened (a pacing playbook, for example) goes in as a section of AGENTS.md. You lose the automation, you keep the content.
Plugin stays in the residue
You never mention a plugin in a portable instruction. It lives below the @AGENTS.md line, in the part only Claude reads.
Subagent becomes a role skill
The "devil's advocate" prompt becomes a SKILL.md that any harness invokes as a procedure. You lose the automatic summoning, you keep the role.
💡 Rule from the source text
"Put reusable hook and check logic in ordinary scripts; validate each native event, payload and trust configuration separately." The script is portable. The trigger belongs to the tool.
Key concepts
Script fired by a harness event. Events differ.
A harness package. Does not cross over.
Child agent with a role. Becomes a role skill.
What exists only in that harness. Stays in the residue.
🔁 Handoff and prime: the summary that travels
A handoff is the structured summary a session writes before closing: decisions made, unfinished tasks, next steps, file paths. It goes into a Markdown file, with a latest.md pointing to the most recent one. Prime is the reverse act: the new session reads that file before doing anything. The cycle replaces dependence on the raw history, and it is what lets Claude stop and Codex carry on.
The green file in the middle is the only link between the two blue sessions. Notice that Session B does not need to be the same harness as Session A: the handoff is Markdown, so any executor can read it.
New here? Without a handoff, "pick up where I left off" means reopening the old session in the same harness, or digging through a JSONL file thousands of lines long. The handoff is a one-page summary, written by the agent itself, that fits in any context. It is the difference between carrying the whole conversation and carrying what matters from it.
✓ A good handoff has
- ✓Decisions made and the reason behind them.
- ✓Unfinished tasks and what is still missing.
- ✓Exact paths of the files touched.
- ✓The next action, concrete, in one line.
✗ A bad handoff
- ✗Narrates the conversation in chronological order.
- ✗Says "several files were changed" without saying which.
- ✗Claims something works without saying which test was run.
- ✗Includes credentials or the raw history.
Key concepts
Structured summary written when the session closes.
The new session reads the handoff before acting.
Fixed pointer to the most recent handoff.
Claude writes, Codex resumes. Or the other way around.
Self-check (optional): which of these items is portable between Claude Code and Codex without adaptation?
🎯 Module summary
Next module:
1.3 — The three levels of migration: one click, one command, personal