session-compound

Session Compound

Compress a single CLI session into an offline-openable HTML report (written to /tmp, not saved into the project repository). The report has four tabs:

• Narrative — what was done this time (timeline + key feedback moments + narrative summary written by the Agent)
• Health — token / cache / tool usage diagnostics
• Evaluation — neutral workflow facts panel + instruction-following / skill recall / per-skill execution evaluation findings from an independent subagent
• Compound — playground: candidate item list on the left (checkable + inline editing), live-synthesized markdown on the right, one-click copy of the "prompt" at the bottom, paste back into Claude / Codex to let the agent persist it according to the rules

When to use

• The user asks to "review / summarize / distill / wrap up" the current session
• The user explicitly invokes /session-compound or a similar command
• The user wants to extract AGENTS.md / docs/rules/ additions, ready-to-use reusable skills, or abstractable skill gaps from this session

Do notuse for cross-session analysis—that is the scope of the session-report plugin (last 7 days × all projects).

---

Workflow

Step 1: Run the analyzer

First determine the CLI identity (read the environment variable CLAUDE_CODE_SESSION_ID or CODEX_THREAD_ID; whichever matches is the side), then execute the corresponding branch.

Claude Code branch

node <skill-dir>/analyzers/claude-code.mjs > /tmp/session-compound.json

<skill-dir> is the absolute path of the directory containing this SKILL.md.

The script automatically infers CLAUDE_CODE_SESSION_ID via the ~/.claude/projects/<cwd-slug>/<session-id>.jsonlenvironment variable + the current cwd. Optional override:

• --session-id <uuid> — specify the session id
• --project-slug <slug> — specify the cwd slug (overrides automatic inference)
• --file <abs-path> — directly specify the JSONL file path

Runtime requires Node 18+ (the script uses node:fs / readline namespace import).

Codex branch

node <skill-dir>/analyzers/codex.mjs > /tmp/session-compound.json

The script reads the thread id from the CODEX_THREAD_ID environment variable, then locates the file under ~/.codex/sessions/**/rollout-*-<thread-id>.jsonl(and ~/.codex/archived_sessions/**/ fallback). Optional override:

• --thread-id <uuid> — specify the thread id (--session-id is its alias)
• --file <abs-path> — directly specify the rollout JSONL file path

General constraints

If the analyzer exits non-zero, read stderr, fix the corresponding issue (wrong path, missing session, file not generated, etc.), and rerun.Do not proceed to subsequent steps without obtaining the JSON。

Step 2: Read the JSON summary

Read /tmp/session-compound.json. Focus on scanning these fields:

• session — id / cwd / duration / model / git;recorded_turn_ms is the sum of the real turn wall-clock durations recorded by the turn_duration entries in the log (when present, more accurate than the active_ms gap estimate)
• narrative.task_title — session title (on the Claude side taken from aiTitle, empty string if missing; on the Codex side taken from the first user message); the report hero title uses it
• narrative.human_turns — summary of each user turn + token + triggered tools
• narrative.feedback_moments — detected user corrections / direction-narrowing moments (including redirect signals such as "don't touch it for now / no rush / micro-optimization"; pure interrogative sentences are not counted)
• narrative.away_summaries — natural-language summaries written by Claude when the user was away (from away_summary entry, narrative raw material)
• health.tokens / health.cache_hit_rate / health.context_window_used_pct
• health.tools / health.subagents / health.skills(skills on both ends: on the Claude side from Skill tool calls, on the Codex side from <skill><name> block parsing; subagents include Claude Agent / Codex spawn_agent calls)
• health.skill_attribution — how many tool calls each skill drove (workload, semantically different from the call count of skills ; currently present on the Claude side, from attributionSkill）
• health.prs — list of PRs referenced in this session (deduplicated,{number,url,repository}; currently present on the Claude side, from pr-link）
• health.tool_failures — failed tool calls ({call_id,name,preview}, same shape on both ends)
• health.expensive_turns — turn with the highest token consumption
• health.waste_signals — waste signals such as repeatedly reading the same file, low cache hit rate, API errors / retries, etc.
• health.skill_catalog — all installed skill directories available on this machine ({name, description, editable}, deduplicated and folded by name for multi-version plugin caches;editable indicates the skill source is inside the current repo and can be optimized in place).Input for instruction-following & skill recall evaluation
• health.workflow_rules — workflow rules parsed from the managed blocks of the repo's AGENTS.md / CLAUDE.md ({n, text}); empty array if there are no managed blocks
• health.workflow_signals — neutral fact package, containing no verdicts（{git_branch, on_main, had_code_edit, first_edit_ts, prs_count, skills_invoked_count}). The mechanical layer only extracts facts; the judgments of instruction following / recall / skill executionare all delegated to the evaluation subagent
• raw_for_compound — raw material used to write candidate entries (including agent_invocations、tool_failures、skill_timeline、review_syntheses）
• raw_for_compound.skill_timeline — Skill invocation timeline ({ts, name} in invocation order; subagent sidechains and invocations without timestamps are excluded). Placing the timestamps of feedback_moments onto this timeline makes it possible to mechanically determine "which workflow stage was running when the user correction occurred"—this is the basis for categorizing experiences into docs/rules/{spec,arch,test}/ , and it is not lost after a long session is compacted
• raw_for_compound.review_syntheses — full text of deep-review's punch list ({ts, text}, matched outside code fences by output contract heading ## Deep Review: in main-conversation assistant messages—subagent and Codex commentary-stage messages have been filtered out; multiple reviews in the same session produce multiple entries; truncated to 6000 characters with an ellipsis appended). The primary raw material for review-type experiences (problem patterns that review should have caught)

of the two analyzer outputscore fields（session.{id,cwd,duration_ms,model,git,recorded_turn_ms} / narrative.{task_title,human_turns,feedback_moments,away_summaries} / health.{tokens,cache_hit_rate,tools,subagents,skills,skill_attribution,prs,tool_failures,expensive_turns,waste_signals,skill_catalog,workflow_rules,workflow_signals} / raw_for_compound.{feedback_moments,repeated_reads,agent_invocations,tool_failures,skill_timeline,review_syntheses}) are consistent; among them, the display fields are rendered by the template,skill_timeline / review_syntheses is agent-side raw material for steps 4.5 / 5d and does not enter template rendering. Beyond that, each side has CLI-specific extension fields: Codex has extra health.{compaction_count, turn_aborted_count, patch_apply, mcp_tool_call_count, custom_tool_call_count, web_search_count, tool_search_count, image_generation_count, context_window, reasoning_output_ratio} and narrative.{task_conclusion, task_completed, task_duration_ms, time_to_first_token_ms}; Claude has extra health.{api_calls, cache_breaks}. Note that skill_attribution / prs / away_summaries currently has data only on the Claude side (Codex logs have no equivalent signal), and the missing side is an empty set.skill_catalog / workflow_rules / workflow_signals exists on both ends, each constructed from the skill root directory of the respective CLI and the AGENTS.md in the session cwd (workflow_signals is a neutral fact, not a verdict). The template already handles these differences by CLI branch.

Step 3: Copy the template to the output file

The report is a one-off artifact—write it to /tmp, do not put it in the project directory, to avoid being tracked by git / accidentally committed into the user's repository.

cp <skill-dir>/template.html /tmp/session-compound-$(date +%Y%m%d-%H%M).html

Step 4: Pre-check ecosystem skills based on the data

Before writing candidates,firstIdentify 3–5 possible skill gap patterns from this session's data (repeatedly reading the same document, recurring tool combinations + failures, fixed multi-step process keywords appearing in long turns), generate a search query for each pattern, then run:

npx skills find "<query>" 2>&1 | head -30

Extract the top-3 results for each query (name / install_count / source URL).

Based on the returned results, make a verdict:

• recommend-install — find one or more existing skills with high install counts, just reuse them (no need to write skill-gap candidate）
• partial-match — there are related skills but the semantics don't fully match (in skill-gap candidate's find-skills check field, reference these results to prevent downstream agents from re-running)
• no-match — nothing reusable at all, write skill-gap candidate from scratch

The output of this stepgoes directly into the candidates array of the next step, 5d, but requires a special type existing-skill——any recommend-install verdict's results should be added to the array as a existing-skill candidate (the user checks it in the browser → after copying the prompt, the downstream agent will automatically run the npx skills add install).

Step 4.5: Dispatch an independent subagent to do instruction-following & skill-execution evaluation

Produce eval-findings(instruction following / recall / per-skill execution evaluation) → step 5e injects it into the report, and it can also feed 5d's skill-body candidates.For the full dispatch protocol (input checklist, output schema, skill-body placement rules), see references/eval-dispatch.md——read it before dispatching. Only the non-omittable hard constraints are listed here:

• Must use an independent subagent with zero context inheritance (fresh context): the session being evaluated is exactly the one the main Agent itself ran, so self-evaluation has systematic bias (same discipline as deep-review / test-designer: new session, no resume, do not copy the current conversation history into the subagent).
• Scope: recall / instruction following covers skill_catalog inall installed skills and all workflow_rules; per-skill execution eval only covers skills actually invoked / run in this session（health.skills in). The mechanical layer only provides workflow_signals neutral facts (branch / whether on main / whether there are edits / PR / skill invocation count),all judgments are made by the subagent——including verdicts like "edited on main" that were previously made by the mechanical layer.
• Output: finding array {kind, polarity, severity?, confidence, text, skill?}——polarity distinguishes positive (positive) from gap (gap),severity only gap is required (positive is omitted),confidence is evidence strength (see references/eval-dispatch.md for the output contract).Do not pre-filter by importance(report all in-scope findings; leave filtering to humans).

Step 5: Inject data + write the Agent fill-in section (use Edit, not Write——the template's JS/CSS must be preserved)

5 edits are needed:

5a. Replace <script id="report-data"> 's content

Replace this block's content with the complete JSON produced in step 1:

<script id="report-data" type="application/json">
{ "cli": "claude-code", ... }
</script>

The template's JS will automatically render the hero, all tables, bars, and timeline from this JSON.

5b. Fill the <!-- AGENT: narrative-summary --> block

Replace this div:

<div id="narrative-summary" class="empty-hint">No summary yet — ...</div>

with:

<div id="narrative-summary">这里写 ≤3 句话的会话叙事摘要</div>

Summary requirements:Factual. Cite real turn content, real decisions, real tool patterns—no boilerplate.

5c. Fill in the <!-- AGENT: anomalies --> block

Replace the placeholder hint inside <div class="takes" id="anomalies">...</div> with 3–5 take cards. Express values as "% of total tokens" wherever possible. Exact markup:

<div class="take bad"><div class="fig">62%</div><div class="txt">Turn <b>#4</b> 一个 prompt 消耗了 62% 的总 token</div></div>

class meanings:

• .take.bad — waste / red
• .take.good — healthy signal / green
• .take.warn — warning / yellow
• .take.info — neutral fact / blue

.fig is a short number (%, count, or 12× multiple)..txt is a plain-language sentence, with the subject wrapped in <b> .

Angles worth exploring:

• A single turn took a disproportionate share
• Cache hit < 85% (Claude) or reasoning accounts for > 50% of output (Codex)
• Reading the same file over and over
• Sub-agent calls have no output format constraint
• Context window approaching its limit (Codex)

5d. Fill in the <script id="candidates"> array (the core value of this skill）

Replace the [] in that script tag with the array of candidate entries. Each candidate belongs to one of the following three categories—only these three：

1. existing-skill — a ready-made ecosystem skill found by the step 4 pre-check; a single npx skills add command installs it
2. agent-md — written into the AGENTS.md system (root AGENTS.md / docs/rules/<topic>.md + index / consumer-bound docs/rules/{spec,arch,test,review}/ / subdirectory AGENTS.md; pick one per the target table below)
3. skill-gap — a multi-step repeatable pattern with no ready-made reusable option in the ecosystem, worth abstracting into a new skill

Schema：

[
  {
    "name": "kebab-case-name",
    "type": "existing-skill | agent-md | skill-gap",
    "body": "条目正文 markdown——直接落库的文本（或对 existing-skill 来说，含安装命令）",
    "default_selected": true
  }
]

type semantics

• existing-skill — a ready-made ecosystem skill found during the step 4 pre-check, with verdict recommend-install. Body template:

  **来源**: <owner/repo@skill> · <NK installs> · <skills.sh URL>
  **解决的本会话问题**: <为什么这个 skill 适合本会话出现的某个模式>
  **安装命令**: `npx -y skills add <owner/repo@skill> -a codex claude-code -y`
  

  Install command breakdown:

  • npx -y — -y comes first, so npx auto-upgrades / pulls the package and skips the "need to install? (y/N)" prompt
  • -a codex claude-code — skills add 's -a collects all subsequent non-flag arguments, sospace-separatedmultiple agents. This repository targets only these two agents
  • at the end, -y — skills add 's own "yes to confirmation prompts" after checking it, it enters the synthesized prompt, and the downstream agent automatically runs the npx skills add install

• agent-md — commit to the AGENTS.md system.The target is determined by this skill itself and given as a recommendation in the candidate; do not throw the choice back to the user or the downstream for another round of decision-making.

  Before choosing a targetfirst survey the existing instruction organization conventions of the current project—do not apply generic defaults:

  1. Read the root AGENTS.md / CLAUDE.md: it is usually anentry + index, relying on multiple levels of files for progressive disclosure (the root file stays lean, detailed specifications are split out into docs/ topical files / subdirectory instruction files).Do not pile content into the root AGENTS.md—follow its existing layered structure.
  2. Check whether docs/rules/ and the like already have a topical file covering this area; if so,expand within that file, rather than creating a parallel one.
  3. Determine whether the experienceis bound to a certain workflow stage——docs/rules/ has four consumer-boundconsumer bindingsdirectories, which are mechanically read by the corresponding skill at fixed stages:docs/rules/spec/（spec-design collected during the research stage),docs/rules/arch/（arch-design as a hard design constraint),docs/rules/test/（test-designer dispatch packet + deep-review test-quality reviewers),docs/rules/review/（deep-review custom reviewers that are automatically discovered and dispatched). Experiences that fall into these directories will bethe stage where the mistake was madeautomatically injected into the corresponding agent's context, whereas the root AGENTS.md can only hope to be remembered—experiences that can be categorized by stage should preferentially be placed in the corresponding directory.
  4. Check the project'sexisting skills to see whether this pattern is already covered—if it is merely that a skill's guidance is inadequate / missing a rule,prefer to optimize in place in that skill's SKILL.md file(with target pointing to that skill file), which is lighter and more aggregated than adding an AGENTS.md section or creating a new skill.

  Choose the target according to the table below (prefer reusing / extending existing files; only consider creating new ones as a last resort):

  Experience scope	target	When to choose
  An existing skill's guidance can be improved	That skill's SKILL.md(optimize in place)	The pattern is already covered by a skill, but a rule is missing / triggering is inaccurate—most aggregated, choose first
  Experience bound to a workflow stage(spec clarification omissions / architecture constraints / testing conventions)	docs/rules/spec/、docs/rules/arch/、docs/rules/test/ topic file under (extend an existing one or create a new one; no root AGENTS.md index line is needed—consumers discover it automatically by directory)	The experience corresponds to spec-design / arch-design / test-designer / test-quality's fixed consumption point, and takes effect automatically the next time work is done at the same stage
  Review-dimension experience(problem patterns that review should have caught)	Extend the existing docs/rules/review/<name>.md 's Checklist / worked scenarios;for an entirely new dimension, it is recommended to run reviewer-creator, do not create one by hand	docs/rules/review/ files carry the frontmatter orchestration contract and are deep-review automattically discovered and dispatched—hand-created files lacking orchestration metadata can only take the degraded path of relying on semantic guessing
  Existing docs/rules/<topic>.md already covers this domain	Extend in that file (do not create a parallel file)	There is already a topic file, add along with it
  Repository-wide / cross-language / workflow-level (short rules)	Root AGENTS.md（CLAUDE.md if it is a symlink, write only in one place)	Short, all future sessions should see it, and the root file has no more suitable subordinate home
  Repository-wide butthe content is long(>10 lines / tables / code)	Create docs/rules/<topic>.md + root AGENTS.md add an index line	Writing it into the root AGENTS.md would bloat it and break progressive disclosure
  Only for a specific standalone subdirectory (plugin / package / service)	That subdirectory's AGENTS.md(create it if it does not exist)	The experience only takes effect in that subdirectory's context; writing it to the root would pollute the global scope

  Body template (the target line must givea specific recommended destination + whether it is "optimize an existing file in place" or "create new"):

  **target**: <具体路径>（如 `<skill>/SKILL.md` 就地优化 / 现有 `docs/rules/<topic>.md` 扩写 / 根 `AGENTS.md` / 新建 `docs/rules/<topic>.md` + 索引 / `<subdir>/AGENTS.md`）
  **落点理由**: <一句话：为什么是这个文件——已有 X 覆盖该领域 / 顺着现有分层 / 根文件无更合适下级>
  **要写入的内容**:
  > <逐字给出要追加 / 修改的段落，下游 agent 复制粘贴即可>
  **索引行**（仅当新建通用 `docs/rules/<topic>.md` 时填；消费方绑定目录 `docs/rules/{spec,arch,test,review}/` 下的文件不填——对应 skill 按目录自动发现）:
  > - [<title>](docs/rules/<topic>.md) — <一句 hook>
  

• skill-gap — in this session there appeareda multi-step repeatable pattern, which is worth abstracting into a new skill. The body must contain: trigger phrases / find-skills check results / an imperative 3–5 step process / bundled resources / verification method (see the template below)

Decision table

Form of experience	Where to record it
The ecosystem already has a matching skill	existing-skill(cheapest)
The project's existing skill already covers it, but the guidance is inadequate	agent-md → optimize that skill in place at its SKILL.md(most consolidated, preferred)
Dimensions that should have been clarified at the spec stage but were missed, causing rework	agent-md → docs/rules/spec/ topic file (expand or create new)
Architectural constraints that were violated / disputed (layering, dependency direction, module boundaries)	agent-md → docs/rules/arch/ topic file (expand or create new)
Test design conventions / fixture conventions / flaky patterns	agent-md → docs/rules/test/ topic file (expand or create new)
Problem patterns that review should have caught	agent-md → expand the existing docs/rules/review/<name>.md; for a brand-new dimension → recommend running reviewer-creator
The existing docs/rules/<topic>.md already covers this area	agent-md → expand in that file
Cross-session workflow constraints / process rules (short text)	agent-md → root AGENTS.md (when there is no more suitable lower level)
Cross-session long-form conventions (>10 lines / tables / code)	agent-md → create new docs/rules/<topic>.md + root AGENTS.md index
Conventions that only affect a specific subdirectory	agent-md → <subdir>/AGENTS.md
Multi-step, repeatable, with trigger conditions, requiring script assistance	skill-gap(new skill)
One-off / upstream tool issue / outside the user's control	Do not write candidate

Destination priority (from most consolidated to heaviest):Optimize an existing skill in place / expand existing docs → a suitable position in the existing hierarchy → a short rule in the root AGENTS.md → create a new topic file → create a new skill. Reuse existing structure first; create new only as a last resort.

Sources of raw material for classification and filing

• Stage classification(spec / arch / test): use raw_for_compound.skill_timeline to map each feedback_moment timestamp onto the skill stage active at that time—corrections received while spec-design is in progress are mostly spec-type experience, and corrections during the test stage are mostly test conventions. Do not classify by impression alone; long sessions' memories may already have been compacted.
• Review-type experience: the primary raw material is raw_for_compound.review_syntheses(the full punch list from the deep-review main Agent);health.prs when non-empty, then use gh pr view <number> --comments Pull the review comments on that PR—consume both human review and CI automated review (bot review, check conclusions) together. Problems that only get discovered by users after passing review, or the same kind of finding repeatedly pointed out in review, are direct evidence of "patterns review should have caught".

skill-gap A candidate must prove itself "worth making into a skill"

Refer to the judgment framework of skill-development skill; only write when all 5 hard gates below are satisfied skill-gap：

1. Multi-step: can be split into ≥3 steps, with order/dependency between steps
2. Repeatable: very likely to happen again in future sessions (one-off cases are not written as candidates)
3. Can write a third-person + specific trigger phrase—this is the hard specification for the skill description, and also an implicit sanity check: if you cannot write "This skill should be used when the user asks to \"X\", \"Y\"", it means the trigger scenario is not clear and it is not worth making into a skill
4. Bindable resources: requires scripts/(deterministic script) / references/(documentation loaded on demand) / assets/(output template). Pure text rules go into agent-md more lightly
5. No existing skill in the ecosystem can be reused—checked with npx skills find <query> before producing the candidate (this is the core action of find-skills skill)

Counterexamples (these should not be written as skill-gap）：

• "The user prefers writing spec first, then implementing" → single rule → write as agent-md(one line in the root AGENTS.md)
• "In the lingolens project, the question type components are named *Question, not *Player" → subdirectory-scoped convention → agent-md（<subdir>/AGENTS.md）

Positive examples (these can be made into skills):

• "Before e2e verification, first check the dev server / database / dependency state machine" → multi-step checklist + bindable script → skill-gap
• "When adding a new question type component: first create *Question.tsx, then add unit tests, then register with the router, then write the mobile preview" → 4-step fixed process → skill-gap

skill-gap Body template (the agent fills this in when writing a candidate, covering all 5 hard gates):

**触发短语**（第三人称 + 具体短语，自证 gate #3）：
> This skill should be used when the user asks to "<具体短语 1>", "<具体短语 2>", or mentions <场景>.

**find-skills 检查**（自证 gate #5，用 `npx skills find <query>`）：
- 已搜：<keyword>
- 结果：无现成可复用 / 找到 `<owner/repo@skill>` 但 <理由不合适>

**3–5 步流程**（imperative，verb-first；遵循 skill-development 写作规范）：
1. Verb …
2. Verb …
3. Verb …

**Bundled resources**（自证 gate #4）：
- `scripts/<name>.sh` — 做 <X>
- `references/<name>.md` — 提供 <Y> 的细节
- `assets/<name>/` — <Z> 模板（可选）

**验证**：跑 `<command>` 应该看到 <expected>；失败时检查 <fallback>。

**为什么不是 `agent-md`**：本条满足 5 条 hard gate（多步骤 + 可重复 + 触发清晰 + 资源可绑定 + ecosystem 没现成的）；写成 AGENTS.md 段落无法承载脚本和多步骤逻辑。

After the downstream agent receives this kind of skill-gap candidate, it should go through skill-creator the complete process (capture-intent → interview → draft → eval → iterate),do not directly write SKILL.md on the spot——skill-creator will ensure that skill-development specifications such as description trigger rate, imperative style, and progressive disclosure (SKILL.md ≤2k words, details split into references/) are followed.

Raw material

From JSON's raw_for_compound: feedback moments, repeated file reads, sub-agent calls, turn timeline.narrative.feedback_moments user feedback snippets in it (≤200-character summary) are usually the starting point for agent-md candidates—if a piece of feedback appears repeatedly, it is a workflow-level rule.human_turns The repeated tool combinations + failure patterns in it are clues for skill-gap .

Step 4.5's eval-findings is also candidate raw material—especially kind: skill-eval findings (some skill performs poorly):

• When a finding points toeditable in this repository SKILL.md（skill_catalog in editable: true that entry), and the problem is that the skill body is not written well enough, produce a agent-md candidate,target points directly at that in-repo SKILL.md to optimize in place (consistent with the decision table's "the project's existing skill already covers it, it's just that the guidance is inadequate"). This is precisely the entry point for "countering the tendency to blindly pile on content": first determine whether the body itself is poorly written, rather than defaulting to adding rules.
• Forexternal / cached, non-editable（editable: falseskills,do not produce edit candidates—their source is in the plugin cache, and any changes will be overwritten on the next update; just report their performance in the "Instruction Following and Skill Evaluation" section of the report's "Evaluation" tab.

Quality standards.

Better fewer than too many.3–8 high-value candidates beats 20 mediocre candidates. Don't write the obvious ones—keep only those thatsome future sessionwill actually use.skill-gap has the highest bar; producing 0–2 per run is enough.

Before each agent-md candidate is written into the array, it must pass threeveto gates(if any one is hit, don't write it):

1. Ongoing rent: once a rule lands in AGENTS.md / docs/rules/ , every relevant dispatch pays the context cost—this is permanent rent, not a one-time writing cost. Only problems that "will recur on every write and can't be caught downstream" can afford this price; one-off friction and low-frequency coupling are not recorded.
2. Already backstopped by an existing mechanism: if the problem is precisely something caught by existing review / tests / hooks, that means the mechanism is already working, and writing another rule is redundant supply.
3. The mechanism can substitute, and the earlier the interception point, the better: for constraints that can be locked down with a zero-rent mechanism (one that doesn't enter the agent context), write the candidate as an in-place change pointing to that mechanism, not as a prompt rule. Choose the mechanism by interception point from earliest to latest, at theearliest feasiblelevel: lint / type system / static check (caught the moment the code is written) → local tests (caught at verification) → CI / hook (caught at push)—the later the interception, the longer the fix loop, and agent review on CI costs another round of tokens and human effort. Choose the mechanism form that isnative to the engineering tech stack(e.g., TypeScript's ESLint custom rules / type constraints, Swift's swiftlint, schema validation, this repo's node:test text assertions for the markdown contract); only fall back to the next level when implementing a given level in that tech stack is clearly too costly.

Experience vetoed by the gates is not necessarily discarded: if the substance is a code defect, write a fix candidate (with target pointing at the problematic source file); for things worth tracking but out of scope for this run, suggest recording them in the PR's Remaining TODOs or an issue.

5e. Fill in the <script id="eval-findings"> array

Write the finding array returned by the step 4.5 independent subagent into the <script id="eval-findings"> block (the default is []）：

<script id="eval-findings" type="application/json">
[{ "kind": "recall", "severity": "high", "confidence": "med", "text": "...", "skill": "..." }]
</script>

The template renders it into the "Instruction Following and Skill Evaluation" section of the "Evaluation" tab; if the array is empty, that section is automatically hidden (no empty shell is shown).Inject the subagent's output verbatim; do not re-filter or reword it here—pre-filtering is already prohibited by dispatch discipline.

Step 6: Open the report

Open the report for the user, and also report the absolute path under /tmp .Prefer the built-in browserto open file://<绝对路径>— Built-in browser tools differ across Agents; use whichever one the current Agent has available; when there is no built-in browser, fall back to system commands (macOS open <path> / Linux xdg-open <path>）。Do notprerender candidates (leave checking them to the user),Do notcopy the report into the project repository (it is a one-off artifact). The user checks items in the Compound tab, edits the wording inline, clicks Copy, and pastes the generated prompt back to the Agent; with that one sentence, persistence is complete.

---

Notes

• Write skill-gap / agent-md Before writing candidates of this type, it is strongly recommended to first run an ecosystem search with find-skills (npx skills find <query>, candidate gate #5); when creating a new skill, write it according to the skill-development conventions (third-person description, imperative body, progressive disclosure: SKILL.md ≤2k words + references/ + scripts/ + assets/, validation checklist),skill-gap each field of the body template corresponds to a specific requirement of that convention
• The template JS reads only three script blocks:<script id="report-data">(analyzer output),<script id="candidates">(the candidates you wrote),<script id="eval-findings">(the evaluation findings from the independent subagent in step 4.5). All other rendering is driven by these three blobs.Do not change the HTML structure。
• The Compound tab is the core value that distinguishes this skill from an ordinary session report—it turns "AI extracts candidates → human reviews → persist into AGENTS.md / install skill / create skill" into a frictionless closed loop.
• Codex has native sub-agents (spawn_agent / wait_agent / close_agent tool calls), and the analyzer aggregates agent_type into health.subagents. Codex also supports skills (the$skill-name command, injected in logs as <skill><name> blocks), which the analyzer parses and fills into health.skills, in the same shape as on the Claude side.
• Codex's health section additionally contains:compaction_count(number of automatic compactions),patch_apply.{success, failure}(code modification success/failure ratio),mcp_tool_call_count / custom_tool_call_count / web_search_count / tool_search_count / image_generation_count and other specialized tool counts, as well as context_window(model window size).
• If raw_for_compound is very sparse (short session, no feedback moments), it is better to produce 1–3 high-quality skill-gapthan to force 5 items.
• If the JSON exceeds 2MB, truncate narrative.human_turns and health.expensive_turns to the first 50 entries before embedding (the analyzer usually already handles this, but check).