create-skill: require downstream skill-manifest updates

Context

PR #10116 (ticket-create skill, merged today) caught that 5 skills were missing from the learn/guides/fundamentals/CodebaseOverview.md skill manifest (ticket-intake, pull-request, whitebox-e2e, memory-mining, debugging-antigravity) and required a separate polish commit to complete the inventory. The root cause is not neglect — the current create-skill meta-skill says nothing about downstream-doc updates when a new skill is added. Every previous skill author who followed the guide correctly would still have missed these surfaces.

Evidence of drift compounding: the CodebaseOverview list's header previously claimed "12 files, ~300 lines" while enumerating only 7. Multiple past skill additions silently diverged the documentation ecosystem from the .agent/skills/ directory.

The Problem

.agent/skills/create-skill/references/skill-authoring-guide.md covers:

• Folder structure (§Skill Folder Structure)
• Router / SKILL.md conventions (§1)
• Payload / references conventions (§2)
• Verification checklist (§Verification — 4 items on YAML, body, absolute paths)

It is silent on the two downstream manifest surfaces that must be updated in lockstep:

• learn/guides/fundamentals/CodebaseOverview.md — short-form skill list categorized by lifecycle / tactical / creative / meta. Every skill gets one bullet.
• learn/agentos/ProgressiveDisclosureSkills.md — long-form skill descriptions + inventory table. Lifecycle skills additionally get a numbered section with their trigger/purpose.

Silent documentation obligations produce silent drift. The fix is to make them explicit.

The Architectural Reality

Two downstream surfaces, differing in depth:

The SKILL.md router stays lightweight (per §Core Concepts) — downstream doc updates happen to the two learn-folder guides, not the skill file itself.

The Fix

Update .agent/skills/create-skill/references/skill-authoring-guide.md:

1. Add a new §3 Downstream Manifest Updates between §2 Writing the Payload and §Verification, explaining the two surfaces with their exact paths, update shapes, and categorization conventions.
2. Extend the §Verification checklist with two items:
   • [ ] CodebaseOverview.md skill list updated (correct category; header count incremented)
   • [ ] ProgressiveDisclosureSkills.md updated (inventory table row + numbered section for lifecycle skills)

No changes to SKILL.md itself (router stays lightweight) — downstream-doc logic is reference-level guidance.

Acceptance Criteria

• skill-authoring-guide.md has a new §3 documenting the two downstream surfaces with paths + update shapes + category conventions
• §Verification checklist contains the two new items
• A subsequent skill addition (e.g., future tech-debt-radar refactor, or any new skill) demonstrably updates both surfaces with no reviewer prompt

Out of Scope

• Backfilling every historical missing entry — already done for CodebaseOverview in #10116; ProgressiveDisclosureSkills was already mostly complete
• Automating the downstream-doc update (e.g., a CI lint that diffs .agent/skills/ against the two manifests) — worth a separate ticket if the guidance alone fails to hold the invariant
• Updating the create-skill SKILL.md router — would bloat the router; reference-level guidance is the right substrate

Avoided Traps

• Putting the downstream-doc instructions in SKILL.md: violates the Progressive Disclosure core principle (router must stay lightweight). Reference-level is correct.
• Automating via CI lint instead of documenting: premature. The doc-level nudge needs to be proven insufficient before code-level enforcement is justified.
• Adding a third downstream surface "just in case": no evidence of another surface that should be synced. Stick to the two confirmed manifests.

Related

• Surfaced during: #10116 / #10104 (ticket-create skill PR); CodebaseOverview.md polish commit required because the skill list was stale
• Sibling meta-skill: .agent/skills/create-skill/
• Downstream surfaces to be documented: learn/guides/fundamentals/CodebaseOverview.md, learn/agentos/ProgressiveDisclosureSkills.md

Origin Session ID

07f601dc-353a-44d2-a373-18da2a0d305a