Context
Epic #11558 requires live skill substrate to stop depending on positional §N references. Skills are a high-frequency agent-consumption surface, and many workflow failures originate from weak or stale skill pointers.
The Problem
Workflow skills and their references currently contain positional references into AGENTS.md, AGENTS_ATLAS.md, and other skill guides. Those references become stale or expensive to parse when compaction changes section positions.
The Architectural Reality
The active skill substrate lives under .agents/skills/**. Top-level SKILL.md files should remain lightweight routers; detailed workflow content belongs in references per the Progressive Disclosure pattern. This ticket migrates references, not skill shape or policy content.
The Fix
Migrate .agents/skills/** live references from positional §N anchors to the semantic anchors introduced by #11561 and governed by #11559. Use the lint guard from #11560 as merge evidence once available.
Discussion Criteria Mapping
- OQ1 runtime/protocol refs -> live skill refs migrate to semantic anchors.
- OQ4 semantic-name stability -> use stable explicit IDs / aliases.
- Step 2.5 path determinism -> skill refs resolve by semantic ID, not mutable position.
- Active/archive boundary -> only active live skill behavior references migrate in this partition.
Acceptance Criteria
Out of Scope
- Authoring new skills.
- Reworking skill trigger copy except where needed to replace stale positional refs.
- Migrating general documentation or ADR references.
Avoided Traps / Gold Standards Rejected
- Bulk rewriting skill prose for style is rejected; this ticket is a reference-identity migration.
- Adding more loaded bytes to top-level skill routers is rejected unless required for trigger correctness.
Related
Origin Session ID: 6e5b995a-c68e-4179-840c-a4cc48d449da
Retrieval Hint: ".agents/skills semantic anchors AGENTS.md AGENTS_ATLAS.md positional refs #11558"
Context
Epic #11558 requires live skill substrate to stop depending on positional
§Nreferences. Skills are a high-frequency agent-consumption surface, and many workflow failures originate from weak or stale skill pointers.The Problem
Workflow skills and their references currently contain positional references into AGENTS.md, AGENTS_ATLAS.md, and other skill guides. Those references become stale or expensive to parse when compaction changes section positions.
The Architectural Reality
The active skill substrate lives under
.agents/skills/**. Top-levelSKILL.mdfiles should remain lightweight routers; detailed workflow content belongs in references per the Progressive Disclosure pattern. This ticket migrates references, not skill shape or policy content.The Fix
Migrate
.agents/skills/**live references from positional§Nanchors to the semantic anchors introduced by #11561 and governed by #11559. Use the lint guard from #11560 as merge evidence once available.Discussion Criteria Mapping
Acceptance Criteria
.agents/skills/**live references to AGENTS.md / AGENTS_ATLAS.md use semantic anchors.SKILL.mdrouter files are not bloated; detailed explanation remains in reference files where appropriate.Out of Scope
Avoided Traps / Gold Standards Rejected
Related
Origin Session ID: 6e5b995a-c68e-4179-840c-a4cc48d449da Retrieval Hint: ".agents/skills semantic anchors AGENTS.md AGENTS_ATLAS.md positional refs #11558"