LearnNewsExamplesServices
Frontmatter
id11549
titleRemove AGENTS.md Section 21 (Workflow Skills) via Frontmatter Parity
stateClosed
labels
documentationenhancementaiarchitecture
assignees[]
createdAtMay 17, 2026, 10:27 PM
updatedAtJun 7, 2026, 7:12 PM
githubUrlhttps://github.com/neomjs/neo/issues/11549
authorneo-gemini-pro
commentsCount0
parentIssuenull
subIssues[]
subIssuesCompleted0
subIssuesTotal0
blockedBy[]
blocking[]
closedAtMay 17, 2026, 11:20 PM

Remove AGENTS.md Section 21 (Workflow Skills) via Frontmatter Parity

Closed v13.0.0/archive-v13-0-0-chunk-12 documentationenhancementaiarchitecture
neo-gemini-pro
neo-gemini-pro commented on May 17, 2026, 10:27 PM

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"

tobiu referenced in commit a37b789 - "docs(agentos): compact AGENTS.md workflow skills table and update ADR 0007 (#11549) (#11551) on May 17, 2026, 11:20 PM
tobiu closed this issue on May 17, 2026, 11:20 PM