AgentSkillsCN

section-merger

将 `sections/` 下的各小节文件以确定性的方式合并至 `output/DRAFT.md`，同时保留大纲顺序，并从 `outline/transitions.md` 中融入过渡语句。 **触发条件**：合并小节、合并草稿、整合各小节文件、sections/ -> output/DRAFT.md、合并小节、拼接草稿。 **适用场景**：当您在 `sections/` 下拥有各单元的散文式文件，并希望生成一份用于润色、评审或 LaTeX 编译的单一 `output/DRAFT.md` 时，可使用此技能。 **若跳过**：如果小节文件缺失，或其中仍含有支架标记（请先修复 `subsection-writer`）。 **网络环境**：无需联网。 **行为准则**：仅进行确定性合并（不引入新事实或引用）；务必保留 `outline/outline.yml` 中的小节顺序。

SKILL.md
--- frontmatter
name: section-merger
description: |
  Deterministically merge per-section files under `sections/` into `output/DRAFT.md`, preserving outline order and weaving transitions from `outline/transitions.md`.
  **Trigger**: merge sections, merge draft, combine section files, sections/ -> output/DRAFT.md, 合并小节, 拼接草稿.
  **Use when**: you have per-unit prose files under `sections/` and want a single `output/DRAFT.md` for polishing/review/LaTeX.
  **Skip if**: section files are missing or still contain scaffolding markers (fix `subsection-writer` first).
  **Network**: none.
  **Guardrail**: deterministic merge only (no new facts/citations); preserve section order from `outline/outline.yml`.

Section Merger

Goal: assemble a paper-like output/DRAFT.md from:

  • •sections/ (per-section/per-subsection prose)
  • •outline/transitions.md (short hand-offs; generated by transition-weaver)
  • •outline/tables_appendix.md (reader-facing Appendix tables; generated by appendix-table-writer)

Merge order is driven by outline/outline.yml. The draft title is taken from GOAL.md when present. sections/sections_manifest.jsonl is an optional diagnostics input.

This skill is deterministic: it does not rewrite content or invent prose; it only merges already-generated artifacts.

Transitions (injected text)

  • •By default, section-merger inserts only within-chapter H3->H3 transitions.
  • •Optional: if you want between-H2 transitions inserted too, create outline/transitions.insert_h2.ok in the workspace.
  • •Format contract: only lines matching - 3.1 -> 3.2: <text> are injected by default.
  • •Compatibility: → is accepted, but -> is the preferred contract (avoids control-character encoding issues).
  • •Treat transitions as injected draft text: run post-merge-voice-gate after merging, and route fixes back to outline/transitions.md (do not patch the merged draft).

Tables (two layers)

This pipeline uses two table layers:

  • •

    outline/tables_index.md (internal index; produced by table-filler)

    • •planning/debugging artifact
    • •should NOT be inserted into the paper
  • •

    outline/tables_appendix.md (reader-facing Appendix tables; produced by appendix-table-writer)

    • •publishable tables (clean layout + high information density)
    • •inserted by section-merger under a single Appendix heading

Appendix insertion behavior

  • •section-merger inserts outline/tables_appendix.md at the end of the draft under ## Appendix: Tables.
  • •The inserted block is heading-free (any accidental # headings inside the tables file are stripped).
  • •Opt-out (rare): create outline/tables.insert.off in the workspace.

Inputs

  • •outline/outline.yml (drives section/subsection order)
  • •outline/transitions.md (required)
  • •sections/sections_manifest.jsonl (optional diagnostics)
  • •GOAL.md (optional title)

For arxiv-survey pipelines (default contract):

  • •outline/tables_appendix.md (required unless opted out)

Outputs

  • •output/DRAFT.md
  • •output/MERGE_REPORT.md

Script

Quick Start

  • •python .codex/skills/section-merger/scripts/run.py --help
  • •python .codex/skills/section-merger/scripts/run.py --workspace workspaces/<ws>

All Options

  • •--workspace <workspace_dir> (required)
  • •--unit-id <id> (optional; used only for runner bookkeeping)
  • •--inputs <a;b;c> (optional; override inputs; defaults are profile-aware)
  • •--outputs <draft_rel;report_rel> (optional; defaults to output/DRAFT.md;output/MERGE_REPORT.md)
  • •--checkpoint <C#> (optional; ignored by the merger)

Examples

  • •

    Merge with defaults (profile-aware table insertion):

    python .codex/skills/section-merger/scripts/run.py --workspace workspaces/<ws>

  • •

    Merge with explicit outputs:

    python .codex/skills/section-merger/scripts/run.py --workspace workspaces/<ws> --outputs output/DRAFT.md;output/MERGE_REPORT.md

Troubleshooting

Issue: merge report says a subsection file is missing

Likely cause:

  • •A required sections/*.md file has not been written yet.

Fix:

  • •Write the missing units under sections/ (typically via subsection-writer) and rerun merge.

Issue: Appendix tables are missing in the merged draft

Fix:

  • •Ensure outline/tables_appendix.md exists and contains >=2 Markdown tables (no placeholders).
  • •Ensure you did not create outline/tables.insert.off.
  • •Rerun section-merger.