Context
PR #11421 and #11424 (Phase B description-router hardening) and compaction efforts have successfully populated the description frontmatter for all Anthropic-style Progressive Disclosure skill routers (.agents/skills/**/SKILL.md). These descriptions are parsed and natively injected into the turn-based memory environment (as seen in the "Available skills:" section of the system prompt).
The Problem
AGENTS.md currently contains ## 21. Workflow Skills (when to invoke), a large markdown table that duplicates these triggers.
- Token Budget Drain: This table consumes significant byte-budget against the strict 24KB Context Window Truncation limit.
- Substrate Philosophy Violation: By packing high-density execution rules (e.g., merge-gate restatements, Evidence Audit rules) into the table's "Trigger condition" column, we are violating ADR 0007's "Map vs. World Atlas" discipline. The
AGENTS.md file should be a low-density routing Map, not a high-density cheat sheet. Agents must read the actual SKILL.md payload (the Atlas) for execution instructions.
The Architectural Reality
A deep Verify-Before-Assert (V-B-A) analysis confirms that the skill router frontmatter descriptions are already at parity or stronger than the AGENTS.md table for almost every skill.
The only identified gaps are:
ideation-sandbox: Frontmatter is missing the auto-fire trigger for "§5.2 Step 2.5 Architectural Step-Back on high-blast-radius proposals before [RESOLVED_TO_AC] / [GRADUATED_TO_TICKET] graduation".
tech-debt-radar: Frontmatter is missing the explicit trigger "During PR review for fundamental architectural shifts".
(Note: pr-review lacks the highly-compressed rule cheat-sheet in its frontmatter, but removing it enforces the intended discipline of making the agent read the SKILL.md instead of relying on a summarized cheat-sheet).
The Fix
- Patch the frontmatter descriptions for
ideation-sandbox and tech-debt-radar to include their missing edge-case triggers.
- Fully delete
## 21. Workflow Skills (when to invoke) from AGENTS.md.
- Update ADR 0007 (Compaction Taxonomy) to document this final phase of the Map vs. Atlas compaction victory.
Contract Ledger Matrix
| Target Surface |
Source of Authority |
Proposed Behavior |
Fallback |
Docs |
Evidence |
AGENTS.md §21 |
ADR 0007 |
Delete section entirely |
Rely on native skill-loading |
ADR 0007 updated |
V-B-A shows parity in frontmatter |
Acceptance Criteria
Out of Scope
- Altering the behavior or execution logic of any skills.
- Changing the
turn-memory-pre-flight mechanism.
Avoided Traps
- Trap: Keeping the table as a "cheat sheet". Rejected because it violates ADR 0007 (Map vs Atlas) and consumes critical 24KB headroom. If an agent needs the rules, they must
view_file the SKILL.md.
Related
Origin Session ID: d1aee218-8c42-4562-b2ec-f597284fa9d7
Handoff Retrieval Hint: "AGENTS.md section 21 workflow skills frontmatter compaction"
Context
PR #11421 and #11424 (Phase B description-router hardening) and compaction efforts have successfully populated the
descriptionfrontmatter for all Anthropic-style Progressive Disclosure skill routers (.agents/skills/**/SKILL.md). These descriptions are parsed and natively injected into the turn-based memory environment (as seen in the "Available skills:" section of the system prompt).The Problem
AGENTS.mdcurrently contains## 21. Workflow Skills (when to invoke), a large markdown table that duplicates these triggers.AGENTS.mdfile should be a low-density routing Map, not a high-density cheat sheet. Agents must read the actualSKILL.mdpayload (the Atlas) for execution instructions.The Architectural Reality
A deep Verify-Before-Assert (V-B-A) analysis confirms that the skill router frontmatter descriptions are already at parity or stronger than the
AGENTS.mdtable for almost every skill. The only identified gaps are:ideation-sandbox: Frontmatter is missing the auto-fire trigger for "§5.2 Step 2.5 Architectural Step-Back on high-blast-radius proposals before[RESOLVED_TO_AC]/[GRADUATED_TO_TICKET]graduation".tech-debt-radar: Frontmatter is missing the explicit trigger "During PR review for fundamental architectural shifts". (Note:pr-reviewlacks the highly-compressed rule cheat-sheet in its frontmatter, but removing it enforces the intended discipline of making the agent read theSKILL.mdinstead of relying on a summarized cheat-sheet).The Fix
ideation-sandboxandtech-debt-radarto include their missing edge-case triggers.## 21. Workflow Skills (when to invoke)fromAGENTS.md.Contract Ledger Matrix
AGENTS.md§21Acceptance Criteria
ideation-sandbox/SKILL.mdfrontmatter updated to include Step 2.5 Architectural Step-Back trigger.tech-debt-radar/SKILL.mdfrontmatter updated to include the PR review hook trigger.AGENTS.md## 21. Workflow Skillsis deleted.learn/agentos/decisions/0007-agents-md-compaction-taxonomy.md(or equivalent ADR) updated to reflect the removal of the skills table from the Map.Out of Scope
turn-memory-pre-flightmechanism.Avoided Traps
view_filetheSKILL.md.Related
Origin Session ID: d1aee218-8c42-4562-b2ec-f597284fa9d7 Handoff Retrieval Hint: "AGENTS.md section 21 workflow skills frontmatter compaction"