Semantic Skill Discovery and the Optimizer Family

A technical paper for skill and prompt engineers working with a large skill hub

As-of: 2026-06-17. Scope: the ~/.claude/skills hub-and-spoke taxonomy, the skill hub’s tool surface, the role registry, the peer-deferral seeding mechanism, the skill-context token budget, and the four-member optimizer family (/sko, /pdo, /ddo, /cdo).

Grounding note. Every mechanism described here is taken from the actual skill definitions under ~/.claude/skills/ and from observed behavior of the live skill-hub tools (the recommend-skills, skill-search, role-resolution and prompt-optimizer tools). Where a claim could not be confirmed from those sources, it is marked [ASSUMED]. Primary sources are listed in the appendix.

Abstract

A large skill library creates a paradox: the more capabilities you install, the harder it becomes to surface the right capability at the right moment without drowning the model’s context window. The skill hub resolves this paradox with three coordinated systems. Discovery decides which of ~600 skills are relevant to a task, using relevance-ranked scoring with transparent match reasons rather than literal substring matching. Routing keeps that decision cheap by enforcing a hub-and-spoke taxonomy, a two-tier description-length cap, progressive disclosure, and deferred-tool loading — so the cost of considering a skill is a one-line description, not its full body. Optimization keeps each artifact production-grade through a family of four sibling optimizers (/sko for skills, /pdo for prompts, /ddo for documents, /cdo for code) that share one convergence-and-severity contract but diverge on their pass catalogs and, critically, on how each verifies that a fix is actually correct.

This paper documents each system in turn, contrasts relevance-ranked (“semantic”) discovery against simple keyword discovery and its failure modes, explains role-based auto-skill addition and peer-deferral seeding, quantifies the skill-context token budget and the techniques that defend it, and closes with a full pass-by-pass enumeration of /sko and a seven-dimension comparison of the four optimizers.

1. System overview: the three layers

The hub is best understood as three layers stacked beneath any task:

1. The skill tree — ~/.claude/skills/<id>/SKILL.md files organized as hubs (broad routers) and spokes (narrow references folded into a hub’s references/ directory). A hub earns its existence at roughly the ≥8-sibling threshold.
2. The discovery surface — the skill hub’s MCP tools, plus a UserPromptSubmit hook that pre-scores the incoming prompt against the registry and injects a role hint and candidate-skill list before the model even begins.
3. The optimizer family — meta-skills that audit and rewrite the artifacts of the system (skills, prompts, documents, code) to a measurable quality bar.

The design tension that shapes all three layers is context economy: the model can only act on what is in its context window, but everything in the window costs tokens and dilutes attention (“context rot”). Every mechanism below is, at bottom, a strategy for spending that budget well.

2. Semantic skill finding and skill discovery

2.1 What “finding a skill” means

When a task arrives, the system must answer: of the hundreds of installed skills, which few are relevant? The hub answers this with relevance-ranked discovery rather than asking the model to read every skill. Three surfaces participate:

• The recommend-skills tool (inputs: query, limit) — the primary discovery tool. It takes a prose description of the task and returns skills ranked by a relevance score (e.g. 0.9146), each annotated with the exact terms it matched (matchedKeywords) and a one-line human-readable reason. It is the “I don’t know the exact skill, score the field for me” tool.
• The skill-search tool (input: query) — a substring/metadata search that returns matches unranked. It is the “I already know the term, find the item” tool.
• The UserPromptSubmit hub-context hook — a pre-pass that runs before the model responds. On the prompt that generated this paper, it injected: [hub-context] This prompt matches the "Skill & Prompt Engineer" role (score 34). Consider loading the role's auto-skills … claude-code-skills, skill-optimizer, prompt-deep-optimizer, concept-family-explorer, deep-research. Call the role-resolution tool for the full merged set. This is the mechanism that makes discovery proactive — the candidate set is offered, not waited for.

Each recommend result also carries a contextPath (e.g. skills/contexts/skill-optimizer.md), indicating the registry indexes a per-skill context document in addition to the frontmatter fields.

2.2 What the score is built from

The observable inputs to the relevance score are the skill’s authored metadata: the description (the primary activation signal), keywords, triggers, whenToUse phrasings, tags, and the indexed context markdown. The score weights how strongly a query’s terms hit those fields and returns the top N. The transparency is the important part: because every result reports which words it matched on, the caller (human or agent) can audit the match and discard a spurious one — a capability that pure ranking opacity would deny.

On the word “semantic.” The tool surface exposes keyword matches and a numeric score, not vector distances. So what the prompt-engineering practice calls “semantic skill finding” is, observably, a field-weighted relevance ranker with match-reason transparency — strictly more capable than substring search, but whether it computes true embedding-based semantic similarity underneath is [ASSUMED] and not verifiable from the tool output alone. The practical contrast that matters (Section 3) holds regardless: ranked-with-reasons beats unranked-substring.

2.3 Discovery is recall; curation is precision

A recommender optimizes recall — it would rather surface a marginal skill than miss a relevant one. That makes a curation step mandatory downstream: the raw candidate list always over-includes. The /phe pipeline (Section 7) formalizes this: it queries the recommend-skills tool and the role-resolution tool, then applies a noise filter that reduces each candidate’s reason to the exact words it matched and drops any whose match is purely incidental. Discovery proposes; curation disposes.

3. Semantic (relevance-ranked) vs. simple keyword discovery

3.1 The two models side by side

3.2 Why simple keyword matching fails

Substring matching has no notion of what a word means in context, so it fires on stopword-like tokens that appear incidentally. Two real leaks observed in the hub illustrate the failure mode precisely:

• the token “methods” matching da-analytical-methods on a prompt about better methods of email access;
• the token “checking” matching python-static-type-checking on monitor for emails that need checking.

Neither of these skills had anything to do with the actual task. A pure keyword system surfaces both with equal confidence; a ranked system pushes them to the bottom and exposes that they matched only on a stopword, which is exactly the signal the noise filter uses to drop them.

This paper’s own discovery run is a live example. Running the recommend-skills tool on the request returned, alongside the genuine subjects (skill-optimizer 0.91, prompt-deep-optimizer 0.88, skill-tree-architect 0.74), three off-domain matches: multimodal-llm-architecture (matched “multimodal”, score 0.008), da-41-knowledge-graphs-and-semantic-analytics (matched “semantic”), and da-data-engineering-platform (matched “engineering”). The scores and match reasons made the noise obvious and removable; an unranked substring search would have presented them as peers of the real hits.

3.3 The lesson

Ranking with reasons does not eliminate noise — it makes noise legible and filterable. That is the entire value proposition of relevance-ranked discovery over keyword discovery, and it is why the system pairs every recommender call with a curation pass rather than trusting the raw list.

4. Role-based auto-skill addition

4.1 The mechanism

A role is a named persona in the skill hub’s registry with a fixed set of autoSkills that should load whenever that persona is active, regardless of the specific query. The tool is the role-resolution tool (inputs: role, query), and its key return field is matchVia:

• matchVia: "id" — the supplied role resolved to a registered role by exact id; the persona applies.
• matchVia: "recommend" — a free-text persona description was matched to a role by relevance; the persona applies.
• matchVia: "none" — no persona matched; ignore the role result entirely and fall back to query-only discovery.

When a persona applies, its autoSkills are merged into the candidate set tagged as role-level, and they survive curation even when their per-query score is weak — because they are justified by who is doing the work, not by what this specific task says.

4.2 Worked example: the “Skill & Prompt Engineer” role

Calling the role-resolution tool with the role skill-knowledge-engineer and this task returned:

role.id:       skill-knowledge-engineer
role.title:    Skill & Prompt Engineer
role.matchVia: id            ← persona applies
autoSkills:    claude-code-skills, skill-optimizer, prompt-deep-optimizer,
               concept-family-explorer, deep-research

Two of those autoSkills — concept-family-explorer and deep-research — barely matched the literal query text (source: "role", no query score). A query-only recommender would have dropped them. The role mechanism keeps them, on the theory that a skill-and-prompt engineer characteristically needs gap-discovery and research tooling on hand even when a given task doesn’t name them. This is the orthogonality that makes roles valuable: role resolution is independent of query relevance. Query discovery answers “what does this task need”; role resolution answers “what does this kind of operator always need.”

4.3 Why this beats query-only selection

Query-only selection is memoryless — it re-derives the toolset from scratch every prompt, so a persona’s standing tools blink in and out as the wording changes. Pinning them to the role makes the working set stable across a session and frees the query layer to do what it is good at: surfacing the task-specific additions on top of the persona’s fixed base. The hook’s pre-injection of the matched role (Section 2.1) means this stabilization happens before the model takes its first action.

5. Peer seeding: deferral edges between sibling skills

5.1 The problem it solves

Two skills with adjacent scopes will both score on a borderline query — a collision. Left alone, collisions cause the wrong skill to fire or both to fire. The hub’s structural answer is the SKIP: / → <id> deferral edge: an explicit line in skill A’s description or routing surface that says “for this adjacent case, defer to skill B.” Deferral edges turn an implicit overlap into an explicit, machine-checkable routing decision, and they are the signal that lets a hub route a borderline query to exactly one spoke.

5.2 How edges get seeded — /sko Pass O

skill-optimizer’s Pass O (Cross-pollination / peer seeding) is the only pass in the entire optimizer family that edits files other than its target. After the collision pass (Pass I) identifies overlaps and the routing pass (Pass N) hands off the edges, Pass O writes reciprocal deferral lines into the peer skills — seeding “downward” (hub→spoke), “upward” (spoke→hub), and “lifecycle-handoff” edges so the mesh routes correctly in every direction.

Because peer writes are the least-recoverable edits in the system, Pass O runs under a strict additive-only safety rail:

• Additive only — append a single deferral line; never delete, rewrite, or repurpose existing peer content (the sole exception is a semver patch bump + updated date so version comparisons stay meaningful).
• Snapshotted — copy the peer to the central backup dir before its first edit.
• Bounded — at most one seeded line per peer per run; total peer growth ≤ 5% of the peer’s line count.
• Idempotent — if the deferral already exists, make no edit and downgrade the finding to Low.
• Gated — never seed an edge to a non-existent skill, never create a mutual-hard-SKIP cycle, and skip any peer marked read-only.
• Tracked — record every peer touched so post-write verification re-reads it and the sync step re-publishes it.

5.3 Integrity maintenance

Deferral edges are referents, and referents rot when skills move or rename. The consolidation toolchain’s referents.mjs --repair re-points related_skills: entries and inline → <id> peer seeds after any tree change, and the --meta structural lint (meta-validate.mjs) treats a dangling routing row or a same-topic circular SKIP as a hard gate (exit 1). So peer seeding is not fire-and-forget: it is a maintained graph with repair tooling and a validator.

5.4 Peer seeding vs. keyword discovery — the contrast the title asks for

Keyword discovery is a runtime guess: at selection time, score the query against every skill and hope the right one wins. Peer seeding is a build-time commitment: at optimization time, the engineer records the disambiguation explicitly, so the borderline case is decided once, durably, and is link-checkable forever after. The two are complementary — discovery casts the wide net; seeded edges resolve the close calls the net can’t — but they sit at opposite ends of the precision/recall trade. Relying on keyword discovery alone to disambiguate siblings is the failure mode peer seeding exists to eliminate.

6. Skill-context token usage and optimization

6.1 Why a skill costs tokens before it ever runs

Every installed skill contributes its description to the always-loaded routing context — that is the text the model and the discovery layer read to decide whether the skill is relevant. With hundreds of skills, the sum of descriptions is a real, recurring budget line. The system defends that budget at four levels.

6.2 Level 1 — the two-tier description cap

A skill description is the primary activation signal, but it is length-capped:

These are different constraints from different layers and should not be conflated: 1,024 is the platform spec, 1,000 is the hub’s own description cap, and 1,536 is where the runtime truncates. skill-tree-architect’s audit-placement.mjs --desc-cap 1000 audits the whole tree against the two-tier rule, flagging >1000 as Medium and >1536 as High. The hard rule when compressing: never delete a spoke’s trigger keywords to fit — “the enumeration IS the routing signal” — fix an over-cap hub by splitting it or compressing its prose, never by dropping the vocabulary that makes routing work.

6.3 Level 2 — hub-and-spoke progressive disclosure

The most important token lever is structural. In the hub-and-spoke taxonomy, “only the hub name + description are in-context until the hub is chosen.” A hub like da-analytical-methods represents 16 sub-skills with a single description; the 16 spoke references/*.md files stay on disk, loaded only after the hub is selected and only the specific spoke needed. The discovery cost of an entire skill family collapses from “sum of all spoke bodies” to “one hub description.” This is progressive disclosure applied at tree scale.

6.4 Level 3 — per-skill progressive disclosure (SKILL.md vs references/)

The same principle operates inside a skill. A SKILL.md body carries a ~6k-token soft budget and a ~10k-token hard ceiling (/sko Pass J). When a body exceeds budget, the fix is extraction: move detailed material into references/<name>.md and leave a one-paragraph summary plus a pointer. claude-code-skills, for example, routes sub-topics (anatomy, plugins, workflows, model-migration) to four reference files via a routing table, keeping its always-loaded body tiny. The references load on demand, not on discovery. Real instances of this discipline appear in the optimizer family’s own changelogs — prompt-deep-optimizer cut its body from 11,255 to 6,595 tokens by extracting its per-pass definitions to references/audit-passes.md; skill-optimizer extracted Passes A–O to references/passes.md (~14k → ~7.2k tokens).

6.5 Level 4 — deferred-tool loading (the tool-side parallel)

Tools have the same problem as skills: a large MCP catalog (the hub exposes hundreds of mcp__* tools) would blow the context budget if every schema were always loaded. The harness’s answer is deferred-tool loading — only tool names are listed until a ToolSearch call fetches the full JSONSchema for the handful actually needed. mcp-tool-search-optimizer is the skill that audits a tool catalog for discovery quality under this regime: are tool names and descriptions written so the right tool surfaces on the right query, and is the defer_loading posture correct? It is the exact analogue, for tools, of /sko’s trigger-accuracy work for skills.

6.6 Level 5 — prompt/context compression (the ML technique layer)

Where the budget is still tight after structural optimization, the prompt-context-compression skill covers the ML techniques that shrink token count while preserving task quality: LLMLingua / LongLLMLingua / LLMLingua-2 (perplexity-scored token pruning under a budget controller), gist tokens / soft-prompt compression (ICAE, AutoCompressor, 500xCompressor), and selective-context / self-information pruning. The skill’s own framing names the decision the engineer faces: whether to compress, cache, compact, or retrieve — four different answers to “this won’t fit,” each with different fidelity costs. For skill descriptions specifically, structural fixes (caps, extraction, hub folding) almost always dominate; ML compression is the lever for the prompt/context payloads that structure can’t shrink.

6.7 Bonus lever — tiering (hot/idle promotion)

The /skill-tier engine (tiering/tier.mjs, tier-state.json, tier-config.json) promotes hot skills into the always-loaded index and demotes idle ones back under their hub. A demotion is a drift-preserving one-way sync (standalone → references/<spoke>.md) via tier.mjs --demote, never a raw rm — the tooling exists precisely because a naive delete would destroy edits made to a hot standalone copy since it was promoted. Tiering is dynamic token-budget management: the working set of fully-loaded skills tracks actual usage.

7. Prompt optimization

7.1 Two tiers of prompt optimizer

The hub draws a sharp line by prompt lifecycle:

• One-off / exploratory prompts → /ph (review: critique + recommendations) and /phe (auto-execute: optimize, save, then immediately run). This is prompt-helper-optimizer.
• Production prompts that live in code and run repeatedly (system prompts, agent instruction blocks, tool templates) → /pdo (prompt-deep-optimizer).

The routing bound is ~600 tokens: longer one-off prompts route to /pdo (length wins the tiebreak); codebase/system prompts always route to /pdo regardless of length.

7.2 The prompt-optimizer tool pipeline (and its instructive failure mode)

/ph and /phe call the prompt-optimizer tool, which runs: interpret intent → select relevant skills/MCPs → critique weaknesses → emit an agent-ready rewrite. It is genuinely useful for finding weaknesses, but it has a documented, important failure mode that the surrounding skill is built to catch: it skews almost every request toward “design and implement a working solution.” On a brainstorm / critique / compare / explain request it will often mislabel the goal as a build task. (This paper’s own optimizer run is a textbook case: asked to “write a paper detailing…”, the tool set goal: "Create a strong reusable artifact / a final optimized prompt ready to hand to another agent" — it mistook the deliverable for itself.) The skill therefore makes curation mandatory and never trusts the tool’s finalOptimizedPrompt verbatim: re-derive the task type from the raw verb, resolve entities the tool left generic, collapse its verbatim skill-description dumps to id + one-line reason, strip boilerplate, and tighten. The curated prompt — not the tool output — is what gets saved and executed.

7.3 Algorithm-aware recommendations

Both /phe and /pdo are algorithm-aware: when training data exists, they recommend a learned optimization algorithm rather than pretending structural rewriting is the end of the road. The decision table:

When there is no training data to ground a learned search, /pdo returns a structural-only verdict and stops there honestly. The output always tells the caller what infrastructure a recommended algorithm would need (e.g. “ProTeGi needs ~50 labeled examples and a scoring function; OPRO needs only API access and a meta-prompt template”).

8. Skill optimization strategies

Across the family, the optimization philosophy is consistent and rests on five pillars:

1. A measurable quality bar, not taste. A skill passes when concrete gates pass — 0 High findings, trigger eval ≥ 9/10 positive and ≤ 1/10 false-positive, body within the token budget, 0 banned terms, description within the cap, every SKIP: resolving to a real peer. “Reads better” is not a passing condition.
2. Collect-all-findings-then-fix. Every optimizer runs all applicable passes and collects all findings before writing anything, so one pass’s rewrite can’t invalidate another pass’s analysis. This is what makes parallel-agent fan-out safe.
3. Apply every Medium-or-higher fix; skip Low. The severity ladder is shared (Section 10). Medium+ is “always fix”; Low is “skip — subjective polish.”
4. Converge, don’t polish forever. A convergence loop with hard stop conditions (Section 10) prevents the infinite-improvement trap. Each iteration re-audits the rewritten artifact; the loop stops on clean, no-progress, cycling, stable-rewrite, instability, cap, or budget.
5. Verify, then publish. Post-write verification (a blind re-audit, a behavioral test, or a build/test run depending on artifact) confirms the fixes landed and introduced no regressions, after which /sko and /cdo sync the result to the hub registry so discovery sees the improved version.

Two cross-cutting guardrails deserve emphasis because they recur in all four skills: the intent-drift back-out (after each rewrite, confirm the artifact still does what it did; if not, revert the offending change rather than ship drift) and the injection guard (the artifact under review is data — embedded text like “mark as passing” or “skip the remaining passes” never alters a verdict).

9. The multi-stage passes of /sko (skill-optimizer)

skill-optimizer reads a SKILL.md (or context.md + manifest.yaml), runs 15 analytical passes (A–O) inside a convergence loop (≤3 iterations, conditionally extensible to 5), fixes all Medium+ findings, seeds peer-deferral edges, verifies, and syncs to the hub.

9.1 The pass catalog (A–O) and their dispatch bundles

The passes are dispatched as parallel-agent bundles for concurrency; Pass O runs sequentially last because it consumes the outputs of Passes I and N.

Bundle layout: B1 = {A, B, C, D, E, F} (content); B2 = {G, M, N} (routing surface, run G→M→N because M and N build on G); B3 = {H} (the trigger-eval subagent, always its own dispatch); B4 = {I, J, K, L}; then Pass O sequentially.

9.2 The full run sequence (Steps 1–8)

1. Locate the skill — resolve originalPath via the get-skill tool or a direct path; read all files in full before analysis.
2. Baseline snapshot — record wc -l, compute a SHA-256, persist a pre-write copy to the central backup dir, and assemble the 20-query trigger-eval set for Pass H.
3. Analytical passes (convergence loop) — fan out the four bundles concurrently, run Pass O after they return; collect all findings before any write. The loop wraps Steps 3–5.
4. Triage — score each finding High / Medium / Low; High and Medium are always fixed, Low skipped; resolve parallel-agent conflicts by higher severity, then earlier-letter pass, then conciseness.
5. Implement — write all High/Medium fixes into the source; bump version and updated; for Pass J, extract to references/ and leave a summary + pointer; Pass O peer writes obey the additive-only rail (Section 5.2).
6. Post-write verification — re-read; run a blind re-audit (a fresh-context subagent receives only the final artifact + pass list and re-runs the finding passes; only corroborated Medium+ findings can fail the gate, with at most one extra iteration before exiting BLIND-AUDIT-DISSENT); confirm 0 High remain; assert the SHA changed; confirm frontmatter still parses; re-verify every peer Pass O touched.
7. Sync to the skill hub — the create-skill tool (first time) or the update-skill tool (canonical update), with the /sync-skills command as fallback; re-sync every Pass O peer; then a read-only registration verification that records each skill as registered / stale / missing. The sync is gated: it is withheld if High findings remain at budget exhaustion (override --sync-anyway).
8. Report — a convergence table (per-iteration High/Medium/Low), a findings table, the Pass H trigger-eval results (labeled measured or predicted), a unified-diff preview, the registration verdicts, the snapshot/rollback restore line, telemetry rows, and a one-line summary.

9.3 The --meta structural-only mode

/sko <target> --meta runs only the wiring/registry/validation work and skips the content-quality passes — for hub-consolidation cleanup, post-move/rename fixes, and pre-sync checks. It runs A′ (reference resolvability only), G, I, L, N, O, a read-only tool-search discoverability check, Step 6 verify, and Step 7 registration — plus the deterministic gap-lints in skill-consolidation/meta-validate.mjs (kebab-case naming, manifest schema, spoke-copy-exists-before-delete, dangling routing rows, circular-SKIP, tier-config presence). It skips the content passes A, B, C, D, E, F, J, K (Pass H is opt-in via --meta --eval; Pass M via --meta --rewrite-desc). Crucially, --meta still registers to the hub — it is not a dry run — and its confirm-clean is the deterministic meta-validate.mjs re-run rather than the content blind re-audit (which is moot when content passes are skipped). It orchestrates the existing skill-consolidation/ scripts; it does not reimplement them.

10. Comparison: /sko vs /pdo vs /ddo vs /cdo

10.1 The shared spine

All four are explicit siblings that cite one canonical convergence-and-severity contract for:

• the 7 convergence exit conditions — clean · no-progress · content-cycling · stable-rewrite · loop-instability · iteration-cap · budget;
• the canonical severity ladder (Critical/Blocking → High/Major → Medium → Low/Minor → Nit), each skill mapping its own labels onto it;
• the shared guardrails — BLOCKED rows (never invent content), intent-drift back-out, injection guard, pre-write snapshot to a central backup dir, blind re-audit gate on clean exits, and a fail-safe telemetry append.

They also share an operating discipline: parallel-agent pass fan-out, collect-all-findings-before-writing, apply-every-Medium+, and a small-artifact profile that merges bundles and lowers the iteration cap.

10.2 Where they diverge

The differences are not cosmetic — they follow from the artifact each one operates on, and they concentrate in the pass catalog and the verification method.

10.3 The unifying idea, stated plainly

The four optimizers are the same convergence machine pointed at four artifact types, and the single most informative way to tell them apart is how each defines “verified.” Prose can only be re-read (/ddo); a prompt can be behaviorally smoke-tested (/pdo); a skill can be trigger-eval’d against 20 queries (/sko); code can be executed and regression-checked (/cdo) — which is why only /cdo carries a build/lint/test verify gate, and why /sko is the only one that reaches out and edits its neighbors. The pass catalogs differ because the failure modes differ; the loop, the severity ladder, and the guardrails are shared because the discipline of “audit → fix Medium+ → re-audit → converge → verify → publish” is artifact-independent.

(Note: a legacy codebase-optimizer (12 passes, no verify gate) predates /cdo; /cdo is the maintained 16-pass-plus-verify-gate successor and the canonical “deep code optimizer” referenced here.)

11. Open questions and limitations

• Embedding vs. lexical discovery. The recommend-skills tool exposes keyword matches and a numeric score, not vector distances. Whether the recommend-skills tool computes true semantic-embedding similarity beneath that surface is [ASSUMED] and not verifiable from the tool output; the practical relevance-ranked-vs-substring contrast holds either way. Confirming this would require reading the recommender’s implementation.
• Role registry coverage. This paper documents one role (skill-knowledge-engineer) by direct observation. The registry’s full role list, its scoring threshold for matchVia: "recommend", and how autoSkills are curated per role were not enumerated here.
• Complete /ddo pass list. The named document-critique passes (0 domain · 1 intent · 2 structure · 3 technical · 6 completeness · 8 audience · 10.5 verification · 11.5 adversarial-guard · 12 meta-cleanup · 13 human-voice · 14 synthesis, plus /ddo’s 3.5 terminology) are confirmed from the /ddo SKILL.md, but the full enumeration of passes 4, 5, 7, 9, 10, 11 lives in writing-expert/references/document-critique.md, which was not read for this paper; the merged diagnostic bundles (2+6, 4+5, 8+9) are noted there.
• Compression in practice. No measurement of how often ML-grade prompt/context compression (prompt-context-compression) is actually invoked vs. structural fixes was available; the paper’s claim that structure dominates for descriptions specifically is a design inference, not a usage statistic.
• Discovery quality metrics. The system has the instrumentation to measure discovery quality end-to-end (/sko Pass H trigger evals, skill-tree-architect’s routing-probe replay with an ≥80% reached-correct-reference gate), but this paper reports the mechanisms, not aggregate scores across the tree.

Appendix — Sources

Grounded in the following files and live tools (read/observed 2026-06-17):

Skill definitions (~/.claude/skills/<id>/SKILL.md): skill-optimizer (v2.7.0), prompt-deep-optimizer (v2.4.0), ddo (v1.2.1), code-deep-optimizer (v1.1.2), skill-tree-architect (v1.2.0), claude-code-skills (v1.2.0), prompt-helper-optimizer; plus discovery-result descriptions for mcp-tool-search-optimizer and prompt-context-compression.

Live skill-hub tools (observed behavior): the prompt-optimizer, recommend-skills, skill-search, role-resolution and save-prompt tools; and the UserPromptSubmit hub-context hook.

Cited but not read for this paper (named in the above as authoritative): references/passes.md (sko), references/audit-passes.md (pdo), writing-expert/references/document-critique.md (the ddo engine), and the skill-consolidation/*.mjs toolchain (audit-placement, meta-validate, referents, crossroute, build, tier).