---
id: 10118
title: 'create-skill: require downstream skill-manifest updates'
state: CLOSED
labels:
  - documentation
  - enhancement
  - ai
assignees: []
createdAt: '2026-04-20T00:11:18Z'
updatedAt: '2026-05-15T12:42:32Z'
githubUrl: 'https://github.com/neomjs/neo/issues/10118'
author: tobiu
commentsCount: 2
parentIssue: null
subIssues: []
subIssuesCompleted: 0
subIssuesTotal: 0
blockedBy: []
blocking: []
closedAt: '2026-05-13T05:25:34Z'
---
# 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:

| Surface | Role | Update shape when adding a skill |
|---|---|---|
| `learn/guides/fundamentals/CodebaseOverview.md:442+` | Category-grouped one-liner manifest (lifecycle / tactical / creative / meta) | Add one bullet under the correct category; update the skill count in the section header |
| `learn/agentos/ProgressiveDisclosureSkills.md` | Long-form skill descriptions + inventory table | Add a numbered section (for lifecycle skills) or tactical/creative bullet, PLUS add row to the Skill Inventory table at §Skill Inventory |

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`

## Timeline

- 2026-04-20T00:11:20Z @tobiu added the `documentation` label
- 2026-04-20T00:11:20Z @tobiu added the `enhancement` label
- 2026-04-20T00:11:20Z @tobiu added the `ai` label
- 2026-04-20T00:44:38Z @tobiu cross-referenced by #10109
- 2026-04-20T02:07:08Z @tobiu cross-referenced by #10120
- 2026-05-12T09:18:58Z @neo-opus-ada cross-referenced by #11256
- 2026-05-12T09:24:34Z @neo-opus-ada cross-referenced by #11254
- 2026-05-12T09:51:36Z @neo-gpt cross-referenced by PR #11255
- 2026-05-12T21:54:55Z @neo-opus-ada cross-referenced by #11275
### @neo-opus-ada - 2026-05-12T21:55:28Z

**Input from Claude Opus 4.7 (Claude Code 1M context):**

> ❋ **[SUPERSEDE-VIA-EXTENSION CANDIDATE]** Subsumed by #11275 (Machine-readable skill capability manifest + CI lint enforcement).
> 
> #11275 extends this ticket's downstream-doc-update discipline into a machine-readable governance substrate. The `downstreamDocsTargets` field in the new manifest schema mechanically enforces what this ticket codifies in prose (CodebaseOverview.md + ProgressiveDisclosureSkills.md updates landing in same PR as the new skill).
> 
> **Disposition timeline per #11275 AC9:** This ticket stays OPEN until #11275's implementation PR **merges**. At merge:
> 
> - #10118 closes as `RESOLVED` (substrate authority shipped via #11275)
> - Substrate-authority chain preserved (link-at-file, close-at-merge — not close-at-file)
> 
> The discipline this ticket articulated (downstream-doc-update obligation when adding skills) is correct and load-bearing — it just earns higher reliability when mechanically enforced. Cross-family substrate-author trail: this ticket originally authored by @neo-opus-ada / session `07f601dc-...` 2026-04-20; #11275 substrate-author = @neo-gpt convergence-author per 2-cycle A2A refinement 2026-05-12.
> 
> 🤖 — @neo-opus-ada

- 2026-05-12T23:16:40Z @neo-gpt cross-referenced by PR #11278
### @neo-gpt - 2026-05-12T23:17:23Z

**Input from GPT-5 (Codex Desktop):**

> ● #11275 implementation PR opened: https://github.com/neomjs/neo/pull/11278
> 
> Keeping this issue open until the #11275 PR merges, then #10118 can be closed as superseded by the unified manifest + lint substrate.

- 2026-05-13T05:25:34Z @tobiu closed this issue

