skill-quality/plugin-philosophy: aihero course lane 8: invocation-mode doctrine and evidence-driven fleet re-grade

[kyle-sexton]

Context

Steering-section extension of the AI Hero course vetting effort — contract in docs/topics/pocock-course-lanes/PLAN.md (branch claude/plan-mode-discussion-55kszx); lanes 1–6 are #2899–#2904; sibling steering lane is #2909. Owns the third gap from the 2026-08-17 writing-for-agents re-evaluation: invocation-choice doctrine is absent, and our de facto posture is the opposite of upstream's default, with neither ever argued.

Fleet reality (measured 2026-08-17): 211 top-level skills — 137 disable-model-invocation: false, 17 missing the key entirely, 57 true (almost entirely the setup skills plus a few maintainer-only skills). The setup convention is enforced by convention, documented nowhere. The skill-quality:check listing-budget instrument measures the aggregate description cost, but no decision rubric exists for choosing a skill's invocation mode. Upstream's SKILL-MECHANICS.md default is the inverse: user-invoked unless the agent must reach the skill autonomously or another skill needs it. The router-skill pattern was rejected only as the ask-matt port ("marketplace shape differs") — never evaluated as a pattern for our 57+ user-invoked skills.

Session decision (user-confirmed 2026-08-17): evidence-driven rubric. Neither upstream's user-invoked default nor our model-invoked default is assumed correct. The rubric weighs: autonomous-reach need, cross-skill reach (invocation-reach invariant), real trigger-hit evidence, listing-budget data, cognitive load on the human, and surface coverage.

Evidence that must feed the rubric:

• Upstream issue Root cause for #366: Claude Code coordinator mode drops user-invoked skills (upstream issue filed) mattpocock/skills#693: Claude desktop/web surfaces drop user-invoked skills from the listing — materially weakens any user-invoked-default posture for this marketplace
• Cloud/remote scope: remote sessions never load ~/.claude user scope, so user-level personal skills don't travel — project/marketplace skills are the only steering that reaches cloud sessions (user-raised, steering-section session)
• Invocation-reach invariant (SSOT tracked strand): a disable-model-invocation: true skill is unreachable from any other skill; substance landed unreleased upstream via PRs feat(planning): route incumbency-driven plan-review findings to incumbent mode #878/feat(typos-format): per-file typos autofix hook plugin #880 (.agents/invocation.md). Verify against current official Claude Code docs and record the disposition
• This marketplace is a multi-repo product: consumers won't memorize 211 skill names — discoverability may be the product, which cuts against upstream's solo-operator default

Scope constraint: ADR 0005 (bound instruction-surface work by question, not population). Shape as rubric-first + question-bounded application, not an unbounded 211-skill sweep. Reconcile with docs/topics/context-engineering-claude-5/ prior art (its design/skill-inventory.md population-derivation traps and the discipline:sweep-all router precedent).

Proposed work

• Open with /planning:interview me per contract; lane discusses and decides — implementation leaves as filed work items
• Write the invocation-mode decision rubric and pick its one home (PLUGIN-PHILOSOPHY component stances, a convention-registry owner doc, or playbooks:skill-authoring — decide, don't duplicate)
• Document the existing setup-skill convention (currently undocumented)
• Decide the 17 skills missing the disable-model-invocation key (explicit value or documented default)
• Evaluate the router-skill pattern on its merits (cognitive-load relief for user-invoked skills; claude-ops:inventory and docs/SKILL-CHEAT-SHEET.md as existing partial answers)
• Apply the rubric question-bounded (e.g. per plugin or per workflow stage), using skill-quality:check listing-budget before/after as the measurement
• Verify and disposition the invocation-reach invariant tracked strand

Acceptance criteria

• Adopt/reject-with-reason/track-on-event decision rows in docs/upstream/aihero-course.md for lessons 3 (What Are Agent Skills), 4 (Write A Skill — invocation half), 5 (User Vs Project Skills, incl. the cloud-scope caveat)
• Rubric written, homed in exactly one place, and cross-linked from the surfaces that need it
• Setup-skill convention documented; 17 missing-key skills decided
• Router-skill pattern verdict recorded (adopt/reject-with-reason)
• Invocation-reach invariant verified against official docs; SSOT tracked-strand disposition recorded
• Fleet re-grade scoped and either executed question-bounded or filed as follow-on work items

References

• docs/upstream/mattpocock-skills.md — decomposition table + tracked strands
• Upstream SKILL-MECHANICS.md (Invocation / Splitting by invocation / Router skills) and .agents/invocation.md (PRs feat(planning): route incumbency-driven plan-review findings to incumbent mode #878/feat(typos-format): per-file typos autofix hook plugin #880, unreleased)
• Root cause for #366: Claude Code coordinator mode drops user-invoked skills (upstream issue filed) mattpocock/skills#693 (harness finding, recorded in SSOT)
• docs/adr/0005-bound-instruction-surface-work-by-question-not-population.md
• docs/topics/context-engineering-claude-5/design/skill-inventory.md

Metadata

Field	Value
Category	unspecified
Area	skill-quality, docs (philosophy, conventions), all plugins (fleet)
Ecosystem	unspecified

[kyle-sexton]

Lane 8 closed per its acceptance criteria (interview-first per contract; register gate clean 8/8, brief=ok; user-confirmed). Artifacts on claude/pocock-steering-course-00zkvd @ 7f69664d.

Acceptance criteria:

• ✅ Decision rows (lessons 3, 4-invocation, 5) — recorded in docs/topics/pocock-course-lanes/STEERING.md "Lane 8 decision rows" (8 rows, incl. the L5 cloud-scope caveat), staged for lane 6's aihero-course.md harvest per the chain's standing decision (that file stays lane 6's deliverable).
• ✅ Rubric written, homed in one place — docs/conventions/invocation-mode/README.md: model-invoked default + three exception classes (side-effect/manual-timing, setup, maintainer-only), evidence axes (incl. Root cause for #366: Claude Code coordinator mode drops user-invoked skills (upstream issue filed) mattpocock/skills#693 and cloud scope); convention-registry row + PLUGIN-PHILOSOPHY cross-refs (setup contract, Instruction economy); playbooks:skill-authoring pointer rides skill-quality/fleet: enforce the invocation-mode rubric — explicit disable-model-invocation on 17 skills, check criterion, skill-authoring pointer #2968.
• ✅ Setup convention / 17 missing keys — the "documented nowhere" premise was stale at filing: PLUGIN-PHILOSOPHY "Setup is explicit and repeatable" (landed 967db56c) already documents it; rubric class (ii) cross-references it. The 17 missing-key skills: normalize to explicit false + new skill-quality:check explicit-key criterion → skill-quality/fleet: enforce the invocation-mode rubric — explicit disable-model-invocation on 17 skills, check criterion, skill-authoring pointer #2968.
• ✅ Router verdict — REJECT with reason (under the model-invoked default the always-present listing is the router; the true set is deliberately model-invisible). Human-side answer: docs/SKILL-CHEAT-SHEET.md + claude-ops:inventory. Domain-scoped composition routers (discipline:sweep-all) remain an admitted distinct pattern.
• ✅ Invocation-reach invariant — CONFIRMED against current official docs (2026-08-17, quotes recorded); SSOT strand dispositioned: upstream-release trigger retired, audit-side trigger kept; the rubric owns the cross-skill-reach axis.
• ✅ Fleet re-grade (ADR 0005-bounded) — one question, executed in-lane: the 10 non-setup true skills graded against the exception classes → 9 KEEP, 1 FLIP (planning:questionnaire → planning: flip questionnaire to model-invoked — the one invocation-mode re-grade flip #2969). The 47 setup skills are class (ii) by contract; the 137 false skills were not swept.

Contract: docs/topics/invocation-mode-doctrine/PLAN.md. Follow-ons: #2968 (enforcement), #2969 (flip). Next lane: #2911.

---

Generated by Claude Code