🌐 Subagents in Codex and other environments

Think of a power outlet. The device is the same; the adapter changes depending on the country. The principle (110/220 V, one plug) doesn't change — what changes is the fit. A subagent is the same: the principle—“delegate to an isolated context, receive a summary”—is universal. What changes from one environment to another is the fit: where the file lives, what the frontmatter is called, the tool names. The goal of this module is to write a single .md and plug it into two runtimes.

↑ One source .md; each runtime applies its own adapter. The idea is the same — the fit changes.

Everything you’ve learned so far — a maestro who delegates, a dedicated context window, a clean report — describes a default, not a product. The pattern is: "a large task becomes a subprocess with its own context; only the conclusion comes back". Every serious agent tool needs something like this, because the problem (context filling up, work repeating) is universal. That's why the concept transfers.

O Codex CLI (OpenAI’s terminal agent) has the same components, just with different terminology. Where Claude Code says “subagent” and “skill,” Codex talks about prompts e agents Markdown that you save in a folder and invoke. The structure is the same: an instruction file + a trigger + a set of permitted tools.

Instead of maintaining two copies (one for Claude, one for Codex) that drift apart over time, you write one source only and “emits” each runtime's version from it. That's the idea behind a polyskill: one .md portable is the template, and each environment is a build of that mold. One truth, multiple destinations — the opposite of copy and paste.

The tools have different names, but the capabilities are the same: read a file, search text, list paths, edit, run shell commands. Instead of naming the exact tool in the body of your .md, describe the capability ("read the files", "search by default") — that way, the same text works in both, because each runtime resolves which specific tool to use.

Before porting, define the boundary. The principle — delegate to an isolated context, one role per agent, return a summary — it works intact across any environment. What changes is the shell: field names, folder, invocation syntax, available tools. Knowing what stays stable keeps you from rewriting what was already right.

Porting is a three-step process: extract the core, swap the shell, test parity. But portability has limits: not everything crosses the boundary. Things tightly coupled to a runtime — an exclusive MCP, a specific tool name, a model from just one provider — don't travel and become a adaptation note.

Here's a doc-summarizer.md written to be portable: the frontmatter is the shell from Claude Code, and the body is the core tool-agnostic. Right after that, the adaptation note shows what to change to run the same file in Codex CLI.

--- # CASCA (Claude Code) — troca por runtime
name: doc-summarizer
description: Lê documentos longos e devolve um resumo
  curto com os pontos-chave. Use para condensar
  arquivos grandes sem encher o contexto.
tools: Read, Grep, Glob   # só leitura
model: haiku             # barato p/ escanear
---

# MIOLO (portável) — NÃO cita ferramenta por nome
You are a precise document summarizer.

When invoked:
1. Read the target documents and grasp the intent.
2. Search for the key claims, numbers and decisions.
3. Write a summary: 5 bullets, then the source paths.

Output: only the summary. Do not paste raw
content. Do not modify any file.

Three prompts to port and cross-run. The pattern is always the same: ask it to preserve the core, adapt shell, and leave a note where portability ends.

Pegue este subagente do Claude Code e adapte para o
Codex CLI. Mantenha o corpo (papel/passos/saída) intacto,
troque só a casca: pasta, frontmatter e invocação. No fim,
liste uma "nota de adaptação" com o que não é portável.

Reescreva esta skill como fonte portável: remova nomes
de ferramenta específicos do corpo e descreva a capacidade
("leia", "busque"). Depois emita dois builds — um para
Claude Code, um para Codex — a partir da mesma fonte.

Liste as ferramentas que este .md usa no Claude Code
(Read, Grep, Glob, Bash…) e me dê o equivalente de shell
para o Codex. Aponte quais não têm equivalente direto e
precisam virar nota de adaptação.

This is how a cross-runtime build appears in the terminal: you run the emitter once on the portable source, and it generates the files for each environment—adapting the shell while keeping the core. Notice the two destinations branching from the same SKILL.md.

↑ Illustrative recreation of the terminal (not a real screenshot). One source goes in; two builds come out with the same core and different shells.