Machine-readable skill capability manifest + CI lint enforcement

Context

Convergence of two operator-surfaced ideas (memory-mined this session): (1) "meta router skill" framing and (2) "JSON definition for capping files inside skills." Cross-family peer dialogue with @neo-gpt resolved both into a single machine-readable substrate.

• (1) "Meta router skill" was a category-error name for what's actually a skill discovery / capability manifest — currently fragmented across 5 surfaces (SKILL.md frontmatter / AGENTS.md §21 / ProgressiveDisclosureSkills.md / CodebaseOverview.md / harness symlinks) with no machine-readable single source of truth. /architecture-pre-flight is the umbrella router-of-uncertainty (shipped via Epic #11256); naming a separate meta-router skill would duplicate it and invite Map-vs-Atlas regression. The actual substrate-gap is governance metadata, not another skill.
• (2) JSON cap definition — adjacent prose-level discipline shipped (slot rule / disposition taxonomy / byte budget retrofit via #10760, per-harness measurement methodology via #10734, AGENTS.md compaction 3-axis slot rule via #10735, MCP-tool-description byte-budget audit via #10341, substrate-budget AC for substrate-mutation PRs via #11263). All enforcement is review-time discipline-only; reviewers can miss; no mechanical gate.

Substrate-author of convergence: @neo-gpt (delivered 2 substantive substrate-refinement cycles A2A: unified-shape proposal + 5 anti-bloat guardrails). Filer: @neo-opus-4-7 per cross-family AC-CycleE (Discussion #11265).

Authored by Claude Opus 4.7 (Claude Code 1M context). Session c2d47e91-625f-4ebf-b066-49442f465830.

The Problem

Discipline-only enforcement at PR review time fails empirically:

• Substrate-bloat cycle PR #11257 → PR #11261 → PR #11264: each PR shipped substrate-budget AC violations only surfaced by operator V-B-A; same-author corrective inherited same defects; cross-family corrective + 3 cycles caught the substrate-untruth. No mechanical gate would have prevented the first or second violation.
• Skill-discovery defects at graduation PR #11270 fixed missing triggers: frontmatter on /turn-memory-pre-flight + /architecture-pre-flight (Epic #11256 graduated 2 skills without enforcing trigger frontmatter completeness or .claude/skills/ symlink parity). No mechanical gate prevented shipping incomplete skill discovery surfaces.
• Tool-surface cap exhaustion this session: the Neural Link MCP server alone exposes 34 operations; combined with ~40 across the other 3 neo-mjs MCP servers + Claude-internal tooling, the 100-tool harness cap is fully consumed. No machine-readable inventory exists for "this MCP server's tool surface = N operations; consumes N/100 of any Claude-style harness budget."
• Manifest update silent drift #10118 (OPEN since 2026-04-20): adding a new skill requires updating CodebaseOverview.md + ProgressiveDisclosureSkills.md in lockstep. Discipline-only docs-prose; new skills land without manifest updates and reviewers miss the discipline.

Each gap is a different facet of the same root: agent-substrate governance is prose-discipline, not machine-enforced. Reviewers carry the load; reviewers miss; substrate drift accumulates.

The Architectural Reality

Current substrate-budget enforcement primitives, all shipped:

• .agents/skills/**/SKILL.md — frontmatter (name, description, triggers) is canonical runtime substrate; harness boot-discovers via this surface
• .agents/skills/create-skill/references/skill-authoring-guide.md §Byte Budget — 7-12 line empirical floor for SKILL.md routers (discriminator, not hard cap)
• learn/agentos/measurements/cognitive-load-baseline-2026-05.md — per-harness loaded-surface measurement methodology
• .agents/skills/pr-review/references/pr-review-guide.md §5.3 — MCP-tool-description budget audit (per-description, not per-server)
• Discussion #11259 → PR #11263 — substrate-budget AC for substrate-mutation PRs (loaded-context-neutral-or-reducing)
• learn/guides/fundamentals/CodebaseOverview.md + learn/agentos/ProgressiveDisclosureSkills.md — fragmented downstream skill manifests

What is missing: a single machine-readable skill capability manifest declaring, per skill: its frontmatter mirror (read-only authoritative), its governance metadata (budgets / downstream-doc targets / harness symlink mandate), and its v1 lint contract.

What is also missing: a CI lint that fails PR on cap violation / missing Claude symlink / missing downstream doc update.

The Fix

Add skills.manifest.json (or per-skill manifest.json — TBD at implementation) declaring per-skill governance metadata; populate one-shot for all 25 current skills; add ai/scripts/lint-skill-manifest.mjs invokable locally and from CI with --base <ref>; add a .github/workflows/skill-manifest-lint.yml workflow that runs the script on any .agents/skills/** PR change; update /create-skill skill to reference the manifest.

Schema shape (v1)

Contract Ledger Matrix

Acceptance Criteria

• AC1: Schema defined. skills.manifest.json schema documented in same PR; JSON Schema validation runnable.
• AC2: Source-of-truth direction. SKILL.md frontmatter is runtime-canonical for name/description/triggers; manifest mirrors are read-only check artifacts; lint asserts mirror matches frontmatter exactly. No bidirectional mirroring; frontmatter wins.
• AC3: Population. Per-skill manifest entries populated one-shot for all 25 current skills.
• AC4: Loaded-context boundary. Manifest is machine-readable CI artifact ONLY; never turn-loaded prompt substrate. AGENTS.md / SKILL.md additions pointer-sized or zero; substrate-reducing direction enforced via AC10.
• AC5: Lint script. ai/scripts/lint-skill-manifest.mjs accepts --base <ref> for local runs; CI invokes same script with --base origin/${{ github.base_ref }}. No GitHub-only check shape; same script local + CI.
• AC6: Lint failure modes. Lint fails PR on: (a) cap threshold violation (SKILL.md exceeds routerByteBudget); (b) missing .claude/skills/<name> symlink when claudeSymlinkRequired: true; (c) downstreamDocsTargets referenced in manifest but not updated in same PR (when skill added/renamed); (d) JSON schema validation failure; (e) frontmatter ↔ manifest mirror inconsistency.
• AC7: Relationship-field restraint. relationships field declared OPTIONAL / future-extension; zero v1 lint rules consume it; AC7 explicitly forbids v1 PRs touching its semantics. Anti-mini-atlas-creep guard.
• AC8: /create-skill skill referenced. skill-authoring-guide.md §Verification + §Skill Folder Structure reference the manifest as the canonical governance surface; downstream-doc discipline (currently §3 candidate per #10118) consolidates here.
• AC9: #10118 close-as-superseded timeline. This ticket's implementation PR comment-links #10118 at filing; #10118 closes-as-superseded only on this ticket's implementation PR merge (preserves substrate-authority chain).
• AC10: Substrate-budget compliance. Implementation PR is loaded-context-neutral or reducing per Discussion #11259 + PR #11263. Added substrate to machine-readable surfaces (manifest + lint + workflow) offset by simplification at prose-discipline surfaces (skill-authoring-guide.md byte-budget prose can compress since manifest mechanically governs).

Out of Scope

• LLM-based skill-quality scoring — out of scope; bytes/counts only in v1.
• Per-token semantic analysis — out of scope; byte-count substrate.
• Cross-server MCP tool-count governance — substantively adjacent (cap-exhaustion empirical anchor shows the need) but separate substrate. Future-extension ticket; not included here.
• Migration of existing skills' frontmatter — handled at population-time (AC3) not as standalone migration.
• Mechanical enforcement of relationships field — explicitly out-of-AC v1 per AC7.

Avoided Traps / Gold Standards Rejected

• Naming as "meta-router skill" — category error per @neo-gpt convergence: would duplicate /architecture-pre-flight (shipped via Epic #11256) and invite Map-vs-Atlas regression. The actual gap is governance metadata, not another skill.
• Manifest content INSIDE SKILL.md — defeats purpose; would expand frontmatter into a mini-atlas. Manifest is separate machine-readable surface; SKILL.md frontmatter stays minimal (name/description/triggers).
• Skill-shaped substrate — this is machine-substrate, not a SKILL.md + atlas. No .agents/skills/skill-manifest/ directory; manifest is configuration substrate alongside skill substrate.
• Bidirectional unstated mirroring — frontmatter and manifest must NOT both be authoritative. AC2 explicitly: frontmatter authoritative, manifest mirrors. Lint enforces one-way consistency.
• CI-only enforcement (no local lint) — AC5 explicitly: same script runnable locally + CI. Authors verify before push; reviewers verify on diff; no GitHub-environment-coupled enforcement.
• Closing #10118 at this ticket's filing — substrate-authority chain requires close-as-superseded happen at merge not at file. AC9 explicit.

Related

• Discussion #11252 (substrate-placement / /turn-memory-pre-flight) — Layer 1 substrate-evolution context
• Discussion #11253 (architecture-pre-flight umbrella) — closes the "meta-router skill" category-question; this ticket is the parallel manifest substrate
• Discussion #11259 → PR #11263 (merged) — substrate-budget AC for substrate-mutation PRs (review-time discipline); this ticket adds mechanical enforcement
• Discussion #11265 (FAIR ticket/PR split) — Layer 1 skill-substrate-health durable target; this ticket operationalizes the mechanical-enforcement half of Layer 1
• #10760 (slot rule + disposition taxonomy + byte budget; CLOSED) — prose-discipline shipped; this ticket mechanically enforces
• #10734 (per-harness loaded-surface measurement methodology; CLOSED) — measurement substrate
• #10735 (AGENTS.md compaction 3-axis slot rule; CLOSED) — adjacent substrate
• #10341 (MCP-tool-description byte-budget audit; CLOSED) — per-description discipline; adjacent to (but distinct from) per-server tool-count governance flagged as future-extension
• #10118 (downstream-doc-update discipline; OPEN since 2026-04-20) — subsumed-via-extension on this ticket's implementation PR merge per AC9
• PR #11257 / #11261 / #11264 — substrate-bloat cycle empirical anchors (NOT "merged" — PR #11257 CLOSED-as-superseded; PR #11261 CLOSED-as-superseded; PR #11264 OPEN CHANGES_REQUESTED at time of filing)
• PR #11270 — skill discovery repair (missing trigger frontmatter + Claude symlinks at Epic #11256 graduation); empirical anchor for claudeSymlinkRequired field
• Epic #11256 — Proactive architecture-decision substrate parent (related context; not subsumed)

Origin Session ID

c2d47e91-625f-4ebf-b066-49442f465830 (Claude Opus 4.7 / Claude Code 1M context, 2026-05-12 recovery session; substrate-author = @neo-gpt convergence-author per 2-cycle A2A refinement; filer = @neo-opus-4-7 per cross-family AC-CycleE rotation discipline)

Handoff Retrieval Hints

• Semantic: query_raw_memories(query: "machine-readable skill capability manifest JSON cap CI lint substrate-budget enforcement")
• Empirical: gh pr view 11270 --json files (skill-discovery-repair empirical anchor for claudeSymlinkRequired)
• Prior implementation pattern: git show 7d06d60b0 (Epic #11256 multi-skill ship pattern), git show 9213f9a5a (substrate-evolution PR pattern with multiple cross-substrate touches)
• Cross-skill reference: view_file .agents/skills/create-skill/references/skill-authoring-guide.md §Byte Budget + §Verification (prose-discipline this ticket mechanically enforces)
• A2A convergence trail: search Memory Core for messages re: "unified manifest" / "Lane 1 + Lane 2 unify" / "skill capability manifest" — substrate-author trail @neo-gpt 2026-05-12 ~20:17Z + ~20:22Z