MODULE 2.1

🩺 Environment diagnosis

Before moving a single comma: know what exists. In this module you clone the kit, run doctor.sh to find out whether the machine is ready and audit.sh to inventory what Claude has and Codex doesn't. Everything is read-only, with the real output from this machine as the example.

6
Topics
~30
Minutes
Basic
Level
Practice
Type
1

📦 Clone the kit

The agente-claude-codex kit is the "level 2, one command" the newsletter imagined: a repository with five bash scripts, the mega-prompts as copyable text and a portable core template. It installs nothing on the system, asks for no password and doesn't touch ~/.claude or ~/.codex unless you tell it to. The first step is just bringing the folder to your machine.

🎯 Goal

Have the kit in a local folder, with the scripts executable, ready to run the diagnosis.

git clone https://github.com/inematds/agente-claude-codex
cd agente-claude-codex
ls scripts/
# adapt-instructions.sh  audit.sh  doctor.sh  init-core.sh  readback-test.sh  sync-skills.sh

How to verify: ls lists the six scripts. If any of them lacks execute permission, chmod +x scripts/*.sh.

New here? "Cloning" means downloading a complete copy of a git repository, with its history. A "bash script" is a text file with terminal commands that run in sequence. None of the kit's scripts needs sudo.

scripts/

The six commands: diagnose, audit, adapt, install core, port skill, prove.

prompts/

Prompt A, Prompt B, readback and handoff as text to paste into an agent.

template/

AGENTS.md, context/, tasks/, handoffs/ to copy into any project.

Key concepts

Kit

Scripts + prompts + template, no global installation.

Read-only

doctor and audit change nothing; they only read.

No sudo

Everything runs as your user, in your folder.

Reversible

Deleting the folder undoes everything this module does.

2

🩺 doctor.sh: ok / warning / missing

The doctor answers the question that comes before any other: is my environment ready? It checks git, python3, node, Claude Code (skills, CLAUDE.md, hooks), the Codex CLI (skills, config, sandbox, MCP), polyskill and the kit's own files. Each item lands in one of three categories, and the script exits with code 1 if something essential is missing, which is useful for automation.

doctor.sh read-only [ok] [warning] [MISSING] move on · git, python3, claude, codex works with limitations · no MCP, no import essential · comes with the command to fix it exit 0 or 1 automatable

From left to right: the doctor examines each item and classifies it as ok, warning or missing. Only red changes the exit code, so a CI script can block the migration when something essential is missing.

💻 Run the diagnostic

Goal: know, in 2 seconds, whether something is missing before auditing.

scripts/doctor.sh
echo "exit=$?"

How to verify: the last line says Pronto. Próximo passo: scripts/audit.sh and exit=0. If it says Faltam itens essenciais, fix what is under [FALTA] and run it again.

This is the real output on the machine where the kit was built, on 2026-09-14. Notice that the two warnings block nothing: they only say that MCP-dependent skills will not work in Codex until you register the server, and that the Codex CLI has no import command (the "one click" exists only in the desktop app).

== Sistema ==
  [ok]     Linux aarch64, shell bash 5.2.21(1)-release
  [ok]     git 2.43.0
  [ok]     python3 3.12.3
  [ok]     node v24.13.0
== Claude Code (fonte) ==
  [ok]     claude 2.1.270 (Claude Code)
  [ok]     ~/.claude/skills: 117 skills
  [ok]     ~/.claude/CLAUDE.md existe (72 linhas)
  [ok]     settings.json: 2 hooks, 7 plugins
== Codex CLI (destino) ==
  [ok]     codex codex-cli 0.154.0
  [ok]     /home/<usuario>/.codex/skills: 27 skills
  [ok]     /home/<usuario>/.agents/skills: 29 skills
  [ok]     config.toml: sandbox_mode=danger-full-access
  [aviso]  nenhum MCP no Codex: skills marcadas 'adaptador' só funcionam após 'codex mcp add'
  [aviso]  Codex CLI sem comando import (o import 'um clique' é só no app desktop); use os scripts deste kit
== polyskill (passo 4) ==
  [ok]     polyskill 0.1.0
== Este kit ==
  [ok]     scripts/audit.sh
  [ok]     scripts/adapt-instructions.sh
  [ok]     scripts/init-core.sh
  [ok]     scripts/sync-skills.sh
  [ok]     scripts/readback-test.sh
  [ok]     template/AGENTS.md
  [ok]     prompts/01-migrate-claude.md
  [ok]     pasta gravável (relatorios/ será criada aqui)

Pronto. Próximo passo: scripts/audit.sh
exit=0

✓ What the doctor does

  • ✓Reads versions and folders; never writes.
  • ✓Tells you the command to fix each missing item.
  • ✓Warns you if AppArmor is going to break the Codex sandbox.
  • ✓Flags a missing runtime as a warning, not as an error.

✗ What it does NOT do

  • ✗Install Claude, Codex or polyskill for you.
  • ✗Edit config.toml or settings.json.
  • ✗Inventory skill by skill (that's the audit's job).
  • ✗Guarantee that a session will read your files (that's the readback's job).

Key concepts

[ok]

Item present and in the expected state.

[aviso]

Works, but with a known limitation.

[FALTA]

Essential item missing; changes the exit code to 1.

Exit code

0 = ready; 1 = fix first. Useful for CI.

3

🔍 audit.sh: read-only inventory

If the doctor asks "is it ready?", the audit asks "what exists?". It reads both homes, ~/.claude and ~/.codex, counts skills, commands, subagents, hooks, plugins and MCP, and produces a Markdown report with the source → destination matrix: every skill that exists only in Claude gets a classification. It is exactly step 2 of Prompt A ("Inventory the working system"), automated.

~/.claude 117 skills · CLAUDE.md · hooks ~/.codex 27 skills · config.toml audit.sh comm + grep for SKILL.md reusable · 72 adapter · 15 native · 2 unresolved · 1 relatorios/ auditoria-*.md

The audit compares the skill lists of both homes (on the left), runs every Claude-only skill through a grep heuristic (in the center) and writes the matrix in four classes (on the right). The numbers are from this machine on 2026-09-14: 89 skills only in Claude.

💻 Run the audit

Goal: generate the report in relatorios/auditoria-<date>.md with the skills matrix.

scripts/audit.sh
# Report: relatorios/auditoria-2026-09-14.md
#   reusable:    72
#   adapter:     15
#   native:      2
#   unresolved:  1

How to verify: the sum of the four lines has to match "Claude only" inside the report (here, 72+15+2+1 = 90 table rows, 89 skills plus 1 without SKILL.md). If it doesn't match, see topic 5.

💡 Practical tip

Run the audit before AND after every migration round and compare the two reports with diff. It's the cheapest way to see what really changed, without relying on anyone's memory.

Key concepts

Inventory

List of what exists, with origin and quantity.

Gap

What is in one runtime and not in the other.

Source → destination matrix

Every asset with its classification and what to do.

Dated report

Evidence you can compare against tomorrow.

4

📊 Reading the skills matrix

The matrix is a grep-based heuristic, not a verdict. The audit opens the SKILL.md of every Claude-only skill and looks for clues: a mention of an MCP tool (mcp__, magnific, heygen) becomes adapter; a mention of AskUserQuestion, subagents or Claude plugins also becomes adapter; a mention of a hook (SessionStart, PreToolUse) becomes native; everything else is reusable, that is, plain Markdown and scripts that Codex reads just the same.

72

Reusable

Ports via polyskill with no changes. E.g.: formato-curso-v5, roteirista-inema, video-explicativo, pixflow-motion, inemaref-serie.

15

Adapter

Depends on an MCP or a Claude plugin. Only works in Codex after codex mcp add. E.g.: avatar-heygen-nei, heygen-cli, espiona-ads, ugc-seedance25, website-intelligence, the 8 printing-press variants.

2

Native

Depends on a SessionStart hook, which Codex doesn't have. fable-mindset and silver-platter become text in AGENTS.md.

1

Unresolved

inemaref-referencias: folder without a SKILL.md. Decide by hand: archive it or complete it.

✓ How to use the matrix

  • ✓Start with the most-used reusable ones; quick win.
  • ✓Group the adapter ones by the MCP they require.
  • ✓Open 3 or 4 SKILL.md files as a sample to check the heuristic.

✗ Common mistakes

  • ✗Treating "reusable" as "tested": it's only about format.
  • ✗Porting all 72 at once; do batches of 10.
  • ✗Forgetting that subagents and plugins don't even enter the matrix: they don't migrate.

Key concepts

Heuristic

Rule of thumb by grep; right most of the time, review the rest.

Reusable

Plain Markdown and scripts: ports without changes.

Adapter

Needs an MCP or an equivalent on the target.

Native

Tied to a runtime event; becomes text or stays behind.

5

🛡️ Codex sandbox and AppArmor: the real failure

The Codex CLI runs commands inside a sandbox built with bwrap (bubblewrap), which isolates the process using Linux user namespaces. On recent Ubuntu, AppArmor restricts those namespaces for unprivileged processes, and bwrap dies immediately with loopback: Failed RTM_NEWADDR: Operation not permitted. Nothing runs, not even an ls. It was the kit's first real failure, and the fix was a single line.

⚠️ What happened

The first readback in Codex (module 2.5) forced -s read-only on the call. The sandbox tried to start, AppArmor blocked it, and Codex replied "I couldn't read any file". The whole session was lost.

bwrap: loopback: Failed RTM_NEWADDR: Operation not permitted
1

Diagnose

sysctl kernel.apparmor_restrict_unprivileged_userns returns 1. The doctor already checks this and warns you.

2

Decide

Trusted personal machine: turn the sandbox off in the Codex config. Shared machine: allow the namespace via sysctl (requires root) and keep the sandbox.

3

Fix the smallest thing

In the kit: remove the -s read-only from the script and respect the sandbox_mode from the config. Logged in FALHAS.md as both prompt and infra.

💻 Check and adjust the sandbox

Goal: make sure Codex can run commands on this machine.

# 1. does AppArmor restrict user namespaces?
sysctl -n kernel.apparmor_restrict_unprivileged_userns

# 2. if it returned 1 and the machine is yours alone, in ~/.codex/config.toml:
sandbox_mode = "danger-full-access"

# 3. quick test
codex exec --skip-git-repo-check "run 'echo sandbox-ok' and reply with only the output"

How to verify: the reply contains sandbox-ok. If bwrap shows up in the output, the config wasn't read: check the path and the spelling of the key.

New here? A "sandbox" is an isolated box where a program runs with no access to the rest of the system. "AppArmor" is the Linux security module that decides what each program is allowed to do. danger-full-access turns the box off: Codex gets the same power you have in the terminal. Acceptable on a personal machine, dangerous on a shared server.

Key concepts

bwrap

Bubblewrap, the isolator Codex uses by default.

User namespace

Kernel feature that AppArmor may block.

sandbox_mode

Key in config.toml; scripts must not override it.

Smallest fix

One flag removed, not a script rewritten.

6

📄 The report and what to do with it

The audit leaves a file at relatorios/auditoria-<data>.md with six sections: versions and roots, the skills gap with the matrix, commands and subagents and hooks and plugins, Codex hooks, MCP (names only, never key values) and a "not run" section reminding you that no behavior was tested. That file is the evidence for Prompt A: you deliver the matrix, not a promise.

📊 The six sections of the report

  • 1.Versions and roots: claude, codex, polyskill, counts per folder, whether a native import exists.
  • 2.Skills: how many on both sides, how many only in Claude, and the matrix line by line.
  • 3.Commands, subagents, hooks, plugins, runbooks, CLAUDE.md, memory: destination and classification of each one.
  • 4.Codex hooks today: which events already have a handler.
  • 5.MCP: names registered on each side, no values.
  • 6.Not run: the reminder that this is an inventory, not proof.

💻 Extract only what you need

Goal: pull the list of adapter skills out of the report to plan the MCPs.

grep '| adaptador |' relatorios/auditoria-<data>.md | cut -d'|' -f2
# avatar-heygen-nei, heygen-cli, heygen-mcp, espiona-ads, ...

How to verify: the list has 15 names on this machine. Replace <data> with the date of your report.

💡 Practical tip

Once I had the audit summary adding up to 94 when the gap was 89. The grep was counting lines from section 3 (subagents, hooks) together with section 2. Smallest fix: restrict the grep to section 2.1. It is in FALHAS.md as "prompt". If your numbers do not add up, suspect the counter before you suspect the data.

Key concepts

Evidence

Dated file that anyone can reread.

No secrets

The report cites MCP names, never keys.

Not run

Inventory is not a test; the proof comes in 2.5.

Diff between runs

Compare reports to measure real progress.

Self-check (optional): the audit classified a skill as "reusable". What does that guarantee?

🎯 Module summary

✓
Clone the kit — six scripts, prompts and template, no global install.
✓
doctor.sh — ok, warning or missing; exit code for automation.
✓
audit.sh and the matrix — 89 only in Claude: 72 reusable, 15 adapter, 2 native, 1 unresolved.
✓
Sandbox and report — the bwrap failure and its one-line fix; the report is evidence, not proof.

Next module:

2.2 — CLAUDE.md → AGENTS.md: portable on one side, residue on the other

← Back to the Track Next module →