@skill-graph/cli 0.5.6

package/examples/exports/debugging.skill-md.md

@@ -0,0 +1,80 @@
+---
+name: debugging
+description: "Use when behavior is broken, a test is failing, or runtime output contradicts expectations. Covers failure reproduction, scope reduction by bisection, evidence capture at the moment of failure, root-cause isolation (not symptom patching), fix verification against the same evidence path, and regression-test creation. Do NOT use for feature planning, architectural design, or behavior-preserving refactor."
+license: MIT
+compatibility: "Markdown, Git, any codebase"
+allowed-tools: Read Grep Bash
+metadata:
+  schema_version: "4"
+  version: "1.0.0"
+  type: workflow
+  category: engineering
+  scope: portable
+  owner: skill-graph-maintainer
+  freshness: "2026-04-18"
+  drift_check: "{\"last_verified\":\"2026-04-18\"}"
+  eval_artifacts: present
+  eval_state: passing
+  routing_eval: present
+  stability: experimental
+  keywords: "[\"debugging\",\"reproduce failure\",\"reproduce bug\",\"failing test\",\"root cause\",\"symptom vs cause\",\"minimum reproduction\",\"bisect\",\"what caused it\",\"my tests are failing\",\"why is this broken\",\"it broke in production\",\"cannot reproduce\",\"test passes locally\",\"stack trace\",\"used to work\",\"worked yesterday\",\"what changed\",\"was working before\",\"agent stuck\",\"stuck in a loop\",\"stuck in loop\",\"blocking my commit\",\"blocking the build\",\"specific error\",\"specific failure\",\"diagnose failure\",\"error blocking\",\"broke the build\",\"broke build\"]"
+  triggers: "[\"debugging-skill\"]"
+  examples: "[\"my tests pass locally but fail in CI — why?\",\"this function used to work yesterday; what changed?\",\"reproduce this Stripe webhook failure from production logs\",\"I see the symptom but can't find the root cause of this nil panic\"]"
+  anti_examples: "[\"plan test coverage for a new feature\",\"document what this function does for future readers\",\"refactor this messy code while the test suite is green\"]"
+  relations: "{\"boundary\":[{\"skill\":\"documentation\",\"reason\":\"documentation is durable reference prose; debugging is transient failure-chasing\"},{\"skill\":\"testing-strategy\",\"reason\":\"testing-strategy plans what to test before a failure exists; debugging chases a specific observed failure\"},{\"skill\":\"refactor\",\"reason\":\"refactor is behavior-preserving code change with green tests; debugging is invoked because tests or behavior are NOT green\"}],\"verify_with\":[\"testing-strategy\"]}"
+  portability: "{\"readiness\":\"scripted\",\"targets\":[\"skill-md\"]}"
+---
+
+# Debugging
+
+## Coverage
+
+- Reproduction: turning a vague bug report into a deterministic failing case
+- Scope reduction: isolating the smallest surface where the failure still reproduces
+- Evidence capture: collecting logs, stack traces, and state snapshots at the moment of failure
+- Root-cause isolation: distinguishing symptoms from causes and resisting the urge to patch symptoms
+- Fix verification: re-running the original failure path to confirm the fix is real
+- Regression prevention: converting the failing case into a permanent test so the same bug cannot return silently
+
+## Philosophy
+
+The fastest way to fix a bug is usually the wrong fix. A working reproduction is worth more than a plausible hypothesis; a plausible hypothesis is worth more than a clever fix; a clever fix that skips the reproduction step ships the same bug again under a different name. When pressure is high the temptation to jump from symptom to patch is also high — resist it, because the cost of a wrong fix is paid again by the next person who hits the same failure with less context than you had.
+
+## Workflow
+
+Each step asks a question. The answer decides the next step. Do not skip steps to save time; the steps exist because skipping them is how bugs return.
+
+| Step | Ask | If yes | If no |
+|---|---|---|---|
+| 1. Reproduce | Do you have a deterministic failing case? | Go to step 2 | Add logging, narrow inputs, or run the failing path in a loop until the failure is reliable |
+| 2. Scope | Can you reproduce it in a surface smaller than the full system? | Go to step 3 | Bisect — halve the code path, data, or config and retry |
+| 3. Evidence | Do you have the state at the moment of failure, not just the symptom after? | Go to step 4 | Add instrumentation at the boundary where state flips wrong |
+| 4. Cause | Does your hypothesis explain ALL of the evidence, not just the visible symptom? | Go to step 5 | Form a better hypothesis — partial explanations hide shared root causes |
+| 5. Verify | Does the same evidence path pass with the fix applied, and fail with it reverted? | Go to step 6 | The fix did not land or the cause was wrong — return to step 4 |
+| 6. Regression test | Does the test you just wrote fail without the fix and pass with it? | Done | Your test is not isolating the cause — rewrite it |
+
+### When to stop and escalate
+
+- Step 1 is still unreproducible after ~60 min of narrowing → suspect non-determinism (race, timing, clock, network). This is a design issue, not a debugging issue.
+- Step 3 instrumentation shows contradictory state on the same object → suspect memory corruption, concurrent mutation, or stale cache. Out of scope for a single-file debugger; escalate to architectural review.
+- The same bug returned after a previous fix → the previous fix patched a symptom. Start over at step 1 and find the real cause.
+
+## Evals
+
+This skill ships a comprehension-eval artifact at [`examples/evals/debugging.json`](../../examples/evals/debugging.json). The `Verification` checklist below is the authoring gate for a completed debugging pass; the eval file is how this skill is graded by `scripts/skill-audit.js --graded`. Do not conflate them — the checklist is for the debugger, the eval is for the grader.
+
+## Verification
+
+- [ ] The original failure was reproduced deterministically, not just described
+- [ ] The hypothesis explains every piece of evidence collected, not a subset
+- [ ] The fix was verified by the same evidence path that revealed the bug
+- [ ] A regression test fails without the fix and passes with it
+- [ ] The next engineer who hits this failure can reach the fix from the regression test alone
+
+## Do NOT Use When
+
+| Use instead | When |
+|---|---|
+| `refactor` | The task is structural cleanup, not failure-driven diagnosis |
+| `testing-strategy` | The task is planning what to test, not chasing a known failure |
+| `documentation` | The task is explaining behavior, not fixing broken behavior |

package/examples/exports/refactor.skill-md.md

@@ -0,0 +1,78 @@
+---
+name: refactor
+description: "Use when reorganizing existing code without changing external behavior — extracting functions, reducing duplication, renaming for clarity, splitting modules, or tightening structure. Covers behavior preservation, duplication reduction, decomposition, naming improvements, structural reorganization, and before/after verification. Do NOT use for bug investigation, adding new product behavior, or writing documentation (even when the docs describe the refactored code)."
+license: MIT
+compatibility: "Markdown, Git, any codebase"
+allowed-tools: Read Grep Bash
+metadata:
+  schema_version: "4"
+  version: "1.0.0"
+  type: workflow
+  category: engineering
+  scope: portable
+  owner: skill-graph-maintainer
+  freshness: "2026-04-18"
+  drift_check: "{\"last_verified\":\"2026-04-18\"}"
+  eval_artifacts: present
+  eval_state: passing
+  routing_eval: present
+  stability: experimental
+  keywords: "[\"refactor\",\"cleanup\",\"simplify\",\"extract function\",\"reduce duplication\",\"clean this up\",\"simplify this\",\"rename this\",\"split this file\",\"too long function\",\"duplicated logic\",\"decompose function\",\"decompose code\",\"decompose long\",\"split by responsibility\",\"behavior preserving\",\"rename module\",\"rename utils\",\"messy code\",\"messy suite\",\"extract helper\",\"extract duplicated\",\"consolidate logic\",\"tighten structure\"]"
+  triggers: "[\"refactor-skill\"]"
+  examples: "[\"this 600-line function is hard to reason about — decompose it while keeping tests green\",\"extract the duplicated validation logic from these three handlers into a helper\",\"rename this module from `utils` to something that describes what it actually does\",\"split this file by responsibility; no behavior changes, tests must still pass\"]"
+  anti_examples: "[\"the test is failing after my edit — what did I break?\",\"write an architecture note explaining this pattern for new team members\",\"reproduce why this function retries three times on transient network errors\"]"
+  relations: "{\"boundary\":[{\"skill\":\"documentation\",\"reason\":\"documentation is prose about the code; refactor is behavior-preserving changes to the code itself\"},{\"skill\":\"debugging\",\"reason\":\"debugging chases an observed failure; refactor runs only with a green test suite and preserves behavior\"}],\"verify_with\":[\"testing-strategy\"],\"depends_on\":[{\"skill\":\"testing-strategy\",\"min_version\":\"^1.0.0\"}]}"
+  portability: "{\"readiness\":\"scripted\",\"targets\":[\"skill-md\"]}"
+---
+
+# Refactor
+
+## Coverage
+
+- Behavior preservation: identifying the external contract that must remain stable before any change
+- Duplication reduction: consolidating repeated logic without over-abstraction
+- Decomposition: extracting functions, modules, or types to improve readability and reuse
+- Naming improvements: renaming so identifiers carry their real meaning
+- Structure improvements: reorganizing file and module boundaries when the current layout obscures intent
+- Verification before and after: running the same behavioral checks on both sides of the change
+
+## Philosophy
+
+Refactoring pays off only when the shape of the code has diverged from the shape of the problem. Before that point it is risk without reward — every move invites a regression, and "cleaner" is a preference, not a justification. The honest test for a legitimate refactor is not "this feels better" but "the next concrete change will be materially easier because of this one." If you cannot name the next change, stop — you are rearranging, not refactoring, and the safest rearrangement is none.
+
+## Workflow
+
+Each step decides whether to continue, split, or stop. "Stop" is always a valid answer; speculative refactoring is a failure mode, not a signal of ambition.
+
+| Step | Ask | If yes | If no |
+|---|---|---|---|
+| 1. Contract | What externally observable behavior must stay the same? | Write it down as a test suite or explicit checklist | Stop — you cannot refactor what you cannot pin down |
+| 2. Next-change justification | Can you name one concrete pending change that becomes easier because of this refactor? | Go to step 3 | Stop — you are rearranging for taste, not improving the codebase |
+| 3. Smallest useful cut | What is the smallest structural change that moves toward the next-change goal? | Make only that change | Split into sequential cuts; do not change multiple abstraction layers at once |
+| 4. Behavior re-verify | Does the contract from step 1 still hold exactly? | Commit | Revert; the refactor was not behavior-preserving. Start over smaller |
+| 5. Stop condition | Have you made the next change materially easier than it would have been before? | Done | Do not keep going — refactoring beyond the next change is speculative waste |
+
+### When to back out
+
+- A green test from before the refactor is now red → revert immediately, then cut smaller.
+- The next-change goal shifted during the refactor → restart at step 2 with the new goal before continuing.
+- The refactor requires touching more than one abstraction layer in a single commit → split into per-layer commits and re-verify each.
+
+## Evals
+
+This skill ships a comprehension-eval artifact at [`examples/evals/refactor.json`](../../examples/evals/refactor.json). The `Verification` checklist below is the authoring gate for a completed refactor; the eval file is how this skill is graded by `scripts/skill-audit.js --graded`. Do not conflate them — the checklist is for the engineer, the eval is for the grader.
+
+## Verification
+
+- [ ] External behavior is unchanged — same tests green before and after
+- [ ] The named next change is now demonstrably easier, not merely "more possible"
+- [ ] No new abstraction was introduced speculatively (no "future-proofing" without a named consumer)
+- [ ] Each commit is a single structural change, not a bundle of rearrangements
+
+## Do NOT Use When
+
+| Use instead | When |
+|---|---|
+| `debugging` | The task starts from a failing behavior, not from structural cleanup |
+| `documentation` | The task is rewriting docs — even docs about the refactored code — it belongs to a separate commit and skill |
+| `testing-strategy` | The task is designing a new test suite; the refactor's own tests should already exist before step 1 |

package/examples/exports/testing-strategy.skill-md.md

@@ -0,0 +1,81 @@
+---
+name: testing-strategy
+description: "Use when planning tests for a bug fix, feature, or refactor — deciding what deserves a test, at which level, with what evidence. Covers test-scope decisions, test-level selection (unit / integration / contract / e2e), effort-to-risk matching, regression targeting, evidence quality, and failure-case coverage. Do NOT use for chasing a known failure (that is `debugging`), for pure doc writing (that is `documentation`), or for conceptual architecture discussion with no verification target (no dedicated skill — treat as strategy, not testing)."
+license: MIT
+compatibility: "Markdown, Git, any codebase"
+allowed-tools: Read Grep Bash
+metadata:
+  schema_version: "4"
+  version: "1.0.0"
+  type: capability
+  category: quality
+  scope: portable
+  owner: skill-graph-maintainer
+  freshness: "2026-04-18"
+  drift_check: "{\"last_verified\":\"2026-04-18\"}"
+  eval_artifacts: present
+  eval_state: passing
+  routing_eval: present
+  stability: experimental
+  keywords: "[\"testing strategy\",\"what to test\",\"what not to test\",\"which test level\",\"test scope\",\"effort vs risk\",\"regression target\",\"failure case coverage\",\"test plan\",\"do I need a test\",\"should I test this\",\"unit or integration\",\"test coverage\",\"pin this behavior\",\"plan test coverage\",\"plan coverage\",\"needs an automated test\",\"automated test\",\"manual QA coverage\",\"passes manual QA\",\"test level decision\"]"
+  triggers: "[\"testing-skill\"]"
+  routing_bundles: "[\"quality\"]"
+  examples: "[\"do I need a unit test for this pure formatter or is integration enough?\",\"what's the right test level for a webhook handler that talks to Stripe?\",\"the feature passes manual QA — does it need an automated test?\",\"pin this regression so the same bug can't slip through again\"]"
+  anti_examples: "[\"my existing test is failing — why?\",\"write a testing-patterns guide for the contributor docs\",\"clean up this duplicated test setup across three files\"]"
+  relations: "{\"boundary\":[{\"skill\":\"documentation\",\"reason\":\"documentation is durable prose; testing-strategy is active verification planning\"},{\"skill\":\"debugging\",\"reason\":\"debugging chases a specific observed failure; testing-strategy decides what to test BEFORE a failure exists\"},{\"skill\":\"refactor\",\"reason\":\"refactor reshapes code (including test setup) while preserving behavior; testing-strategy decides what coverage to author in the first place\"}],\"verify_with\":[\"debugging\"]}"
+  portability: "{\"readiness\":\"scripted\",\"targets\":[\"skill-md\"]}"
+---
+
+# Testing Strategy
+
+## Coverage
+
+- Test scope: deciding what behavior actually needs a test, and what does not earn the maintenance cost
+- Test level selection: choosing between unit, integration, contract, and end-to-end tests based on risk and coupling
+- Effort-to-risk matching: investing verification effort where regressions are most likely and most damaging
+- Regression targeting: writing tests that pin the specific behavior a change risks breaking, not generic coverage
+- Evidence quality: preferring concrete, reproducible verification over assumed or manual checks
+- Failure-case coverage: ensuring boundary conditions and error paths are tested, not only the happy path
+
+## Philosophy
+
+Most test suites fail the effort-to-risk test: they exercise code that will never break and skip code that breaks in production. The correct target is the behavior that ships to users, not the code you happen to have written last. Coverage percentage is a proxy, and every proxy eventually gets gamed — the real signal is regressions caught before release. A test that never fails is noise; a test that fails without isolating the cause is worse than no test at all because it wastes the next engineer's time.
+
+## Test-Level Selection
+
+Pick the test level by the risk of the change and the coupling of the behavior, not by the file you happen to be editing. Unit tests are cheap to write and cheap to pass; integration and contract tests are where real production bugs are actually caught.
+
+| Situation | Test level | Why |
+|---|---|---|
+| Pure function, single-owner, no I/O | **Unit** | Fast, deterministic, zero setup. If you cannot unit-test it, the function is doing too much |
+| Logic that composes multiple units inside one service | **Integration** (in-process) | Unit tests of each piece will miss composition bugs; integration test catches real wiring |
+| Behavior that crosses a service / process / network boundary | **Contract** | Both sides need a shared verifiable agreement; a unit test on either side misses the real failure mode |
+| User-visible flow end-to-end | **E2E** (one or two per critical path) | Proves the full path works at least once; too expensive to run for every code path |
+| Bug fix for a bug that reached production | **Regression** at the level where the bug slipped through | If it slipped past unit tests, a unit test won't catch it next time; write the test at the level the bug exposed |
+| Behavior that is "obviously correct," unchanged for a year, no external pressure | **No new test** | The test would never fail; it would only add maintenance cost. Every test is a liability until it catches a bug |
+
+### Level-selection anti-patterns
+
+- **Unit testing what should be an integration test** — mocking the only thing that could actually break. Fix: test the real integration, or admit the unit test proves nothing.
+- **Integration testing what should be a unit test** — slow setup for a function that has no dependencies. Fix: extract the pure logic and unit-test it.
+- **E2E-testing every code path** — fragile, slow, flaky. Fix: one E2E per critical user journey, unit/integration for the rest.
+- **Adding a test because coverage dropped** — test has no regression target and never fails meaningfully. Fix: either find a real regression to pin, or delete the uncovered code if it has no value.
+
+## Evals
+
+This skill ships a comprehension-eval artifact at [`examples/evals/testing-strategy.json`](../../examples/evals/testing-strategy.json). The `Verification` checklist below is the authoring gate for a completed test plan; the eval file is how this skill is graded by `scripts/skill-audit.js --graded`. Do not conflate them — the checklist is for the test author, the eval is for the grader.
+
+## Verification
+
+- [ ] The test type matches the change risk
+- [ ] A behavior or regression target is explicit
+- [ ] Verification evidence is concrete, not assumed
+- [ ] Failure cases and boundaries are covered, not only the happy path
+
+## Do NOT Use When
+
+| Use instead | When |
+|---|---|
+| `documentation` | The task structures explanation for a reader, not verification for a change |
+| `debugging` | The task is chasing a known failure — strategy is planned before the failure, not after |
+| `refactor` | The task is restructuring code; any test work is to preserve existing behavior, which belongs to the refactor skill's verification step |

package/examples/projects/markdown-static-site/README.md

@@ -0,0 +1,115 @@
+# Specimen Project — Multi-Tenant Markdown Static Site
+
+> **Status:** Specimens, not a maintained starter pack.
+>
+> These five `SKILL.md` files are *illustrative*. They show what the Skill Metadata Protocol contract looks like when applied to a recognizable real-world project (a multi-tenant markdown static site with a build-time image pipeline, a periodic link-rot scan, and a content-source router). They are not production skills — the truth-source paths point at files that exist in a *hypothetical* adopter's project, not in this repository. If you adopt one of these specimens for your own library, copy the `SKILL.md`, replace the truth-source paths with your real ones, and re-record the drift baseline.
+>
+> The stack is deliberately low-stakes: even if a reader template-copies one of these specimens and gets it slightly wrong, no payment, auth, or tenant-isolation boundary is compromised. The contract features (typed relations, grounding, drift detection, project tagging, archetype discipline) work the same against any stack.
+
+## What this directory demonstrates
+
+The five specimens cover three Skill Graph archetypes (`capability`, `workflow`, `router`) at both relevant scopes (`codebase`, `portable`) and exercise the most-used contract features. The fourth archetype (`overlay`) is covered by the `lint-overlay` starter in the main `skills/` library.
+
+| Specimen | Archetype | Scope | What it uniquely demonstrates |
+|---|---|---|---|
+| [`markdown-post-frontmatter-validation`](skills/markdown-post-frontmatter-validation/SKILL.md) | `capability` | `codebase` | Codebase-grounded capability with full `grounding` block, hierarchical `category` (`content/markdown/frontmatter`), and pushy `description` activation language |
+| [`image-optimization-pipeline-config`](skills/image-optimization-pipeline-config/SKILL.md) | `capability` | `codebase` | Five concrete `failure_modes`, demonstrating the value of enumerable failure categories the eval grader can target (the canonical example of "what does a good `failure_modes` list look like") |
+| [`link-rot-detection`](skills/link-rot-detection/SKILL.md) | `capability` | `portable` | The `portable` scope — repo-agnostic knowledge that does NOT need a `grounding` block (compare to the codebase-scoped specimens) |
+| [`content-source-router`](skills/content-source-router/SKILL.md) | `router` | `codebase` | The `router` archetype with its required `## Routing Rules` section and the anti-default doctrine surfaced in the body |
+| [`migrate-posts-to-v2-frontmatter`](skills/migrate-posts-to-v2-frontmatter/SKILL.md) | `workflow` | `codebase` | The `workflow` archetype with its required `## Workflow` section, plus a `relations.depends_on` declaration |
+
+## The conceptual relationship graph
+
+The five specimens form a graph in concept (read this as a domain map, not as their literal `relations` blocks — see the note below):
+
+```
+                        ┌─────────────────────────────────┐
+                        │ migrate-posts-to-v2-frontmatter │
+                        │ (workflow)                      │
+                        │                                 │
+                        │ depends conceptually on:        │
+                        │   - markdown-post-frontmatter-  │
+                        │     validation (the migration   │
+                        │     re-validates against the    │
+                        │     same schema this capability │
+                        │     owns; flipping the validator│
+                        │     is unsafe unless the        │
+                        │     capability's contract is    │
+                        │     authored correctly)         │
+                        └────────────┬────────────────────┘
+                                     │
+                                     │ (conceptual dependency)
+                                     ▼
+                  ┌───────────────────────────────────────┐
+                  │ markdown-post-frontmatter-validation  │
+                  │ (capability)                          │
+                  │                                       │
+                  │ Owns the contract for the YAML        │
+                  │ block at the top of every content     │
+                  │ file — required fields, tag           │
+                  │ vocabulary, slug consistency.         │
+                  └───────────────────────────────────────┘
+
+   ┌──────────────────────────────────┐    ┌─────────────────────────────────┐
+   │ image-optimization-pipeline-     │    │ content-source-router           │
+   │ config (capability)              │◀───│ (router)                        │
+   │                                  │    │                                 │
+   │ Owns the build-time image        │    │ Dispatches between markdown,    │
+   │ pipeline contract — formats,     │    │ MDX, and CMS-synced sources by  │
+   │ srcset breakpoints, quality.     │    │ file extension or content-path  │
+   └──────────────────────────────────┘    │ prefix. Routes a request for a  │
+                                           │ post to the right source skill. │
+                                           └─────────────────────────────────┘
+
+   ┌──────────────────────────────────┐
+   │ link-rot-detection               │   (portable — applies to any        │
+   │ (capability)                     │    markdown-content project; not    │
+   │                                  │    coupled to this site's specific  │
+   │ Periodic external-link scanner.  │    file paths or build pipeline)    │
+   │ Reports broken links nightly.    │
+   └──────────────────────────────────┘
+```
+
+## Note on `relations` in these specimens
+
+The Skill Graph lint enforces that every target named in `relations.depends_on`, `relations.verify_with`, etc. resolves to a real skill in `<repo>/skills/`. These specimen skills live at `examples/projects/markdown-static-site/skills/`, not in `<repo>/skills/`, so cross-specimen relations would fail lint.
+
+To keep the specimens lint-clean, their `relations` blocks point at **real existing starter skills in this Skill Graph repository** (`testing-strategy`, `documentation`, `refactor`, `debugging`, `graph-audit`). The conceptual specimen-to-specimen relationships are documented in the diagram above and in each specimen's body prose. If you copy these specimens into a real adopter library where the sibling specimens are also present as production skills, you can additionally add cross-specimen `depends_on` entries — for example, `migrate-posts-to-v2-frontmatter` `depends_on: markdown-post-frontmatter-validation` — and lint will validate them.
+
+## How to verify a specimen
+
+```bash
+# Lint a single specimen with --strict (zero warnings allowed)
+node scripts/skill-lint.js --strict --skip-generator-parity \
+  examples/projects/markdown-static-site/skills/markdown-post-frontmatter-validation/SKILL.md
+
+# Lint all five specimens (one command per specimen)
+for spec in markdown-post-frontmatter-validation \
+            image-optimization-pipeline-config \
+            link-rot-detection \
+            content-source-router \
+            migrate-posts-to-v2-frontmatter; do
+  echo "=== Linting $spec ==="
+  node scripts/skill-lint.js --strict --skip-generator-parity \
+    "examples/projects/markdown-static-site/skills/$spec/SKILL.md"
+done
+```
+
+`--skip-generator-parity` is needed because the manifest sample at `examples/skills.manifest.sample.json` is generated only from `skills/`, not from this specimen directory. The skip is intentional — these specimens are demonstrations, not production library entries.
+
+## Adopting a specimen for your own library
+
+1. Copy the `SKILL.md` from this specimen directory to your own `skills/<name>/SKILL.md`
+2. Replace the `truth_sources` paths under `grounding` with the real file paths in your repository
+3. Replace the `paths:` glob entries with globs that match your real directory layout
+4. Update `owner` to your team handle
+5. Re-record the drift baseline: `node scripts/skill-graph-drift.js --record --apply skills/<name>`
+6. If you want to express cross-specimen dependencies as `relations.depends_on` (e.g., `migrate-posts → markdown-post-frontmatter-validation`), add them once the sibling specimens are also in your `skills/` directory
+
+The specimens are MIT-licensed (per each `SKILL.md` frontmatter) so you can adapt them freely.
+
+## Why this stack and not another?
+
+This specimen pack was deliberately chosen to be a low-stakes, recognizable, multi-tenant content stack: a markdown static site with a build pipeline, a periodic maintenance job, and a multi-source dispatch. Every working developer has built (or could build) something shaped like this. Critically, the stack involves **no security-critical primitives** — no payment processing, no auth flows, no tenant-isolation boundaries, no cryptographic verification. If a reader template-copies one of these specimens and gets it slightly wrong, the worst outcome is a broken image variant or a 404 on a bad route — not a customer-affecting incident.
+
+The Skill Metadata Protocol features the specimens demonstrate (typed relations, grounding, drift detection, project tags, archetype discipline) work identically against any stack. A future specimen pack against a different stack would exercise the same contract; pick one whose worst-case mistake matches your risk tolerance.

package/examples/projects/markdown-static-site/skills/content-source-router/SKILL.md

@@ -0,0 +1,131 @@
+---
+# yaml-language-server: $schema=https://skillgraph.dev/schemas/skill.v4.schema.json
+schema_version: 4
+name: content-source-router
+description: "Use when dispatching a content-fetch task across the multiple sources the site reads from — local markdown under `content/`, MDX with React components under `content/mdx/`, and a headless-CMS sync under `lib/cms/`. Activate this skill whenever the task says 'render this content' or 'where does this post come from' without naming a specific source, or when adding a new source to the routing surface. Do NOT use for the actual rendering of one source (use the per-source skill — `markdown-post-frontmatter-validation`, an MDX rendering skill, or a CMS-sync skill) or for chasing a specific routing bug (use debugging)."
+version: 0.1.0
+type: router
+category: content
+domain: content/routing
+scope: codebase
+owner: markdown-static-site-maintainer
+freshness: "2026-05-06"
+drift_check:
+  last_verified: "2026-05-06"
+eval_artifacts: none
+eval_state: unverified
+routing_eval: absent
+stability: experimental
+license: MIT
+compatibility:
+  runtimes:
+    - node
+  node: ">=20"
+  notes: "Source dispatch by file extension and content-path prefix; assumes a unified content router."
+allowed-tools: Read Grep
+keywords:
+  - content source router
+  - content dispatch
+  - which content source
+  - markdown vs mdx
+  - cms vs local
+  - source dispatch
+  - content routing
+  - source selection
+  - content-fetch routing
+triggers:
+  - content-source-router
+paths:
+  - "lib/content/router.ts"
+  - "lib/content/sources/markdown.ts"
+  - "lib/content/sources/mdx.ts"
+  - "lib/content/sources/cms.ts"
+examples:
+  - "the content fetcher just received a request — which source do I read from?"
+  - "add a fourth source (e.g., Notion API) to the routing table"
+  - "why did the router pick MDX when the file extension is `.md`?"
+  - "design the routing precedence between local files and the CMS sync"
+anti_examples:
+  - "render this MDX page with React components"
+  - "the CMS sync is producing duplicate posts"
+  - "write a guide explaining the content routing"
+relations:
+  boundary:
+    - skill: documentation
+      reason: "documentation writes prose ABOUT routing; this router is the routing logic itself"
+    - skill: debugging
+      reason: "debugging chases a specific routing mis-dispatch; this skill designs the routing table"
+    - skill: refactor
+      reason: "refactor restructures code; this skill defines the dispatch contract that any refactor must preserve"
+  verify_with:
+    - graph-audit
+grounding:
+  domain_object: "Content source dispatch — the table that selects between local markdown, local MDX with React components, and headless-CMS-synced content based on file extension, content-path prefix, or explicit source hint"
+  grounding_mode: repo_specific
+  truth_sources:
+    - lib/content/router.ts
+    - lib/content/sources/markdown.ts
+    - lib/content/sources/mdx.ts
+    - lib/content/sources/cms.ts
+  failure_modes:
+    - silent_fallback_to_default_source
+    - file_extension_check_skipped
+    - cms_sync_drift_path_to_source_map_stale
+    - new_source_added_without_router_update
+    - error_response_from_one_source_silently_retried_via_another
+  evidence_priority: repo_code_first
+portability:
+  readiness: scripted
+  targets:
+    - skill-md
+workspace_tags:
+  - content
+  - static-site
+lifecycle:
+  stale_after_days: 90
+  review_cadence: quarterly
+---
+
+# Content Source Router
+
+## Coverage
+
+- File-extension dispatch — `.md` routes to the markdown source, `.mdx` routes to the MDX source, no extension or `.cms.json` routes to the CMS source
+- Content-path prefix dispatch — `content/posts/**` routes to local sources; `content/cms-synced/**` routes to the CMS source even if the file extension is `.md`
+- Explicit source hints — internal callers (preview tools, manual reconciliation) pass an explicit `source` parameter that bypasses inspection
+- Coverage-gap surfacing — when no detection rule matches a request, the router returns a structured "unknown source" result; it never silently picks a default
+- Adding a new source — the workflow for landing a fourth source (Notion API, Sanity, etc.) without breaking the existing three (registration, routing precedence, fixture test, end-to-end content-fetch sanity)
+
+## Philosophy
+
+A content router is a dispatch surface that has to be exactly right or the rest of the site reads the wrong content. Every misroute is either a 404 (the user sees nothing) or a wrong-content render (the user sees a different post than the URL implies). The discipline is the same anti-default doctrine the `skill-router` applies to skills: prefer an explicit signal over an inferred one, prefer an unambiguous match over a "best guess," and prefer surfacing a coverage gap loudly over silently routing to a default.
+
+## Routing Rules
+
+The router evaluates four signals in priority order. The first signal that produces an unambiguous winner stops the chain.
+
+| Priority | Signal | Source | Match rule |
+|---|---|---|---|
+| 1 | Explicit `source` parameter | Internal callers (preview, manual reconciliation) | Exact match against the `Source` enum. Bypasses all subsequent inspection. |
+| 2 | Content-path prefix | Inbound request path | First matching prefix wins: `content/posts/` → markdown; `content/mdx/` → mdx; `content/cms-synced/` → cms. |
+| 3 | File extension | Resolved file path | `.md` → markdown; `.mdx` → mdx; `.cms.json` → cms. |
+| 4 | Explicit `source_hint` in query string | Trusted internal callers | Last-resort hint; surfaced as a warning in the router's audit log. |
+
+### Coverage-gap behavior
+
+If no signal produces a match, the router returns `{ ok: false, reason: 'unknown_source', evidence: {...} }`. It does NOT fall back to a default source. The caller must handle the unknown-source case explicitly — typically by responding HTTP 404 and logging the full request shape for human triage.
+
+### Adding a new source
+
+1. Add the new source's path prefix and file extension to the priority-2 and priority-3 detection tables
+2. Add a source implementation in `lib/content/sources/<source>.ts` that mirrors the markdown source's interface
+3. Add the new source to the `Source` enum used at priority 1
+4. Add an end-to-end test that requests a fixture path matched by the new source and asserts the router selects it — without this, the router will silently fall through
+
+## Do NOT Use When
+
+| Use instead | When |
+|---|---|
+| `markdown-post-frontmatter-validation` | The task is the actual frontmatter parsing for the markdown source — the router decides which source to read from, the source-specific skill validates and parses |
+| `debugging` | A specific routing decision is wrong in production logs and you need to reproduce |
+| `documentation` | The task is writing a contributor doc about the routing architecture |

package/examples/projects/markdown-static-site/skills/image-optimization-pipeline-config/SKILL.md

@@ -0,0 +1,132 @@
+---
+# yaml-language-server: $schema=https://skillgraph.dev/schemas/skill.v4.schema.json
+schema_version: 4
+name: image-optimization-pipeline-config
+description: "Use when authoring or reviewing the build-time image pipeline config — defining responsive srcset breakpoints, picking output formats (AVIF / WebP / JPEG fallback), tuning compression quality per format, and ensuring the pipeline never produces a lossy artifact for source PNGs with transparency. Activate this skill whenever the task touches `lib/images/pipeline.config.ts`, `scripts/build-images.ts`, or any code path that resizes or recompresses content images. Do NOT use for runtime image rendering choices (use a frontend skill) or for chasing a specific build failure (use debugging)."
+version: 0.1.0
+type: capability
+category: content
+domain: content/build/images
+scope: codebase
+owner: markdown-static-site-maintainer
+freshness: "2026-05-06"
+drift_check:
+  last_verified: "2026-05-06"
+eval_artifacts: none
+eval_state: unverified
+routing_eval: absent
+stability: experimental
+license: MIT
+compatibility:
+  runtimes:
+    - node
+  node: ">=20"
+  notes: "sharp ^0.33 or equivalent; output formats AVIF / WebP / JPEG."
+allowed-tools: Read Grep Bash
+keywords:
+  - image optimization
+  - image pipeline
+  - srcset breakpoints
+  - responsive images
+  - AVIF WebP fallback
+  - sharp config
+  - PNG transparency
+  - compression quality
+  - image build pipeline
+  - format negotiation
+  - image resize
+triggers:
+  - image-optimization-pipeline-config
+paths:
+  - "lib/images/pipeline.config.ts"
+  - "scripts/build-images.ts"
+  - "lib/images/format-negotiation.ts"
+  - "!**/*.test.ts"
+examples:
+  - "configure srcset breakpoints for hero images and thumbnails differently"
+  - "review the image pipeline — does it preserve transparency on PNG sources?"
+  - "add AVIF output to the pipeline alongside WebP and JPEG"
+  - "tune JPEG quality without breaking the AVIF pass"
+anti_examples:
+  - "pick the right <picture> element markup at runtime"
+  - "the build is OOM-killed on the 10MB hero image"
+  - "rewrite the pipeline in a different image library"
+relations:
+  boundary:
+    - skill: documentation
+      reason: "documentation writes prose about the image pipeline; this skill enforces the config contract in code"
+    - skill: debugging
+      reason: "debugging chases a specific build-time pipeline failure; this skill is the authoring/review primitive applied before failure"
+    - skill: refactor
+      reason: "refactor changes pipeline code shape; this skill enforces a specific config contract that must survive any refactor"
+  verify_with:
+    - testing-strategy
+grounding:
+  domain_object: "Build-time image pipeline configuration — the resize/compress/format-negotiation rules that turn source images in `content/` into the responsive variants under `public/images/`"
+  grounding_mode: repo_specific
+  truth_sources:
+    - lib/images/pipeline.config.ts
+    - scripts/build-images.ts
+    - lib/images/format-negotiation.ts
+  failure_modes:
+    - lossy_compression_on_png_with_transparency
+    - missing_avif_fallback_for_unsupported_clients
+    - srcset_breakpoints_dont_match_layout_breakpoints
+    - quality_setting_too_aggressive_visible_artifacts
+    - pipeline_doesnt_skip_already_optimized_outputs
+  evidence_priority: repo_code_first
+portability:
+  readiness: scripted
+  targets:
+    - skill-md
+workspace_tags:
+  - content
+  - static-site
+  - build-pipeline
+lifecycle:
+  stale_after_days: 90
+  review_cadence: quarterly
+---
+
+# Image Optimization Pipeline Config
+
+## Coverage
+
+- The format-negotiation table — which output formats the pipeline produces (AVIF + WebP + JPEG fallback is the canonical shape) and the priority order browsers should request
+- Srcset breakpoints — the widths the pipeline emits per image role (hero, content, thumbnail) and how those align with the site's CSS layout breakpoints
+- Per-format compression quality — JPEG at 80, WebP at 75, AVIF at 65 is a defensible default; anything more aggressive needs visual A/B verification
+- Transparency preservation — the pipeline must detect alpha channels in source PNGs and disable lossy formats (or fall back to lossless WebP / AVIF) for those specific images
+- Idempotency — the pipeline must not reprocess already-optimized outputs on every build (cache invalidation by source-file hash, not timestamp)
+- Source-format coverage — what the pipeline accepts as input (PNG, JPEG, WebP source) and what it explicitly rejects (HEIC, RAW, video formats)
+
+## Philosophy
+
+A build-time image pipeline is a config-defined contract between the source-of-truth images in `content/` and the bandwidth-optimized variants the browser receives. Bugs here are silent: a misconfigured srcset doesn't crash the build, it just sends a 4MB hero image to a phone. The discipline is to encode every choice — breakpoints, formats, quality, transparency rules — explicitly in the config, with a comment naming the constraint that drove each choice. Pipeline behavior should be derivable from the config without reading the build script.
+
+## Key Files
+
+| File | Purpose |
+|---|---|
+| `lib/images/pipeline.config.ts` | The canonical config: breakpoints, formats, quality settings, source-format allowlist |
+| `scripts/build-images.ts` | The build entrypoint that reads the config and walks `content/` — should be a thin runner with no embedded policy |
+| `lib/images/format-negotiation.ts` | The runtime helper that maps a request's `Accept:` header to the right pre-built variant |
+
+## Verification
+
+Before merging any change to the pipeline config:
+
+- [ ] Every output format has an explicit quality setting; no relying on library defaults
+- [ ] Srcset breakpoints match (or are a documented superset of) the site's CSS layout breakpoints
+- [ ] PNG sources with an alpha channel route to lossless or alpha-preserving lossy formats (WebP-lossless, AVIF) — never to JPEG
+- [ ] The pipeline skips already-optimized outputs by source-hash comparison; running the build twice in a row is a no-op on the second run
+- [ ] An end-to-end test under `__tests__/images/` exercises a fixture image of each accepted format and asserts the expected variant set is produced
+- [ ] The format-negotiation helper has a fallback path for clients that send no `Accept:` header (or one that lists no supported format)
+
+## Do NOT Use When
+
+| Use instead | When |
+|---|---|
+| (a frontend image-rendering skill) | The task is choosing the right `<picture>` / `<img srcset=...>` markup at the component level |
+| `debugging` | A specific image is failing to optimize and you need to reproduce from build logs |
+| `documentation` | The task is writing a contributor doc explaining how the pipeline works |
+| `refactor` | The task is restructuring the pipeline code without changing the config contract |