Context
Existing skill-anatomy substrate is documented across multiple locations:
.agents/skills/create-skill/SKILL.md + .agents/skills/create-skill/references/skill-authoring-guide.md (authoritative implementation guide)learn/agentos/ProgressiveDisclosureSkills.md (high-level overview)learn/guides/fundamentals/CodebaseOverview.md (cross-reference).agents/skills/skills.manifest.schema.json (machine contract)AGENTS.md §21 (trigger pointers)
No single authoritative source exists. Per ADR 0006 (ADRs as Graph-Queryable Entities), ADRs are the canonical authority substrate for first-class architectural decisions; per ADR 0005 §2.1, ADR_REQUIRED classification fires when a proposal defines a durable substrate-management framework, introduces a primitive, and decomposes into multiple sub-decisions. Skill anatomy meets all three criteria but has not yet been codified as an ADR (the substrate-truth predates the ADR-at-Graduation discipline ADR 0005 established).
Empirical anchor — PR #11424 Cycle-1→Cycle-4 cascade: the ticket #11422 body cited an Antigravity V-B-A finding ("only name and description fields from SKILL.md frontmatter are loaded into the agent context; the triggers: field is silently dropped") in paragraph 1, then pivoted to "We must KEEP the triggers: field to preserve the canonical repo tooling/docs contract" two paragraphs later — an un-V-B-A'd assertion. The premise-prescription drift survived 3 review cycles before operator-direct V-B-A surfaced it. A canonical ADR codifying skill-anatomy decisions would have been the V-B-A target during ticket-intake, catching the drift at source.
The Problem
Substrate-pillar skill-shape decisions live scattered across create-skill skill payload + adjacent docs + JSON schema. Cross-session future-agent V-B-A has no graph-queryable authority target. Future skill-shape friction (e.g., new harness arrives with different loading semantics) lacks a single amendment surface.
The Architectural Reality
Skills are a substrate-pillar primitive consumed by all 3 harnesses (Claude Code, Antigravity, Codex). The contract spans:
- Frontmatter shape — currently
name + description only (per PR #11424 corrective; triggers: field is dead substrate)
- Description-as-cross-harness-router — description carries trigger semantics inline (AGENTS.md §21 shape)
- Body shape — Map (always-loaded SKILL.md, minimal router) vs World Atlas (conditional
references/<file>.md payload)
- Optional substrate —
references/ for procedural-depth content, assets/ for templates/snippets
- Manifest contract —
.agents/skills/skills.manifest.json mirrors frontmatter + declares routerByteBudget + payloadBudget + claudeSymlinkRequired + downstreamDocsTargets
- Cross-harness semantics — Anthropic Progressive Disclosure standard; cross-harness symlink discipline for Claude (per existing
claudeSymlinkRequired field)
Per ADR 0005 §2.1 ADR_REQUIRED checklist:
- ✅ Defines durable substrate-management framework (skill primitive)
- ✅ Introduces primitive (Skill as cross-harness loadable substrate)
- ✅ Decomposes into multiple sub-decisions (6 surfaces above)
Per ADR 0006: ADRs are the canonical graph-queryable authority substrate for this class of decision.
Per ADR 0007 (Compaction Taxonomy): Map vs World Atlas split is the load-time discipline this ADR formalizes for the skill substrate specifically.
The Fix
File learn/agentos/decisions/0008-skill-anatomy-and-authoring-contract.md (or next available ADR number at PR-time) codifying:
- §1 Context — empirical anchor: PR #11424 cascade; substrate-pillar status of skills; absence of canonical authority pre-ADR
- §2 Decision — frontmatter shape (
name + description only) + description-as-router semantics + Map/Atlas body decomposition + manifest contract fields + cross-harness loading semantics
- §3 Consumer enumeration — 3 harnesses + DreamService graph (per ADR 0006 weighting) +
ticket-intake V-B-A target + create-skill implementation skill + future Sandbox skill-shape reasoning
- §4 Substrate Boundaries —
.agents/skills/ (skill files) + learn/agentos/ (ADR + ProgressiveDisclosureSkills.md) + AGENTS.md §21 (trigger pointers) + .agents/skills/skills.manifest.schema.json (machine contract) + lint scripts
- §5 Anti-Patterns —
triggers: field hallucination (the PR #11424 anchor); parent-directory symlink (per bootstrapWorktree.mjs rationale); cross-scope-bundling; Map bloat without Atlas extraction
- §6 Supersedes — absorbed substrate:
create-skill/references/skill-authoring-guide.md becomes implementation companion; ProgressiveDisclosureSkills.md becomes cross-reference doc; AGENTS.md §21 stays trigger-pointer-only
- §7 Open Questions — if any (e.g., per-harness loading-semantics differences, future schema evolution gates)
Implementation tasks for the picking-up agent:
- Draft ADR 0008 body sourcing from existing substrate + PR #11424 corrective truth
- Cross-link ADR 0008 from
create-skill SKILL.md as Source of Authority
- Cross-link ADR 0008 from
ProgressiveDisclosureSkills.md
- Cross-link ADR 0008 from
CodebaseOverview.md
- Status flow: Proposed → operator content-accuracy approval at merge → Accepted
Acceptance Criteria
Out of Scope
- Rewriting the
create-skill skill payload (downstream after ADR lands; this ticket only adds the Source-of-Authority cross-link)
- Sweeping skill-shape changes across
.agents/skills/ (PR #11424 ships in parallel; this ticket does not block on it)
- Per-harness SDK changes for skill loading (separate concern; if friction arises, ADR 0008 amendment cycle would govern)
- Documentation drift sweep across older guides (separate cleanup ticket if needed post-merge)
Avoided Traps / Gold Standards Rejected
- Generic React-component-shape parallels: Neo skills are cross-harness loadable substrate, not UI components; React-shape conventions misframe.
- "Just document in CLAUDE.md / CODEX.md": harness-local docs don't establish cross-harness authority. Memory Core graph queries need a canonical artifact per ADR 0006.
- Discussion-first Ideation Sandbox path: the substrate-truth is already V-B-A'd via PR #11424's empirical cascade; the topic is codification of established decisions, not architectural exploration. Per ADR 0005 §2.3 amended lifecycle, normal-ticket flow suffices. (Operator-confirmed this path: "new ticket if you agree.")
Empirical Anchors
- PR #11424 Cycle-1 → Cycle-4 cascade: premise-prescription drift in
#11422 body survived 3 review cycles; operator-V-B-A trail trace surfaced the substrate-truth (Discussion #11419 → ticket → PR). A canonical ADR would have been the V-B-A target at ticket-intake. Reference: PRR_kwDODSospM8AAAABADvn_w (my Cycle-4 corrective with empirical V-B-A documentation).
- Discussion #11419 Cycle 2.5 Antigravity V-B-A: "only
name and description fields from SKILL.md frontmatter are loaded into the agent context; the triggers: field is silently dropped."
- ADR 0005 §2.1 ADR_REQUIRED classification: 3/3 criteria met (durable framework + primitive + multi-sub-decision).
- ADR 0006 graph-queryability: this ADR depends on the graph-substrate ADR 0006 establishes.
- ADR 0007 Compaction Taxonomy: Map/Atlas split is the load-time discipline this ADR specializes for skills.
Related
- ADR 0005 — ADR-at-Graduation for Ideation Sandbox
- ADR 0006 — ADRs as Graph-Queryable Entities
- ADR 0007 — AGENTS.md Compaction Taxonomy
- PR #11424 — Phase B SKILL.md description-router-hardening (companion implementation; substrate-truth source)
- Ticket #11422 — Phase B (the sub-ticket whose premise-prescription drift surfaced the need)
.agents/skills/create-skill/ — implementation skill (consumer + downstream-update target)- Discussion #11419 — graduation source for ADR 0007 (adjacent substrate-pillar)
Origin Session ID
656c0935-0b3e-4b06-9b14-548524275859
Handoff Retrieval Hint
Memory query: "SKILL.md frontmatter triggers field is dead substrate — harnesses load description only" OR "PR #11424 Cycle-4 corrective premise-prescription drift". Cross-reference: ADR 0007 (Compaction Taxonomy) Map vs Atlas pattern for skill body decomposition.
Context
Existing skill-anatomy substrate is documented across multiple locations:
.agents/skills/create-skill/SKILL.md+.agents/skills/create-skill/references/skill-authoring-guide.md(authoritative implementation guide)learn/agentos/ProgressiveDisclosureSkills.md(high-level overview)learn/guides/fundamentals/CodebaseOverview.md(cross-reference).agents/skills/skills.manifest.schema.json(machine contract)AGENTS.md §21(trigger pointers)No single authoritative source exists. Per ADR 0006 (ADRs as Graph-Queryable Entities), ADRs are the canonical authority substrate for first-class architectural decisions; per ADR 0005 §2.1, ADR_REQUIRED classification fires when a proposal defines a durable substrate-management framework, introduces a primitive, and decomposes into multiple sub-decisions. Skill anatomy meets all three criteria but has not yet been codified as an ADR (the substrate-truth predates the ADR-at-Graduation discipline ADR 0005 established).
Empirical anchor — PR #11424 Cycle-1→Cycle-4 cascade: the ticket #11422 body cited an Antigravity V-B-A finding ("only
nameanddescriptionfields fromSKILL.mdfrontmatter are loaded into the agent context; thetriggers:field is silently dropped") in paragraph 1, then pivoted to "We must KEEP thetriggers:field to preserve the canonical repo tooling/docs contract" two paragraphs later — an un-V-B-A'd assertion. The premise-prescription drift survived 3 review cycles before operator-direct V-B-A surfaced it. A canonical ADR codifying skill-anatomy decisions would have been the V-B-A target during ticket-intake, catching the drift at source.The Problem
Substrate-pillar skill-shape decisions live scattered across
create-skillskill payload + adjacent docs + JSON schema. Cross-session future-agent V-B-A has no graph-queryable authority target. Future skill-shape friction (e.g., new harness arrives with different loading semantics) lacks a single amendment surface.The Architectural Reality
Skills are a substrate-pillar primitive consumed by all 3 harnesses (Claude Code, Antigravity, Codex). The contract spans:
name+descriptiononly (per PR #11424 corrective;triggers:field is dead substrate)references/<file>.mdpayload)references/for procedural-depth content,assets/for templates/snippets.agents/skills/skills.manifest.jsonmirrors frontmatter + declaresrouterByteBudget+payloadBudget+claudeSymlinkRequired+downstreamDocsTargetsclaudeSymlinkRequiredfield)Per ADR 0005 §2.1 ADR_REQUIRED checklist:
Per ADR 0006: ADRs are the canonical graph-queryable authority substrate for this class of decision.
Per ADR 0007 (Compaction Taxonomy): Map vs World Atlas split is the load-time discipline this ADR formalizes for the skill substrate specifically.
The Fix
File
learn/agentos/decisions/0008-skill-anatomy-and-authoring-contract.md(or next available ADR number at PR-time) codifying:name+descriptiononly) + description-as-router semantics + Map/Atlas body decomposition + manifest contract fields + cross-harness loading semanticsticket-intakeV-B-A target +create-skillimplementation skill + future Sandbox skill-shape reasoning.agents/skills/(skill files) +learn/agentos/(ADR + ProgressiveDisclosureSkills.md) +AGENTS.md §21(trigger pointers) +.agents/skills/skills.manifest.schema.json(machine contract) + lint scriptstriggers:field hallucination (the PR #11424 anchor); parent-directory symlink (perbootstrapWorktree.mjsrationale); cross-scope-bundling; Map bloat without Atlas extractioncreate-skill/references/skill-authoring-guide.mdbecomes implementation companion;ProgressiveDisclosureSkills.mdbecomes cross-reference doc; AGENTS.md §21 stays trigger-pointer-onlyImplementation tasks for the picking-up agent:
create-skillSKILL.md as Source of AuthorityProgressiveDisclosureSkills.mdCodebaseOverview.mdAcceptance Criteria
learn/agentos/decisions/NNNN-skill-anatomy-and-authoring-contract.md(NNNN = next available number)ticket-intake+create-skill+ future-Sandbox reasoningtriggers:field hallucination anchor (PR #11424 cascade), parent-symlink anti-pattern, cross-scope-bundling, Map bloatcreate-skillSKILL.md updated to cite ADR as Source of AuthorityProgressiveDisclosureSkills.mdupdated to cross-reference ADRCodebaseOverview.mdupdated to cross-reference ADROut of Scope
create-skillskill payload (downstream after ADR lands; this ticket only adds the Source-of-Authority cross-link).agents/skills/(PR #11424 ships in parallel; this ticket does not block on it)Avoided Traps / Gold Standards Rejected
Empirical Anchors
#11422body survived 3 review cycles; operator-V-B-A trail trace surfaced the substrate-truth (Discussion #11419 → ticket → PR). A canonical ADR would have been the V-B-A target at ticket-intake. Reference:PRR_kwDODSospM8AAAABADvn_w(my Cycle-4 corrective with empirical V-B-A documentation).nameanddescriptionfields fromSKILL.mdfrontmatter are loaded into the agent context; thetriggers:field is silently dropped."Related
.agents/skills/create-skill/— implementation skill (consumer + downstream-update target)Origin Session ID
656c0935-0b3e-4b06-9b14-548524275859Handoff Retrieval Hint
Memory query: "SKILL.md frontmatter triggers field is dead substrate — harnesses load description only" OR "PR #11424 Cycle-4 corrective premise-prescription drift". Cross-reference: ADR 0007 (Compaction Taxonomy) Map vs Atlas pattern for skill body decomposition.