---
id: 11549
title: Remove AGENTS.md Section 21 (Workflow Skills) via Frontmatter Parity
state: CLOSED
labels:
  - documentation
  - enhancement
  - ai
  - architecture
assignees: []
createdAt: '2026-05-17T20:27:03Z'
updatedAt: '2026-06-07T17:12:56Z'
githubUrl: 'https://github.com/neomjs/neo/issues/11549'
author: neo-gemini-pro
commentsCount: 0
parentIssue: null
subIssues: []
subIssuesCompleted: 0
subIssuesTotal: 0
blockedBy: []
blocking: []
closedAt: '2026-05-17T21:20:51Z'
---
# Remove AGENTS.md Section 21 (Workflow Skills) via Frontmatter Parity

## 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. 
1. **Token Budget Drain:** This table consumes significant byte-budget against the strict 24KB Context Window Truncation limit.
2. **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
1. Patch the frontmatter descriptions for `ideation-sandbox` and `tech-debt-radar` to include their missing edge-case triggers.
2. Fully delete `## 21. Workflow Skills (when to invoke)` from `AGENTS.md`.
3. 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
- [ ] `ideation-sandbox/SKILL.md` frontmatter updated to include Step 2.5 Architectural Step-Back trigger.
- [ ] `tech-debt-radar/SKILL.md` frontmatter updated to include the PR review hook trigger.
- [ ] `AGENTS.md` `## 21. Workflow Skills` is 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
- 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
- ADR 0007

Origin Session ID: d1aee218-8c42-4562-b2ec-f597284fa9d7
Handoff Retrieval Hint: "AGENTS.md section 21 workflow skills frontmatter compaction"

## Timeline

- 2026-05-17T20:27:03Z @neo-gemini-pro added the `documentation` label
- 2026-05-17T20:27:04Z @neo-gemini-pro added the `enhancement` label
- 2026-05-17T20:27:04Z @neo-gemini-pro added the `ai` label
- 2026-05-17T20:27:04Z @neo-gemini-pro added the `architecture` label
- 2026-05-17T20:34:34Z @neo-gemini-pro cross-referenced by PR #11551
- 2026-05-17T20:53:29Z @neo-gemini-pro referenced in commit `6f5882f` - "chore(skills): restore exact trigger parity for create-skill and turn-memory-pre-flight (#11549)"
- 2026-05-17T20:58:58Z @neo-gemini-pro referenced in commit `520633d` - "docs(agentos): restore explicit trigger parity for pull-request and pr-review skills (#11549)"
- 2026-05-17T21:07:46Z @neo-gemini-pro referenced in commit `c7ad645` - "refactor(docs): adjust AGENTS.md section numbering after compaction (#11549)"
- 2026-05-17T21:20:51Z @tobiu referenced in commit `a37b789` - "docs(agentos): compact AGENTS.md workflow skills table and update ADR 0007 (#11549) (#11551)

* docs(agentos): compact AGENTS.md workflow skills table and update ADR 0007 (#11549)

* docs(agentos): address parity gate review feedback for SKILL frontmatters and manifest

* chore(skills): restore exact trigger parity for create-skill and turn-memory-pre-flight (#11549)

* docs(agentos): restore explicit trigger parity for pull-request and pr-review skills (#11549)

* refactor(docs): adjust AGENTS.md section numbering after compaction (#11549)

* docs: align ADR 0007 taxonomy table with new contiguous numbering

---------

Co-authored-by: neo-gemini-3-1-pro <neo-gemini-3-1-pro@users.noreply.github.com>"
- 2026-05-17T21:20:51Z @tobiu closed this issue

