@skill-graph/cli 0.5.6

package/marketplace/skills/skill-infrastructure/SKILL.md

@@ -0,0 +1,320 @@
+---
+name: skill-infrastructure
+description: "Use when designing the deterministic health-tooling layer for a skill library, diagnosing why an existing library is decaying invisibly, deciding which categories of automated check to add (inventory, protocol consistency, conflict detection, routing health, drift sentinel), debugging eval-threshold violations across many skills at once, or auditing whether a skill-system has the safety nets a production library needs. Covers the five categories of skill-health tooling, the library-as-database mental model, eval quality patterns (minimum thresholds, contradiction-check pattern, negative-expectation requirement), maintenance workflows triggered by batch skill changes, and the anti-patterns that cause skill libraries to decay until agents loading them get worse over time. Do NOT use for authoring an individual SKILL.md (use `skill-scaffold`), for running the conformance audit on the Skill Graph repo itself (use `graph-audit`), or for general lint rule selection across a codebase (use `lint-overlay`)."
+license: MIT
+compatibility: "Library- and harness-agnostic. Patterns apply to any skill-style library (Skill Graph, Claude skills, Cursor rules, custom in-house skill systems). Specific tool names in this skill (skill-lint, generate-manifest, routing-eval, drift-sentinel) are concrete examples from the Skill Graph reference implementation -- substitute your library's equivalents."
+allowed-tools: Read Grep Bash Edit Write
+metadata:
+  metadata: "{\"schema_version\":6,\"version\":\"1.0.0\",\"type\":\"capability\",\"category\":\"agent\",\"domain\":\"agent/skill-system\",\"scope\":\"portable\",\"owner\":\"skill-graph-maintainer\",\"freshness\":\"2026-05-13\",\"drift_check\":\"{\\\\\\\"last_verified\\\\\\\":\\\\\\\"2026-05-13\\\\\\\",\\\\\\\"truth_source_hashes\\\\\\\":{\\\\\\\"package.json\\\\\\\":\\\\\\\"7a3410a004aea78a2065092e289c0f3cf3c082298804dda6c5829eff22c14b62\\\\\\\",\\\\\\\"bin/skill-graph.js\\\\\\\":\\\\\\\"113a1e01ac7276ac1b5d77a1c32e35a73113da93fc33cfd0caf6db842d2d679f\\\\\\\",\\\\\\\"scripts/skill-lint.js\\\\\\\":\\\\\\\"3a78f75f8921542b91dc619cd41bde29bf379de3c16bdcf3653c854ecbe9fa29\\\\\\\",\\\\\\\"scripts/lib/roots.js\\\\\\\":\\\\\\\"e742efa57b6c33ff1c87034b16a689d1499f6d53c1e6b740f3e9783db7fd557f\\\\\\\",\\\\\\\"scripts/check-protocol-consistency.js\\\\\\\":\\\\\\\"0ff39406d36e7a9e51c176f657f4f426d8bd5a3fe6411d28b9e9a93dc7d89f29\\\\\\\",\\\\\\\"scripts/generate-manifest.js\\\\\\\":\\\\\\\"9d7bbbdae440fdb1763d61ffa7bda10c9efae92359d1c2139d0e971582d59e0e\\\\\\\",\\\\\\\"scripts/skill-graph-drift.js\\\\\\\":\\\\\\\"6b69c25b59c16b477a377e5ab40adb6ff30f72d5a12947772053a6cd16b1f409\\\\\\\",\\\\\\\"scripts/skill-overlap.js\\\\\\\":\\\\\\\"ed642cbc677cc76ec1321300b37d6752337b6b5541c7a9f558fd315d6f934e4b\\\\\\\",\\\\\\\"scripts/skill-graph-routing-eval.js\\\\\\\":\\\\\\\"fffac2858863662bde6bc54c56bb77a219ae93f626e0c8d5886566f998181deb\\\\\\\",\\\\\\\"docs/manifest-field-mapping.md\\\\\\\":\\\\\\\"aca0b7f2d4631be24a3e7daed1a1d207b488f253164a7d514b9db7af21c6177f\\\\\\\"}}\",\"eval_artifacts\":\"planned\",\"eval_state\":\"unverified\",\"routing_eval\":\"absent\",\"stability\":\"experimental\",\"keywords\":\"[\\\\\\\"skill library health\\\\\\\",\\\\\\\"skill system tooling\\\\\\\",\\\\\\\"skill library decay\\\\\\\",\\\\\\\"skill library maintenance\\\\\\\",\\\\\\\"skill census\\\\\\\",\\\\\\\"skill inventory\\\\\\\",\\\\\\\"frontmatter validation\\\\\\\",\\\\\\\"imperative conflict\\\\\\\",\\\\\\\"skill overlap detection\\\\\\\",\\\\\\\"skill conflict\\\\\\\",\\\\\\\"routing gap\\\\\\\",\\\\\\\"routing miss\\\\\\\",\\\\\\\"routing health\\\\\\\",\\\\\\\"eval threshold\\\\\\\",\\\\\\\"eval minimum\\\\\\\",\\\\\\\"contradiction check\\\\\\\",\\\\\\\"negative expectation\\\\\\\",\\\\\\\"drift sentinel\\\\\\\",\\\\\\\"truth source hash\\\\\\\",\\\\\\\"mirror parity\\\\\\\",\\\\\\\"skill graph health\\\\\\\",\\\\\\\"production skill library\\\\\\\",\\\\\\\"skill linter\\\\\\\",\\\\\\\"skill quality gate\\\\\\\",\\\\\\\"phantom ref\\\\\\\"]\",\"examples\":\"[\\\\\\\"our skill library is growing and we're getting silent decay — eval counts dropping, conflicts emerging — what tooling should we add?\\\\\\\",\\\\\\\"two of our skills give opposite instructions for the same function — how do we detect this automatically?\\\\\\\",\\\\\\\"we keep getting skill-router misses on real user queries — how do we surface and close routing gaps?\\\\\\\",\\\\\\\"design a health-check pipeline for a 200-skill library that runs in CI\\\\\\\",\\\\\\\"what's a reasonable minimum eval count per skill, and how do we enforce it?\\\\\\\",\\\\\\\"our skill mirror in `.claude/skills` keeps drifting from the source — what's the parity check?\\\\\\\",\\\\\\\"we want to add a contradiction-check eval pattern — what does it look like and when do we use it?\\\\\\\",\\\\\\\"skill-overlap-detector flagged 12 imperative conflicts — how do we triage which to fix vs suppress?\\\\\\\"]\",\"anti_examples\":\"[\\\\\\\"scaffold a new SKILL.md for our team's deploy procedure\\\\\\\",\\\\\\\"audit this Skill Graph repo for schema conformance and dangling relation targets\\\\\\\",\\\\\\\"the manifest sample drifted from the generator — find the mismatch\\\\\\\",\\\\\\\"improve this prompt's wording to get better outputs\\\\\\\",\\\\\\\"review this AI-generated PR for correctness\\\\\\\",\\\\\\\"set up ESLint for our TypeScript repo\\\\\\\",\\\\\\\"draft an architecture note explaining why we chose Postgres\\\\\\\"]\",\"relations\":\"{\\\\\\\"boundary\\\\\\\":[{\\\\\\\"skill\\\\\\\":\\\\\\\"skill-scaffold\\\\\\\",\\\\\\\"reason\\\\\\\":\\\\\\\"skill-scaffold owns authoring methodology for one new SKILL.md; skill-infrastructure owns the deterministic health-tooling layer that watches the entire library after authoring\\\\\\\"},{\\\\\\\"skill\\\\\\\":\\\\\\\"graph-audit\\\\\\\",\\\\\\\"reason\\\\\\\":\\\\\\\"graph-audit is the operational audit of one specific library (Skill Graph), scope: codebase; skill-infrastructure is the portable discipline of designing health tooling for any skill library\\\\\\\"},{\\\\\\\"skill\\\\\\\":\\\\\\\"lint-overlay\\\\\\\",\\\\\\\"reason\\\\\\\":\\\\\\\"lint-overlay covers lint-rule selection and gate placement for general codebases; skill-infrastructure covers the skill-system-specific tooling category that includes lint but extends to overlap, routing-gap, drift, and mirror-parity\\\\\\\"}],\\\\\\\"related\\\\\\\":[\\\\\\\"skill-scaffold\\\\\\\",\\\\\\\"graph-audit\\\\\\\",\\\\\\\"testing-strategy\\\\\\\"],\\\\\\\"verify_with\\\\\\\":[\\\\\\\"testing-strategy\\\\\\\",\\\\\\\"code-review\\\\\\\"]}\",\"grounding\":\"{\\\\\\\"domain_object\\\\\\\":\\\\\\\"Deterministic health tooling for Skill Graph libraries\\\\\\\",\\\\\\\"grounding_mode\\\\\\\":\\\\\\\"hybrid\\\\\\\",\\\\\\\"truth_sources\\\\\\\":[\\\\\\\"package.json\\\\\\\",\\\\\\\"bin/skill-graph.js\\\\\\\",\\\\\\\"scripts/skill-lint.js\\\\\\\",\\\\\\\"scripts/lib/roots.js\\\\\\\",\\\\\\\"scripts/check-protocol-consistency.js\\\\\\\",\\\\\\\"scripts/generate-manifest.js\\\\\\\",\\\\\\\"scripts/skill-graph-drift.js\\\\\\\",\\\\\\\"scripts/skill-overlap.js\\\\\\\",\\\\\\\"scripts/skill-graph-routing-eval.js\\\\\\\",\\\\\\\"docs/manifest-field-mapping.md\\\\\\\"],\\\\\\\"failure_modes\\\\\\\":[\\\\\\\"health_tooling_categories_missing_from_ci\\\\\\\",\\\\\\\"protocol_mapping_drift\\\\\\\",\\\\\\\"eval_thresholds_become_self_attested\\\\\\\",\\\\\\\"overlap_or_drift_checks_not_run_after_batch_changes\\\\\\\"],\\\\\\\"evidence_priority\\\\\\\":\\\\\\\"repo_code_first\\\\\\\"}\",\"portability\":\"{\\\\\\\"readiness\\\\\\\":\\\\\\\"scripted\\\\\\\",\\\\\\\"targets\\\\\\\":[\\\\\\\"skill-md\\\\\\\"]}\",\"lifecycle\":\"{\\\\\\\"stale_after_days\\\\\\\":90,\\\\\\\"review_cadence\\\\\\\":\\\\\\\"quarterly\\\\\\\"}\",\"skill_graph_source_repo\":\"https://github.com/jacob-balslev/skill-graph\",\"skill_graph_protocol\":\"Skill Metadata Protocol v5\",\"skill_graph_project\":\"Skill Graph\",\"skill_graph_canonical_skill\":\"skills/skill-infrastructure/SKILL.md\"}"
+  skill_graph_source_repo: "https://github.com/jacob-balslev/skill-graph"
+  skill_graph_protocol: Skill Metadata Protocol v4
+  skill_graph_project: Skill Graph
+  skill_graph_canonical_skill: skills/skill-infrastructure/SKILL.md
+---
+
+# Skill Infrastructure
+
+## Coverage
+
+- The library-as-database mental model: skill-infrastructure as the linter, integrity checker, and query planner for a SKILL.md library
+- Why deterministic, zero-LLM tooling is mandatory for skill libraries (trustworthy enough for CI gates; LLM-based health checks are circular)
+- The five categories of skill-health tooling: (1) inventory and frontmatter validation, (2) protocol consistency, (3) conflict detection (overlap, imperative, code duplication, heading overlap), (4) routing health (gap analysis, miss tracking), (5) drift detection (truth-source hashing, mirror parity)
+- Eval quality patterns: minimum eval threshold per skill, the contradiction-check eval type, the negative-expectation requirement, valid eval-type taxonomy
+- Imperative conflict detection: the same-target-opposite-polarity rule, three-check false-positive suppression, when conflicts indicate scope-tightening vs merging
+- Routing gap analysis: how to read a "routing-misses" log, how to distinguish keyword gaps from skill content gaps, signal-hygiene rules to suppress noise
+- Maintenance workflows: when to run a full health check, the order in which to run the categories, what to fix before what
+- Anti-patterns that cause invisible decay: dirty-tree manifest writes, deletion-as-conflict-resolution, eval-renumbering during cleanup, scope misuse to mask threshold violations
+- The verification gate before any batch skill commit: every category clean, every new skill meets eval minimums, every routing change is reflected in the manifest
+- Package and workspace-root integrity: the npm CLI entrypoint must dispatch to the same scripts as local development while resolving schemas from the package and skills/manifests from the caller workspace
+
+## Philosophy
+
+A skill library is only as useful as its worst skill. When agents load stale, conflicting, poorly-routed, or mirror-drifted skills, they get *worse* at tasks — not better. A skill library at scale (50+, certainly 200+) decays invisibly: eval counts drift below minimums, keyword maps miss whole product areas, mirror copies fall out of sync, and two skills start giving opposite instructions for the same function.
+
+The infrastructure exists to catch that decay deterministically, with **zero LLM calls**. Every health check reads files, parses structure, and computes — it does not reason, infer, or hallucinate. That makes the output trustworthy enough to use in CI-style gates. An LLM-based health check is circular: the same probabilistic component that produces the skill library cannot reliably grade its own output.
+
+> If the skill library is a codebase, skill-infrastructure is its combined linter, type-checker, and dead-code detector — always-on, zero-model, CI-safe.
+
+The maintenance commitment is: run a full health check after any batch skill work, fix threshold violations before they reach the gate, and document conflicts before the agents loading those skills are affected.
+
+## The Library-as-Database Mental Model
+
+Treat the skill library as a database and skill-infrastructure as its query planner, integrity checker, and migration-safety net combined.
+
+| Database concept | Skill-library equivalent |
+|---|---|
+| Schema | SKILL.md frontmatter schema (JSON Schema or equivalent) |
+| Constraints | Required fields, eval thresholds, valid enum values |
+| Foreign keys | `relations.boundary[]`, `relations.related[]` targets — must point at real skills |
+| Indexes | Manifest, routing-keyword map, path-glob inverse index |
+| Integrity check | Protocol-consistency tooling (cross-schema parity, sample correctness, generated-field parity) |
+| Query planner | Skill router (matches user prompt → skill activation) |
+| Replication lag | Mirror parity (`.claude/skills`, `.agents/skills`, harness-specific copies) |
+| Dead code | Skills with broken relation targets, phantom routing entries |
+
+Every script in this domain reads files and computes — it does not reason. Output is deterministic, reproducible, and safe to embed in CI gates.
+
+## The Five Categories of Skill-Health Tooling
+
+A production skill library needs all five. Missing any one allows a class of decay through.
+
+### 1. Inventory and Frontmatter Validation
+
+Walks the skill tree, parses every SKILL.md's frontmatter, and validates against the schema.
+
+| Check | Why it matters |
+|---|---|
+| Required fields present (`name`, `description`, `version`, `type`, `scope`, `owner`, `freshness`) | Missing fields break the manifest generator and the router |
+| Field-value enums valid (`type`, `scope`, `eval_state`) | Drift in valid values leaks invalid skills into routing |
+| Description-length and quality (≥ 100 chars, contains "Use when X / Do NOT use for Y") | Short or vague descriptions degrade router precision |
+| Eval-count per skill (warn at < 7, error at < 3 for non-reference skills) | Under-evaluated skills regress quality undetected |
+| Reference-path resolution (every `references/X.md` cited in frontmatter actually exists) | Dangling references mislead the agent at activation time |
+| Scope-grounding consistency (`scope: codebase` requires populated `grounding` block) | Codebase claims without grounding can hallucinate file paths |
+
+**Reference implementation:** `scripts/skill-lint.js` in this repo runs T5 per-skill lint covering most of these.
+
+### 2. Protocol Consistency
+
+Cross-checks that the schema, generator, sample manifest, and field-reference docs all agree.
+
+| Check | Failure mode if missing |
+|---|---|
+| Cross-schema parity (versioned schemas describe the same fields) | Schema bumps silently drop fields |
+| Authored-to-generated parity (frontmatter fields match what the generator emits) | Generator drift breaks downstream consumers |
+| Sample manifest matches generator output | Sample stales as skills are added |
+| Generated field-reference matches authored field-reference | Documentation drift hides field changes |
+| Truth invariants on example evals (e.g. truth-source line ranges still resolve) | Eval expectations point at non-existent code |
+
+**Reference implementation:** `scripts/check-protocol-consistency.js` runs C1–C7 protocol checks.
+
+### 3. Conflict Detection
+
+Pairwise comparison across all active skills to surface duplication, contradiction, and structural overlap.
+
+| Dimension | Method | Signal |
+|---|---|---|
+| Description similarity | Jaccard on word bigrams | > 0.4 = potential duplicate |
+| Heading overlap | Shared H2/H3 headings excluding boilerplate | High overlap = structural duplication |
+| Code duplication | Identical fenced code blocks > 30 chars | Copy-paste anti-pattern |
+| Imperative conflicts | Same target, opposite polarity (ALWAYS vs NEVER) | Agents get contradictory instructions |
+
+**Imperative extraction patterns:**
+
+- Positive: `\b(?:always|must|required|mandatory)\b\s+(.{10,80})/gi`, `\buse\s+(.{5,60})\s+(?:for|when|instead)/gi`
+- Negative: `\b(?:never|do\s+not|don't|must\s+not|prohibited)\b\s+(.{10,80})/gi`, `\bdo\s+NOT\s+use\s+(.{5,60})/gi`
+
+**Three-check false-positive suppression** for the most common phantom-conflict sources (e.g. `Do NOT use X` matching as positive `use X`):
+
+1. **Lookbehind check** — if `not`, `never`, `don't`, or `cannot` appears in the 20 characters before a positive match, suppress it
+2. **Within-match check** — if `not` appears between the start of the match and the target identifier (extracted via backticks), suppress it
+3. **Same-line dedup** — if the target was already extracted as a negative on the current line, suppress any positive extraction for that target
+
+**When a conflict is real vs spurious:**
+
+| Conflict type | Resolution |
+|---|---|
+| Phantom ref | Routing config maps to a non-existent skill — delete the stale entry |
+| Code duplication | One skill owns the example; the other links to it |
+| Heading overlap | Acceptable for structural templates; review only the differentiating content |
+| Imperative conflict (real) | Scope the instructions more precisely (`always use X` → `always use X in app code`); rarely merge skills |
+| Imperative conflict (spurious) | Un-backticking an identifier hides a real boundary ambiguity — fix the skill wording instead |
+
+### 4. Routing Health
+
+Reads the routing-miss log and the routing config to identify where the keyword map fails.
+
+| Input | Purpose |
+|---|---|
+| Routing-misses log (queries that matched zero skills) | Surface keyword gaps — words users typed that never reached a skill |
+| Eval-history log with `failure_category` | Surface skills failing for reasons routing can fix (`skill_not_activated`, `wrong_answer`) |
+| Active routing config (`keywordMap`, `labelMap`) | Authoritative truth for what currently routes |
+
+**Output sections:**
+
+1. **Keyword gaps** — words appearing in routing-misses but absent from the active keyword map, sorted by frequency
+2. **Eval failure breakdown** — skills with 2+ failures, grouped by failure category
+3. **Suggested actions** — `add_keyword` for frequent gaps; `improve_skill` for skills failing for content reasons
+
+**Signal hygiene rules** (suppress these from the suggestion list):
+
+- Low-signal tokens (`v`, `v4`, `skill`, `start`, `events`, `daily`, `log`, `status`, `health`)
+- Single-word misses already covered by an existing multi-word phrase (e.g. `error` should not surface if `error recovery` is already mapped)
+- Stale historical misses where the full query already routes under the current config
+- Synthetic no-match probes used to verify the router's miss path
+- Bundle entries (only direct `keywordMap` entries participate in free-text matching)
+
+**Reference implementation:** the routing harness (`scripts/skill-graph-routing-eval.js` in this repo) provides the negative case — verifying that a skill's authored `examples` actually route to it. A real routing-gap report is the symmetric positive case (verifying that real user prompts reach a skill).
+
+### 5. Drift Detection
+
+Detects when the *world the skill claims* has changed without the skill being updated.
+
+| Drift type | Detection |
+|---|---|
+| Truth-source drift | `drift_check.truth_source_hashes` records SHA-256 of cited files; rerun hashes; mismatch = drift |
+| Mirror parity | Hash every `<library>/skills/<name>/SKILL.md` and every `<harness-mirror>/skills/<name>/SKILL.md`; mismatch = drift |
+| Stale `freshness` date | Skill has not been touched in > `lifecycle.stale_after_days`; surface for review |
+| Tracker → skill drift | Issue tracker references a skill that no longer exists; or skill references a closed issue |
+
+**Reference implementation:** `scripts/skill-graph-drift.js` in this repo records and verifies truth-source hashes against the live files.
+
+## Eval Quality Patterns
+
+### The minimum-threshold rule
+
+Every active skill should have at least 7 evals. Most healthy skills carry 9–15 covering happy paths, edge cases, anti-patterns, and contradiction checks. The threshold is a *floor*, not a goal.
+
+**Recommended enforcement:**
+
+- **Error** if `eval_count < 3` (or **warn** for `scope: reference` skills, where the file is documentation more than testable behaviour)
+- **Warn** if `eval_count < 7`
+
+Below 7, the skill is statistically under-tested. Below 3, it is effectively un-evaluated.
+
+### The contradiction-check eval type
+
+A `contradiction-check` eval tests that the agent correctly handles a documented exception or boundary condition that a simpler reading of the skill would mishandle. Format:
+
+```json
+{
+  "id": 5,
+  "type": "contradiction-check",
+  "grounding": "repo-specific",
+  "difficulty": "adversarial",
+  "prompt": "Skill A says always use the scoped fetcher. One service uses the unscoped fetcher with an inline comment. Is this wrong?",
+  "expected_output": "Not wrong — the unscoped fetcher with an inline justification comment is the documented exception for system-level reads.",
+  "expectations": [
+    "Correctly identifies the documented exception from the skill's anti-patterns table",
+    "Does NOT flag the usage as a bug without reading the inline comment",
+    "Distinguishes a system-level exception from a regular violation in application code"
+  ]
+}
+```
+
+Use a contradiction-check when:
+
+- A skill has a documented exception that overrides the general rule
+- Two adjacent skills appear to contradict each other but actually operate in different scopes
+- A historical false positive or conflict was resolved and the resolution is non-obvious
+
+### The negative-expectation requirement
+
+Every eval case with an `expectations` array must include at least one expectation containing `does not`, `never`, `must not`, `should not`, or `do not`. Without this, evals become pure happy-path tests and miss the failure modes that motivated the skill.
+
+**Recommended enforcement:** the inventory tool flags any eval missing this pattern in a `missingNegativeEvalIds` field of its report.
+
+### Valid eval types
+
+| Type | When to use |
+|---|---|
+| `knowledge` | Tests a factual claim or pattern from the skill |
+| `contradiction-check` | Tests documented exceptions and boundary conditions |
+| `browser` | Tests a browser-executable interaction (requires running server) |
+| `edge-case` | Tests unusual inputs or rare conditions |
+| `business-model` | Tests domain-specific logic (e.g. SaaS billing rules, e-commerce fulfilment) |
+| `negative` | Tests refusal or correct non-action |
+
+## Maintenance Workflows
+
+### The full health check sequence
+
+Run after any batch skill work — creating ≥ 3 skills, changing routing config, or modifying skill content across multiple files. Order matters:
+
+```bash
+# 1. Inventory snapshot — discover invalid frontmatter, missing fields, broken refs
+<inventory tool>
+
+# 2. Protocol consistency — cross-schema, manifest, generated-doc parity
+<protocol-consistency tool>
+
+# 3. Conflict detection — overlap, imperatives, code duplication
+<conflict tool> --conflicts
+
+# 4. Routing gaps (last 7 days)
+<routing-gap tool> --since 7d
+
+# 5. Drift sentinel — truth-source hashes, mirror parity
+<drift tool>
+
+# 6. Regenerate manifest + index from the now-clean tree
+<manifest generator> --write
+```
+
+Review the output of steps 1–5 before running step 6. The manifest and index should reflect a clean state — never write a manifest from a dirty tree.
+
+### Adding evals to an existing skill
+
+1. Read the skill's existing eval set
+2. Identify gaps: are all eval types represented? Are there contradiction-checks for documented exceptions?
+3. Draft new cases with `id`, `prompt`, `expected_output`, `expectations`, `type`, `grounding`, `difficulty`
+4. Ensure every new case has at least one `does not / never / must not` expectation
+5. **Append** to the eval array — never renumber existing IDs (eval-history logs reference numeric IDs)
+6. Re-run the inventory tool and verify the skill no longer appears in `belowMinimum` or `missingNegativeEvalIds`
+
+### Triaging imperative conflicts
+
+1. Run the conflict tool with `--conflicts --json` to get the structured list
+2. For each conflict, identify which skill's instruction is more precise or more scoped
+3. Resolve by *narrowing scope*, not by deleting the instruction:
+   - "Use X" → "Use X in app code" (narrower)
+   - "Always use X" → "Always use X for tenant-scoped data" (specific)
+   - Move the negative instruction to an anti-patterns table row that does not start with "Use"
+   - Add an inline qualifier (e.g. `// system: <reason>`) that the detector can distinguish
+4. Re-run `--conflicts` to confirm the conflict is gone
+5. Document the resolution in a conflict log so future audits know it was deliberate
+
+### Fixing invalid frontmatter
+
+| Problem | Fix |
+|---|---|
+| `scope` field absent | Add the correct value (`portable` / `reference` / `codebase`) |
+| `drift_check.last_verified` absent or stale | Add or update to today's ISO date |
+| `eval_artifacts` absent | Set to `present` if eval files exist, `planned` if intended, `none` otherwise |
+| `keywords` empty or short | Add 5–15 natural-language phrases users would actually type |
+| `description` too short | Quote it; require ≥ 100 chars; include trigger phrases and a "Do NOT use for X (use Y)" exclusion |
+| `version` absent | Set to `1.0.0` for new skills; bump per semver on substantive change |
+
+After editing, re-run the inventory tool and confirm the skill no longer appears in the invalid-frontmatter list.
+
+## Anti-Patterns
+
+| Anti-pattern | Why it fails | What to do instead |
+|---|---|---|
+| Running manifest-write on a dirty skill tree | Writes a broken index that downstream consumers trust | Fix all inventory errors first, then regenerate |
+| Resolving conflicts by deleting one instruction | Removes useful guidance the agent needs in the right scope | Narrow the scope of the instruction instead |
+| Adding evals without negative expectations | Census flags them; they test only happy paths | Every eval must have at least one `does not / never / must not` expectation |
+| Renumbering eval IDs during cleanup | Breaks eval-history references that use numeric IDs | Always append; never renumber |
+| Un-backticking an identifier to suppress a false positive when the conflict is real | Hides a real boundary ambiguity | Fix the skill wording to accurately reflect the scope |
+| Adding routing keywords without a real skill to route to | Creates more broken mappings | Only add keywords that map to an existing skill |
+| Treating heading overlap as always wrong | Structural-template skills (model profiles, integration patterns) legitimately share structure | Review the differentiating content instead of restructuring |
+| Using `scope: reference` to mask threshold violations | Reference scope downgrades eval-error to warning, hiding real gaps | Use `reference` only for genuine reference docs (contracts, schemas), never to dodge threshold enforcement |
+| Producing a thin audit summary after a multi-hour session | A two-hour audit that outputs "5 entities missing evals" has performed a *census*, not an *audit* — 95% of the invested tokens are wasted | Census counts things; audits verify claims against evidence. Every audited skill needs per-claim verdicts (verified / drift) referencing specific file:line evidence |
+| Running a "skill loop" without a minimum-output specification | Agents read methodology sections but skip output-format sections, then produce free-form summaries | Before any audit/eval/improvement session, define the output format up front. Templates exist — use them |
+| LLM-based health checks instead of deterministic ones | Probabilistic grading of probabilistic content is circular and unreliable | Health-tooling layer is zero-LLM by design. LLMs grade *task output*, not *skill metadata* |
+
+## Verification
+
+Before any batch skill commit, verify:
+
+- [ ] Inventory tool exits with zero critical errors
+- [ ] Zero invalid-frontmatter entries
+- [ ] Zero broken mappings in routing config
+- [ ] All new skills meet the eval minimum (≥ 7, or ≥ 3 with explicit warning acceptance)
+- [ ] All new evals include at least one negative expectation
+- [ ] Conflict tool shows no NEW conflicts vs baseline
+- [ ] Routing-gap report shows no new keyword gaps caused by your changes
+- [ ] Manifest generator completed without errors
+- [ ] Mirror parity verified if the library replicates to multiple harness directories
+- [ ] Skill index header count matches actual skill count
+
+## Do NOT Use When
+
+| Use instead | When |
+|---|---|
+| `skill-scaffold` | Authoring or restructuring a single new SKILL.md (the contract for one file, not the system around the library) |
+| `graph-audit` | Running the conformance audit on this Skill Graph repo specifically (operational), not designing the discipline |
+| `lint-overlay` | General-purpose lint-rule selection and gate placement for any codebase, not skill-system-specific tooling |
+| `documentation` | Writing prose for a human reader explaining how the skill system works |
+| `code-review` | Reviewing a code change to the health-tooling scripts themselves |
+| `testing-strategy` | Designing the test pyramid / trophy / honeycomb shape for a non-skill-library codebase |
+| `prompt-craft` | Improving the wording of a single skill's prompt or eval prompt |

package/marketplace/skills/skill-router/SKILL.md

@@ -0,0 +1,71 @@
+---
+name: skill-router
+description: "Use when routing an agent request across multiple skills, building or auditing a routing table, detecting routing coverage gaps, or answering questions like 'which skill handles this?', 'who routes X?', or 'why did skill A activate instead of B?'. Covers trigger-label matching, file-path matching, keyword matching, description-based semantic matching, scope/type tiebreakers, and coverage-gap detection. Do NOT use when the target skill is already known (load it directly), when authoring a new skill (use `skill-metadata-template` instead), or when evaluating a SINGLE skill's quality (use `graph-audit`)."
+license: MIT
+compatibility: "Markdown, YAML, any agent runtime"
+allowed-tools: Read Grep
+metadata:
+  metadata: "{\"schema_version\":6,\"version\":\"1.0.0\",\"type\":\"router\",\"category\":\"agent\",\"domain\":\"agent/skill-system\",\"scope\":\"portable\",\"owner\":\"skill-graph-maintainer\",\"freshness\":\"2026-04-18\",\"drift_check\":\"{\\\\\\\"last_verified\\\\\\\":\\\\\\\"2026-05-13\\\\\\\",\\\\\\\"truth_source_hashes\\\\\\\":{\\\\\\\"scripts/skill-graph-route.js\\\\\\\":\\\\\\\"b9a7b51d0e8b845b11473f479c4593754768c3775508049db7339892b2f08cc2\\\\\\\",\\\\\\\"scripts/skill-graph-routing-eval.js\\\\\\\":\\\\\\\"fffac2858863662bde6bc54c56bb77a219ae93f626e0c8d5886566f998181deb\\\\\\\",\\\\\\\"examples/evals/skill-router.json\\\\\\\":\\\\\\\"fccabcbc5f9d8057536f397fb0fc71a567371f75fb9a21afda343b197af30293\\\\\\\",\\\\\\\"examples/evals/skill-router.routing.json\\\\\\\":\\\\\\\"c4dc88db1e746bea78a7cf96b50c6c84532a07eda42da2e35d790c8928d4da8c\\\\\\\"}}\",\"eval_artifacts\":\"present\",\"eval_state\":\"passing\",\"routing_eval\":\"present\",\"stability\":\"experimental\",\"keywords\":\"[\\\\\\\"skill routing\\\\\\\",\\\\\\\"skill dispatch\\\\\\\",\\\\\\\"keyword routing\\\\\\\",\\\\\\\"route skill\\\\\\\",\\\\\\\"which skill to use\\\\\\\",\\\\\\\"skill selector\\\\\\\",\\\\\\\"routing table\\\\\\\",\\\\\\\"coverage gap\\\\\\\",\\\\\\\"ambiguous skill activation\\\\\\\",\\\\\\\"skill activate\\\\\\\",\\\\\\\"skill activates\\\\\\\",\\\\\\\"activate skill\\\\\\\",\\\\\\\"skill should activate\\\\\\\",\\\\\\\"which skill activates\\\\\\\",\\\\\\\"why did skill activate\\\\\\\",\\\\\\\"why skill activated\\\\\\\",\\\\\\\"routing decision\\\\\\\",\\\\\\\"dispatch request\\\\\\\",\\\\\\\"dispatch agent request\\\\\\\",\\\\\\\"agent request routing\\\\\\\",\\\\\\\"route this request\\\\\\\",\\\\\\\"route the request\\\\\\\",\\\\\\\"find the right skill\\\\\\\",\\\\\\\"choose the right skill\\\\\\\",\\\\\\\"which skill handles\\\\\\\"]\",\"triggers\":\"[\\\\\\\"skill-router\\\\\\\"]\",\"examples\":\"[\\\\\\\"activate the right skill for this agent request: 'my tests are failing in CI'\\\\\\\",\\\\\\\"build a routing table that covers every agent request type we see\\\\\\\",\\\\\\\"why did the documentation skill activate when the user asked about a11y?\\\\\\\",\\\\\\\"find the coverage gaps — which agent requests match no skill at all?\\\\\\\"]\",\"anti_examples\":\"[\\\\\\\"audit the graph-audit skill for schema conformance\\\\\\\",\\\\\\\"write a guide explaining how our routing works\\\\\\\",\\\\\\\"reproduce this routing mis-dispatch from production logs\\\\\\\"]\",\"relations\":\"{\\\\\\\"boundary\\\\\\\":[{\\\\\\\"skill\\\\\\\":\\\\\\\"graph-audit\\\\\\\",\\\\\\\"reason\\\\\\\":\\\\\\\"graph-audit verifies ONE skill's metadata; skill-router chooses BETWEEN skills at request time\\\\\\\"},{\\\\\\\"skill\\\\\\\":\\\\\\\"debugging\\\\\\\",\\\\\\\"reason\\\\\\\":\\\\\\\"debugging reproduces a specific routing mis-dispatch from evidence; skill-router designs the routing table itself\\\\\\\"},{\\\\\\\"skill\\\\\\\":\\\\\\\"skill-infrastructure\\\\\\\",\\\\\\\"reason\\\\\\\":\\\\\\\"skill-infrastructure analyses routing-miss patterns across the whole library to find systemic gaps; skill-router authors the routing logic for one library at a time\\\\\\\"}],\\\\\\\"verify_with\\\\\\\":[\\\\\\\"graph-audit\\\\\\\"]}\",\"grounding\":\"{\\\\\\\"domain_object\\\\\\\":\\\\\\\"Skill Graph reference routing behavior\\\\\\\",\\\\\\\"grounding_mode\\\\\\\":\\\\\\\"repo_specific\\\\\\\",\\\\\\\"truth_sources\\\\\\\":[\\\\\\\"scripts/skill-graph-route.js\\\\\\\",\\\\\\\"scripts/skill-graph-routing-eval.js\\\\\\\",\\\\\\\"examples/evals/skill-router.json\\\\\\\",\\\\\\\"examples/evals/skill-router.routing.json\\\\\\\"],\\\\\\\"failure_modes\\\\\\\":[\\\\\\\"negation_paths_score_as_positive_matches\\\\\\\",\\\\\\\"routing_eval_claim_without_harness_pass\\\\\\\",\\\\\\\"boundary_exclusion_removes_stronger_match\\\\\\\",\\\\\\\"coverage_gap_silently_falls_back\\\\\\\"],\\\\\\\"evidence_priority\\\\\\\":\\\\\\\"repo_code_first\\\\\\\"}\",\"portability\":\"{\\\\\\\"readiness\\\\\\\":\\\\\\\"scripted\\\\\\\",\\\\\\\"targets\\\\\\\":[\\\\\\\"skill-md\\\\\\\"]}\",\"skill_graph_source_repo\":\"https://github.com/jacob-balslev/skill-graph\",\"skill_graph_protocol\":\"Skill Metadata Protocol v5\",\"skill_graph_project\":\"Skill Graph\",\"skill_graph_canonical_skill\":\"skills/skill-router/SKILL.md\"}"
+  skill_graph_source_repo: "https://github.com/jacob-balslev/skill-graph"
+  skill_graph_protocol: Skill Metadata Protocol v4
+  skill_graph_project: Skill Graph
+  skill_graph_canonical_skill: skills/skill-router/SKILL.md
+---
+
+# Skill Router
+
+## Coverage
+
+- Routing by keyword pattern: matching inbound query terms to skill `keywords` arrays to identify the best candidate
+- Routing by trigger label: matching explicit skill-router labels (`triggers` field) to eliminate ambiguity when the intent is declared
+- Routing by file path: matching touched or mentioned file paths against skill `paths` arrays for file-activated skills
+- Fallback ordering: how to rank skills when multiple candidates score equally, including `scope` and `type` tiebreakers
+- Coverage gaps: detecting when no skill matches a request and how to surface that gap as an authoring signal
+
+## Philosophy
+
+Routing is adversarial against convenience. The tempting move — "if nothing matches exactly, just pick the closest skill and activate it" — is the one that silently degrades every agent that depends on the router. A wrong skill that activates confidently is worse than a coverage gap that surfaces loudly, because silent wrongness has no signal for anyone to fix. The router's job is to produce either a certain winner or an explicit non-answer, never a confident guess.
+
+Four principles follow from that stance:
+
+- **First unique winner stops the chain.** A match on `triggers` is stronger than a match on `paths`, which is stronger than a match on `keywords`. Evaluate surfaces in priority order and stop at the first one that yields a unique winner — do not second-guess a trigger-label hit with keyword analysis.
+- **Tiebreakers favor specificity, not popularity.** When scores tie, a skill specific to *this* codebase (`scope: codebase`) wins over a portable skill, and a procedural skill (`type: workflow`) wins over a reference (`type: capability`) because the inbound query is more likely to need action than lookup. Never rank by skill age, usage count, or author preference.
+- **Explicit coverage gaps beat silent wrong fallback.** If no surface produces a winner, surface the gap to the caller — recommend authoring a new skill or broadening a keyword list. Silent fallback to a default skill is a bug that no test catches, because the misrouted query looks successful to the router but nonsensical to the downstream agent.
+- **The router is a mapping, not a judge.** It decides which skill owns a query; it does not decide whether the query is well-formed, worth handling, or strategically important. Those are the activated skill's concerns. Overloading the router with domain judgment makes it harder to audit and harder to change.
+
+## Routing Rules
+
+The router evaluates three matching surfaces in priority order. The first surface that produces a unique winner stops the evaluation chain.
+
+| Priority | Surface | Field consulted | Match rule |
+|---|---|---|---|
+| 1 | Trigger label | `triggers` | Exact match against the declared label. Winner is unambiguous. |
+| 2 | File path | `paths` | Glob match against the touched/mentioned path. Prefer the most specific match. |
+| 3 | Keyword pattern | `keywords` | Token overlap between query terms and skill keyword list. Rank by match count; break ties with `scope` then `type`. |
+
+### Scope tiebreaker
+
+When keyword scores are equal, prefer skills in this `scope` order: `codebase` > `reference` > `portable`. A codebase-scoped skill is specific to *this* repository and wins over a portable one when both match the query equally.
+
+> **Schema version note.** The v1 enum values `operational` and `generic` were renamed to `codebase` and `portable` in `schema_version: 2`. Always use the v2 names; the current schema rejects the v1 names as hard errors. A full rename map ships with the Skill Graph schema migration notes — consult those when porting a v1 skill.
+
+### Type tiebreaker
+
+After scope, prefer `workflow` over `capability` over `router` over `overlay`. A workflow skill ships procedural decision logic that is usually more actionable than a pure capability reference when the query is ambiguous.
+
+### Fallback behavior
+
+If no skill matches any surface, the router does not fall back to a default skill. It surfaces a coverage gap and recommends authoring a new skill or broadening an existing skill's `keywords` array. Silent fallback to a wrong skill is worse than an explicit coverage-gap signal.
+
+## Evals
+
+This skill ships a comprehension-eval artifact as `skill-router.json` in the Skill Graph `examples/evals/` directory. The eval prompts specifically test the priority-ordered match surfaces, the scope/type tiebreakers, and the explicit refusal to fall back to a default. The eval file is how this skill is graded by the Skill Graph audit runner — consumers in other agent runtimes can treat the eval cases as conformance tests translated to their own grading harness.
+
+## Do NOT Use When
+
+| Use instead | When |
+|---|---|
+| The target skill directly | The correct skill is already known — skip the router and load it |
+| `documentation` | The task is writing or structuring doc prose, not routing |
+| `graph-audit` | The task is auditing whether routing metadata is consistent, not dispatching a query |
+| `examples/skill-metadata-template.md` | The task is authoring a new skill from scratch, not dispatching to an existing one (the template is a reference artifact, not a routable skill) |

package/marketplace/skills/skill-scaffold/SKILL.md

@@ -0,0 +1,105 @@
+---
+name: skill-scaffold
+description: "Use when creating a new SKILL.md from scratch, adapting an existing skill to a different archetype, or teaching another author the canonical Skill Metadata Protocol frontmatter and body structure. Covers schema-conformant frontmatter, archetype-aware body layout, semantic-layer discipline (description vs Coverage), teaching-layer mechanics (TEMPLATE NOTE blockquotes), the lint-first authoring gate, and the routing-eval honesty rule. Do NOT use when modifying an already-written skill (edit it directly), when writing general technical documentation (use `documentation`), or when fixing a malformed skill detected by lint (use `graph-audit` for systematic library health, not authoring scaffold help)."
+license: MIT
+compatibility: "Markdown, YAML, JSON Schema"
+allowed-tools: Read Grep Bash Write Edit
+metadata:
+  metadata: "{\"schema_version\":6,\"version\":\"1.0.0\",\"type\":\"capability\",\"category\":\"agent\",\"domain\":\"agent/skill-system\",\"scope\":\"reference\",\"owner\":\"skill-graph-maintainer\",\"freshness\":\"2026-05-04\",\"drift_check\":\"{\\\\\\\"last_verified\\\\\\\":\\\\\\\"2026-05-14\\\\\\\",\\\\\\\"truth_source_hashes\\\\\\\":{\\\\\\\"examples/skill-metadata-template.md\\\\\\\":\\\\\\\"42b3185ebf53f9efc6a32977ee9408efce0957c0a7ed62cabca97cb83c33600a\\\\\\\",\\\\\\\"schemas/skill.v4.schema.json\\\\\\\":\\\\\\\"e83d6be8b1314488b39b8c7bec2784d6459980d3f9965be68ad1c9a53865622d\\\\\\\",\\\\\\\"docs/skill-metadata-protocol.md\\\\\\\":\\\\\\\"08ad662c5f470fac337aa559dacd0b9e882be7df8d7918f20a5d4e3aaaaa2ed7\\\\\\\"}}\",\"eval_artifacts\":\"planned\",\"eval_state\":\"unverified\",\"routing_eval\":\"absent\",\"stability\":\"experimental\",\"keywords\":\"[\\\\\\\"skill authoring\\\\\\\",\\\\\\\"new skill\\\\\\\",\\\\\\\"writing a skill\\\\\\\",\\\\\\\"skill scaffold\\\\\\\",\\\\\\\"skill template\\\\\\\",\\\\\\\"skill frontmatter\\\\\\\",\\\\\\\"skill graph contract\\\\\\\",\\\\\\\"capability or workflow\\\\\\\",\\\\\\\"description vs coverage\\\\\\\",\\\\\\\"archetype selection\\\\\\\",\\\\\\\"skill body layout\\\\\\\",\\\\\\\"teaching layer\\\\\\\",\\\\\\\"placeholder sludge\\\\\\\",\\\\\\\"cargo cult meta sections\\\\\\\",\\\\\\\"lint first authoring\\\\\\\",\\\\\\\"routing eval honesty\\\\\\\"]\",\"examples\":\"[\\\\\\\"I'm writing a new skill from scratch — where do I start?\\\\\\\",\\\\\\\"how do I pick between capability and workflow for my skill type?\\\\\\\",\\\\\\\"what's the difference between description and the ## Coverage section?\\\\\\\",\\\\\\\"scaffold a new skill that teaches react component composition patterns\\\\\\\",\\\\\\\"I copied skill-metadata-template.md but my new skill won't pass lint — help\\\\\\\",\\\\\\\"draft frontmatter for a workflow skill that owns deployment rollback\\\\\\\",\\\\\\\"how do I strip teaching annotations from the template before commit?\\\\\\\",\\\\\\\"should I flip routing_eval to present on my new skill?\\\\\\\"]\",\"anti_examples\":\"[\\\\\\\"refactor my existing skill to be more concise\\\\\\\",\\\\\\\"my skill's routing isn't activating — why?\\\\\\\",\\\\\\\"audit my skill library for stale frontmatter\\\\\\\",\\\\\\\"write a developer guide for the contributor docs\\\\\\\",\\\\\\\"review this skill's content for correctness\\\\\\\"]\",\"relations\":\"{\\\\\\\"boundary\\\\\\\":[{\\\\\\\"skill\\\\\\\":\\\\\\\"refactor\\\\\\\",\\\\\\\"reason\\\\\\\":\\\\\\\"refactor is behaviour-preserving modification of existing code or skills; skill-scaffold creates a new skill from scratch\\\\\\\"},{\\\\\\\"skill\\\\\\\":\\\\\\\"skill-router\\\\\\\",\\\\\\\"reason\\\\\\\":\\\\\\\"skill-router dispatches between existing skills at request time; skill-scaffold is the authoring-time guide for a NEW skill\\\\\\\"},{\\\\\\\"skill\\\\\\\":\\\\\\\"graph-audit\\\\\\\",\\\\\\\"reason\\\\\\\":\\\\\\\"graph-audit verifies the authored metadata of an existing skill; skill-scaffold is the authoring-time guide before a skill exists\\\\\\\"}],\\\\\\\"related\\\\\\\":[\\\\\\\"naming-conventions\\\\\\\"],\\\\\\\"verify_with\\\\\\\":[]}\",\"grounding\":\"{\\\\\\\"domain_object\\\\\\\":\\\\\\\"Authoring a new SKILL.md against Skill Metadata Protocol v5\\\\\\\",\\\\\\\"grounding_mode\\\\\\\":\\\\\\\"repo_specific\\\\\\\",\\\\\\\"truth_sources\\\\\\\":[\\\\\\\"examples/skill-metadata-template.md\\\\\\\",\\\\\\\"schemas/skill.v4.schema.json\\\\\\\",\\\\\\\"docs/skill-metadata-protocol.md\\\\\\\"],\\\\\\\"failure_modes\\\\\\\":[\\\\\\\"placeholder_sludge\\\\\\\",\\\\\\\"cargo_cult_meta_sections\\\\\\\",\\\\\\\"description_coverage_collapse\\\\\\\",\\\\\\\"authoring_gate_skipped\\\\\\\",\\\\\\\"inflated_routing_eval\\\\\\\"],\\\\\\\"evidence_priority\\\\\\\":\\\\\\\"repo_code_first\\\\\\\"}\",\"portability\":\"{\\\\\\\"readiness\\\\\\\":\\\\\\\"scripted\\\\\\\",\\\\\\\"targets\\\\\\\":[\\\\\\\"skill-md\\\\\\\"]}\",\"lifecycle\":\"{\\\\\\\"stale_after_days\\\\\\\":180,\\\\\\\"review_cadence\\\\\\\":\\\\\\\"quarterly\\\\\\\"}\",\"skill_graph_source_repo\":\"https://github.com/jacob-balslev/skill-graph\",\"skill_graph_protocol\":\"Skill Metadata Protocol v5\",\"skill_graph_project\":\"Skill Graph\",\"skill_graph_canonical_skill\":\"skills/skill-scaffold/SKILL.md\"}"
+  skill_graph_source_repo: "https://github.com/jacob-balslev/skill-graph"
+  skill_graph_protocol: Skill Metadata Protocol v4
+  skill_graph_project: Skill Graph
+  skill_graph_canonical_skill: skills/skill-scaffold/SKILL.md
+---
+
+# Skill Scaffold
+
+## Coverage
+
+- Authoring flow: copy → rename → adapt → strip teaching annotations → verify → commit
+- Frontmatter identity: `name`, `description`, `version`, `type`, `category`, `scope`, `owner`, plus the eval-health triple and `drift_check` required by every Skill Metadata Protocol skill
+- Archetype selection: how to pick between `capability`, `workflow`, `router`, and `overlay` and which `## H2` body sections each archetype requires
+- Semantic-layer discipline: how `description:` (≤ 3 sentences, pushy, boundary-aware routing contract) differs from `## Coverage` (bulleted scope map of distinct topics) and why each must stay in its own layer
+- Teaching-layer mechanics: how to use `> **TEMPLATE NOTE:**` blockquotes and `# TEMPLATE NOTE:` YAML comments to teach without cargo-culting meta sections into derived skills
+- Lint-first authoring gate: passing `node scripts/skill-lint.js --strict` against your new skill before commit, every time, no exceptions
+- Routing-eval honesty: defaulting to `routing_eval: absent` and only flipping to `present` after `node scripts/skill-graph-routing-eval.js --skill <name>` exits 0
+- Grounding declarations: when to populate `grounding.truth_sources` vs leaving the block off, and how the drift sentinel consumes recorded `truth_source_hashes`
+
+## Philosophy
+
+A scaffold teaches by example, not by placeholder. A concrete, internally consistent specimen of a finished skill is a more reliable authoring reference than any amount of abstract instruction. The teaching layer — meta-commentary about how to read and adapt the scaffold — must live in structurally distinct slots that disappear when the author tightens a new skill, never in the `## H2` section slots that AI agents copy verbatim. Authoring is also a *lint-first* discipline: the lint output is the primary debugging surface for new skills, deliberately verbose, and the canonical answer to "did I do this right?" — not a senior reviewer's pattern-match.
+
+## Authoring Flow
+
+The five steps are non-negotiable; skipping any step produces a skill that lints in your editor but breaks on someone else's machine.
+
+**Step 0 (precondition):** Before authoring, check the redundancy registry at [`_meta/REDUNDANT-SKILLS.md`](https://github.com/jacob-balslev/skills/blob/main/_meta/REDUNDANT-SKILLS.md) (in the sibling broader library). It lists skills that have been authored, evaluated via comprehension grading, and judged redundant or harmful by the grader. If your intended subject matches an entry in that registry, either skip authoring (the model already knows the topic) or document the new grounding evidence that justifies a fresh attempt — re-authoring a tombstoned skill without contradicting evidence wastes context and risks regressing on measured quality.
+
+1. **Copy** `examples/skill-metadata-template.md` to `skills/<your-skill-name>/SKILL.md`. Do not rename in-place; the template stays as the canonical specimen.
+2. **Rename** identity fields: `name`, `description`, `category` (if used), `keywords`, `examples`, `anti_examples`, `paths` (if applicable), and the body title. Every reference to "skill-metadata-template" should be gone.
+3. **Adapt** body sections to your skill's subject. Match the `## H2` layout to your declared archetype per `docs/skill-metadata-protocol.md § Archetype section map`. Remove sections that do not apply — do not keep them with placeholder content.
+4. **Strip** every `> **TEMPLATE NOTE:**` body blockquote and every `# TEMPLATE NOTE:` YAML comment. They are authoring scaffolding; shipping them in a derived skill is the most common authoring mistake. Run `grep -n "TEMPLATE NOTE" skills/<your-skill>/SKILL.md` to confirm zero hits.
+5. **Verify** by running the gate sequence: `node scripts/skill-lint.js --strict` (must show 0 errors), `node scripts/check-protocol-consistency.js` (C1-C7 must all pass), and (if you populated `examples` and `anti_examples`) `node scripts/skill-graph-routing-eval.js --skill <your-skill>` (verdict PASS before flipping `routing_eval` to `present`).
+
+## Archetype Selection
+
+Pick `type:` once, deliberately, before writing the body — the archetype determines which body sections are required.
+
+| Archetype | When to pick it | Required body sections |
+|---|---|---|
+| `capability` | The skill teaches *how to do something* with no fixed sequence (e.g., a11y, naming-conventions, prompt-craft) | `## Coverage`, `## Philosophy`, `## Verification` |
+| `workflow` | The skill orchestrates a *sequence of steps* the agent follows in order (e.g., debugging, refactor, skill-audit-loop) | `## Coverage`, `## Workflow` (numbered steps), `## Verification` |
+| `router` | The skill dispatches between *other skills* (rare; only one starter — `skill-router`) | `## Coverage`, `## Routing Rules`, `## Verification` |
+| `overlay` | The skill *specialises an `extends:` parent* with project-specific or stack-specific overrides (e.g., `lint-overlay`) | `## Overlay Rules` plus everything inherited from the parent's archetype |
+
+The fastest way to pick wrong: choose `workflow` because your skill happens to list ordered steps in the body. If the *user* could reasonably consume the skill in any order based on the section they need, it is a `capability`, not a `workflow`. Workflows are skills the agent literally walks through start-to-end every time.
+
+## Semantic-Layer Discipline
+
+`description` and `## Coverage` look like duplicates and are not. They live in different layers and serve different consumers.
+
+- `description` (≤ 3 sentences, frontmatter): the **routing contract**. Pushy, specific, boundary-aware. Tells a router whether to activate this skill for a given query. Should include an explicit "Do NOT use for…" boundary clause so the router doesn't over-activate.
+- `## Coverage` (bulleted list, body): the **scope map**. Enumerates the distinct topics this skill teaches. The reader scans `## Coverage` to decide whether to read further. Should NOT restate `description` as a single line; should NOT be a checklist of placeholder commitments.
+
+If you can drop your `description` into `## Coverage` without changing meaning, both layers are wrong. Rewrite `description` until it is too pushy for the body, then rewrite `## Coverage` until it is too enumerative for the description.
+
+## Common Authoring Mistakes
+
+| Mistake | Symptom | Fix |
+|---|---|---|
+| Placeholder sludge | `description: "Use when... for..."`, paths like `your/file.md`, `todo` markers | Search the file for `your-`, `path/to/`, `todo`, `lorem`. Zero hits before commit. |
+| Cargo-culted teaching layer | `> **TEMPLATE NOTE:**` blocks survive into derived skill | `grep -n "TEMPLATE NOTE" skills/<name>/SKILL.md` returns nothing |
+| Description-Coverage collapse | `description` and `## Coverage` say the same thing in different shapes | Rewrite description as routing contract, Coverage as scope map (see § Semantic-Layer Discipline) |
+| Inflated routing_eval | `routing_eval: present` set without running the harness | Default to `absent`. Flip to `present` only after `node scripts/skill-graph-routing-eval.js --skill <name>` returns PASS |
+| Wrong archetype | Skill body sections don't match `type:` | Re-pick archetype per § Archetype Selection; rewrite the body to match |
+| Anti-examples for skills that don't exist | `anti_examples` references skills not in the library | Either author those skills first or use existing starter names |
+| Lint-skipped commit | New skill is committed without `--strict` lint pass | Run `node scripts/skill-lint.js --strict` before every commit; fix all errors |
+
+## Verification
+
+Use this checklist as the authoring gate before committing a skill. Every item must pass.
+
+- [ ] Every retained field has a real reason to exist in the new skill
+- [ ] Every removed field was removed because of archetype or grounding mismatch, not laziness
+- [ ] Body sections match the declared archetype per `docs/skill-metadata-protocol.md § Archetype section map`
+- [ ] `description:` is ≤ 3 sentences, contains pushy trigger phrases, and names an explicit negative boundary
+- [ ] `## Coverage` is a scope map of distinct topics, not a one-line restate of the description
+- [ ] `drift_check` is an object with `last_verified`; `truth_source_hashes` recorded when truth sources exist
+- [ ] `compatibility` is an object (not a free-text string) when present
+- [ ] `eval_artifacts`, `eval_state`, `routing_eval` reflect the actual skill state — no inflation
+- [ ] All `relations` entries point to skills that exist in the target repo; `boundary` entries with non-obvious rationale use the `{skill, reason}` form
+- [ ] No placeholder sludge (`your-skill-name`, `path/to/file`, `todo`) remains
+- [ ] No `> **TEMPLATE NOTE:**` blockquotes or `# TEMPLATE NOTE:` YAML comments remain
+- [ ] `node scripts/skill-lint.js --strict` returns 0 errors against the new skill
+- [ ] `node scripts/check-protocol-consistency.js` passes C1-C7
+- [ ] If `routing_eval: present`, `node scripts/skill-graph-routing-eval.js --skill <name>` returns verdict PASS
+
+## Do NOT Use When
+
+| Use instead | When |
+|---|---|
+| `documentation` | Writing general technical documentation (guides, tutorials, references) — not a skill specifically |
+| `refactor` | Modifying an existing skill's content while preserving its identity |
+| `graph-audit` | Auditing the metadata health of skills already in the library |
+| `skill-router` | Diagnosing why a router doesn't activate an existing skill on a given query |
+| `code-review` | Reviewing the technical content of a skill (correctness, clarity) once authored |