@skill-graph/cli 0.5.6

package/examples/projects/saas-stripe-postgres/skills/postgres-rls-pattern/SKILL.md

@@ -0,0 +1,163 @@
+---
+# yaml-language-server: $schema=https://skillgraph.dev/schemas/skill.v6.schema.json
+schema_version: 6
+name: postgres-rls-pattern
+description: "Use when writing or reviewing Postgres queries in a multi-tenant SaaS where every table row must be scoped to a single organization. Enforces the FORCE ROW LEVEL SECURITY + USING + WITH CHECK triple on every tenant-bound table, and wraps application queries in an `orgQuery(orgId)` helper that sets `app.current_org_id` before each statement. Do NOT use for cross-org system queries such as billing cron jobs or admin panels (those bypass RLS intentionally via the service role); use a service-role query wrapper instead."
+version: 0.1.0
+type: capability
+category: engineering
+domain: engineering/database
+scope: portable
+owner: saas-stripe-postgres-example
+freshness: "2026-05-18"
+drift_check:
+  last_verified: "2026-05-18"
+eval_artifacts: none
+eval_state: unverified
+routing_eval: absent
+stability: experimental
+license: MIT
+compatibility:
+  runtimes:
+    - node
+  node: ">=20"
+  notes: "Postgres >=14 with row-level security enabled; assumes pg or postgres.js driver."
+allowed-tools: Read Grep
+keywords:
+  - postgres row level security
+  - RLS multi-tenant
+  - orgQuery wrapper
+  - FORCE ROW LEVEL SECURITY
+  - SET app.current_org_id
+  - tenant data isolation
+  - cross-tenant data leak prevention
+  - multi-tenant postgres
+  - row security policy
+  - using with check policy
+triggers:
+  - postgres-rls-pattern
+paths:
+  - "lib/db.ts"
+  - "db/schema.sql"
+  - "db/migrations/*.sql"
+examples:
+  - "how do I prevent one tenant's data from appearing in another tenant's queries?"
+  - "write the RLS policy for the orders table in a multi-tenant SaaS"
+  - "set up the orgQuery helper so every query is automatically scoped to the current org"
+  - "add row level security to a new subscriptions table"
+anti_examples:
+  - "run a billing cron job that needs to read all orgs"
+  - "write a migration that backfills data across all organizations"
+  - "query the database without any tenant context for an admin dashboard"
+relations:
+  boundary:
+    - skill: migrate-orders-to-canonical-schema
+      reason: "migrate-orders-to-canonical-schema changes column layout; this skill defines the RLS policy that must be updated alongside any schema change on tenant-bound tables"
+    - skill: nextjs-server-action-validation
+      reason: "nextjs-server-action-validation validates the input layer; this skill governs the query layer — both are required but at different tiers"
+  depends_on: []
+  verify_with:
+    - migrate-orders-to-canonical-schema
+portability:
+  readiness: portable
+  targets:
+    - skill-md
+lifecycle:
+  stale_after_days: 180
+  review_cadence: quarterly
+---
+
+# Postgres RLS Pattern
+
+## Coverage
+
+- The three-part policy triple — `FORCE ROW LEVEL SECURITY`, `USING (org_id = current_setting('app.current_org_id')::uuid)`, and `WITH CHECK (org_id = current_setting('app.current_org_id')::uuid)` — and why omitting any one part leaves a gap
+- The `orgQuery(orgId)` application wrapper — a single function that opens a transaction, sets `app.current_org_id`, runs the caller's query, and commits; why setting the variable once at session start is unsafe under connection pooling
+- Service role bypass — legitimate cross-org operations (billing cron, admin panel, migration backfills) that must use a connection string that skips RLS, and why those code paths must be isolated from application code
+- Policy audit checklist — grepping for `query()` calls without a preceding `SET app.current_org_id` as a CI-safe audit gate
+- New-table checklist — steps to add RLS to a table that was created before RLS was enforced on the schema
+
+## Philosophy
+
+Row-level security on Postgres is the difference between "we checked org_id in the WHERE clause" and "the database rejects cross-org reads at the storage layer." Application-level checks are deleted by a single missing WHERE clause; RLS cannot be bypassed unless you use the service role explicitly. The cost is a session variable that must be set before every query and a discipline of never using the service role for application queries. Both costs are cheap relative to the consequence of a cross-tenant data leak.
+
+## Schema Pattern
+
+```sql
+-- 1. Enable and force RLS on every tenant-bound table
+ALTER TABLE orders ENABLE ROW LEVEL SECURITY;
+ALTER TABLE orders FORCE ROW LEVEL SECURITY;
+
+-- 2. SELECT policy — only rows where org_id matches the session variable
+CREATE POLICY orders_org_select ON orders
+  FOR SELECT
+  USING (org_id = current_setting('app.current_org_id', true)::uuid);
+
+-- 3. INSERT policy — only allow inserts that match the session variable
+CREATE POLICY orders_org_insert ON orders
+  FOR INSERT
+  WITH CHECK (org_id = current_setting('app.current_org_id', true)::uuid);
+
+-- 4. UPDATE policy — USING (read filter) AND WITH CHECK (write filter)
+CREATE POLICY orders_org_update ON orders
+  FOR UPDATE
+  USING (org_id = current_setting('app.current_org_id', true)::uuid)
+  WITH CHECK (org_id = current_setting('app.current_org_id', true)::uuid);
+
+-- 5. DELETE policy
+CREATE POLICY orders_org_delete ON orders
+  FOR DELETE
+  USING (org_id = current_setting('app.current_org_id', true)::uuid);
+```
+
+## Application Wrapper Pattern
+
+```typescript
+// lib/db.ts
+import postgres from "postgres";
+
+const sql = postgres(process.env.DATABASE_URL!);
+
+/** Tenant-scoped query: sets app.current_org_id for every statement. */
+export async function orgQuery<T>(
+  orgId: string,
+  fn: (sql: postgres.Sql) => Promise<T>
+): Promise<T> {
+  return sql.begin(async (tx) => {
+    await tx`SELECT set_config('app.current_org_id', ${orgId}, true)`;
+    return fn(tx);
+  });
+}
+
+/** System query: bypasses RLS. Use ONLY for cron jobs, migrations, and admin. */
+export async function systemQuery<T>(fn: (sql: postgres.Sql) => Promise<T>): Promise<T> {
+  return fn(sql);
+}
+```
+
+Usage in a Server Action:
+
+```typescript
+import { orgQuery } from "@/lib/db";
+
+export async function getOrders(orgId: string) {
+  return orgQuery(orgId, (tx) => tx`SELECT * FROM orders ORDER BY created_at DESC`);
+}
+```
+
+## Verification
+
+- [ ] Every tenant-bound table has `ENABLE ROW LEVEL SECURITY` AND `FORCE ROW LEVEL SECURITY`
+- [ ] Every DML operation (SELECT, INSERT, UPDATE, DELETE) has a corresponding policy on each table
+- [ ] `WITH CHECK` is present on INSERT and UPDATE policies (not just `USING`)
+- [ ] `orgQuery` sets the variable inside a transaction, not at session start
+- [ ] No application code calls `systemQuery` (grep for `systemQuery` in `apps/` and `lib/` — any hit is a finding)
+- [ ] Every new migration that adds a table includes the RLS policy triple in the same migration file
+
+## Do NOT Use When
+
+| Use instead | When |
+|---|---|
+| `systemQuery` wrapper | The query legitimately crosses org boundaries (billing cron, migration backfill, admin panel) |
+| `migrate-orders-to-canonical-schema` | The task is a schema migration that also needs to update RLS policies |
+| (a database skill without multi-tenancy scope) | The application is single-tenant and org_id isolation is not a requirement |

package/examples/projects/saas-stripe-postgres/skills/stripe-webhook-signature-verification/SKILL.md

@@ -0,0 +1,137 @@
+---
+# yaml-language-server: $schema=https://skillgraph.dev/schemas/skill.v6.schema.json
+schema_version: 6
+name: stripe-webhook-signature-verification
+description: "Use when validating incoming Stripe webhook requests in a Node.js or Next.js backend before processing any payment event. Verifies the `stripe-signature` header against `STRIPE_WEBHOOK_SECRET` using Stripe's HMAC-SHA256 scheme, and rejects replays older than 300 seconds. Do NOT use for general HTTP signature validation (use a generic crypto-signature skill), for processing the webhook payload after signature is confirmed (use payment-provider-router), or for Stripe API calls that are not webhook-driven."
+version: 0.1.0
+type: capability
+category: engineering
+domain: engineering/payments
+scope: portable
+owner: saas-stripe-postgres-example
+freshness: "2026-05-18"
+drift_check:
+  last_verified: "2026-05-18"
+  truth_source_hashes:
+    stripe-webhook-docs: "sha256:placeholder-record-with-node-scripts-skill-graph-drift-js"
+eval_artifacts: none
+eval_state: unverified
+routing_eval: absent
+stability: experimental
+license: MIT
+compatibility:
+  runtimes:
+    - node
+  node: ">=20"
+  notes: "Stripe SDK >=14; expects raw request body (not parsed JSON) for signature verification."
+allowed-tools: Read Grep
+keywords:
+  - stripe webhook signature verification
+  - stripe-signature header
+  - webhook hmac verification
+  - STRIPE_WEBHOOK_SECRET
+  - stripe constructEvent
+  - replay attack prevention
+  - webhook security
+  - payment webhook validation
+  - stripe webhook secret
+triggers:
+  - stripe-webhook-signature-verification
+paths:
+  - "app/api/webhooks/stripe/route.ts"
+  - "lib/stripe/webhook.ts"
+examples:
+  - "how do I verify that a webhook is really from Stripe?"
+  - "my webhook handler is returning 400 — is the signature verification failing?"
+  - "set up the Stripe webhook endpoint in a Next.js App Router API route"
+  - "reject replayed webhook events older than 5 minutes"
+anti_examples:
+  - "process the Stripe payment_intent.succeeded event payload"
+  - "call the Stripe API to create a payment intent"
+  - "validate a generic HTTP signature that is not from Stripe"
+relations:
+  boundary:
+    - skill: payment-provider-router
+      reason: "payment-provider-router decides which downstream handler receives the verified event; this skill verifies authenticity before any routing happens"
+    - skill: nextjs-server-action-validation
+      reason: "nextjs-server-action-validation validates user-submitted form input via Zod; this skill validates Stripe's HMAC signature — different trust boundary, different mechanism"
+  depends_on:
+    - skill: postgres-rls-pattern
+      reason: "idempotency key lookups that prevent double-processing run inside the RLS-scoped query layer; this skill activates before those lookups"
+  verify_with:
+    - nextjs-server-action-validation
+portability:
+  readiness: portable
+  targets:
+    - skill-md
+lifecycle:
+  stale_after_days: 90
+  review_cadence: quarterly
+---
+
+# Stripe Webhook Signature Verification
+
+## Coverage
+
+- The raw-body requirement — why `stripe.webhooks.constructEvent()` requires the unparsed `Buffer` from the request body, and how Next.js App Router routes expose it via `request.arrayBuffer()`
+- HMAC-SHA256 verification — how `constructEvent(rawBody, signature, secret)` reconstructs and compares the Stripe signature internally
+- Replay protection — the 300-second tolerance window Stripe checks against the `t=` timestamp embedded in the `stripe-signature` header; when to tighten it
+- Environment-specific secrets — `STRIPE_WEBHOOK_SECRET` for production vs `whsec_...` from the Stripe CLI `--forward-to` session in development; why they must never be swapped
+- Idempotency key pattern — recording the `event.id` in Postgres before processing so a retried delivery does not double-charge or double-fulfill
+
+## Philosophy
+
+A webhook that skips signature verification is an unauthenticated public endpoint that can trigger payment processing. The verification step is load-bearing security, not a convenience check. Stripe's SDK makes verification a single call, but two failure modes are common in practice: the request body gets parsed (by a body-parser middleware) before the raw bytes reach the verification call, which silently corrupts the HMAC comparison; and the wrong webhook secret is loaded from environment variables, producing a 400 that is hard to distinguish from a replay rejection. Both failures look the same to the caller — a rejected webhook — and both are invisible until a real event is dropped.
+
+## Verification
+
+1. **Confirm raw body access.** In Next.js App Router: `const rawBody = Buffer.from(await request.arrayBuffer())`. Do NOT pass `await request.json()` or `await request.text()` — both transform the bytes.
+
+2. **Retrieve and verify.**
+
+   ```typescript
+   import Stripe from "stripe";
+   const stripe = new Stripe(process.env.STRIPE_SECRET_KEY!);
+
+   const sig = request.headers.get("stripe-signature") ?? "";
+   let event: Stripe.Event;
+   try {
+     event = stripe.webhooks.constructEvent(
+       rawBody,
+       sig,
+       process.env.STRIPE_WEBHOOK_SECRET!
+     );
+   } catch (err) {
+     return Response.json({ error: "Signature verification failed" }, { status: 400 });
+   }
+   ```
+
+3. **Check idempotency before processing.**
+
+   ```sql
+   INSERT INTO webhook_events (event_id, processed_at)
+   VALUES ($1, now())
+   ON CONFLICT (event_id) DO NOTHING
+   RETURNING event_id;
+   ```
+
+   If the `RETURNING` clause returns no rows, the event was already processed — return 200 immediately without re-running side effects.
+
+4. **Route the verified event** to `payment-provider-router`.
+
+## Failure Mode Reference
+
+| Failure | Symptom | Fix |
+|---------|---------|-----|
+| Body parsed before verification | 400 on every real Stripe event | Use `arrayBuffer()`, not `json()` or `text()` |
+| Wrong webhook secret | 400 with "No signatures found matching the expected signature" | Verify `STRIPE_WEBHOOK_SECRET` matches the endpoint in the Stripe dashboard |
+| Replay attack | 400 with "Timestamp too old" | Legitimate if tolerance is tight; check `t=` value in the `stripe-signature` header |
+| Secret from wrong environment | Events verify in dev but fail in production | Use per-environment secrets; never share between environments |
+
+## Do NOT Use When
+
+| Use instead | When |
+|---|---|
+| `payment-provider-router` | You have a verified event and need to decide which handler processes it |
+| `nextjs-server-action-validation` | You are validating user-submitted form data, not a Stripe webhook |
+| (a generic HTTP signature skill) | You are verifying webhooks from a non-Stripe provider with a different signing scheme |

package/examples/protocol/skill-metadata-template.md

@@ -0,0 +1,301 @@
+---
+# yaml-language-server: $schema=https://skillgraph.dev/schemas/skill.v4.schema.json
+#
+# ============================================================================
+# SCAFFOLD — this file is a skill template, not a production skill.
+# ============================================================================
+#
+# Adopters COPY this file to `skills/<new-name>/SKILL.md` and then edit it to
+# author a new skill. Every `# TEMPLATE NOTE:` YAML comment and every
+# `> **TEMPLATE NOTE:**` body blockquote is authoring scaffolding that MUST be
+# stripped from the derived copy before shipping.
+#
+# Field values here are deliberate authoring-time defaults, not aspirational
+# targets. In particular `eval_artifacts: planned`, `eval_state: unverified`,
+# and `routing_eval: absent` (see comment on the routing_eval line below)
+# encode the correct starting state for a brand-new un-verified skill —
+# flipping them to `present` on this scaffold would make every derived skill
+# inherit a false attestation until the author noticed.
+#
+# Build automation treats this file specially: the sample manifest
+# generator ingests it only under `--include-template`, and the library-wide
+# harness counts it as the 9th "skill" only when the flag is set. It is NOT
+# routable in day-to-day skill dispatch — `scope: reference` keeps it out of
+# the normal routing pool.
+# ============================================================================
+schema_version: 4
+name: skill-metadata-template
+# TEMPLATE NOTE: Be pushy in your description — Claude tends to under-trigger
+# skills, so descriptions should read as commands ("Use when X", "Activate
+# this skill whenever Y") not as polite suggestions ("This skill provides Z").
+# State both WHAT the skill does AND WHEN to use it, and include an explicit
+# negative boundary ("Do NOT use for ..." with a pointer to the right
+# alternative skill). The 3-test quality gate for descriptions is:
+#   (1) names a real domain object (file path, function name, route),
+#   (2) has an explicit "Do NOT use for X (use Y)" exclusion clause,
+#   (3) names a concrete trigger (code pattern, file path, command).
+# Keep the description concise enough to route well, but do not treat runtime
+# wording guidelines as protocol limits.
+# for Anthropic's own guidance on pushy descriptions.
+description: "Use when creating a new SKILL.md, adapting an existing skill to a different archetype, or teaching an author the canonical frontmatter and body structure. Covers schema-conformant frontmatter, archetype-aware body layout, semantic-layer discipline (description vs Coverage), teaching-layer mechanics (TEMPLATE NOTE blockquotes and YAML comments), and the authoring gate. Do NOT use when modifying an already-written skill (edit that skill directly) or when writing general technical documentation (use the documentation skill)."
+version: 1.0.0
+type: capability
+category: knowledge
+# TEMPLATE NOTE: domain is the OPTIONAL hierarchical domain path (slash-
+# delimited, lowercase kebab-case segments). Use it only when the skill library
+# is large enough that a tree structure helps readers find related skills.
+# Remove this line entirely when the flat `category` above is sufficient.
+domain: skill-system/authoring
+scope: reference
+owner: skill-graph-maintainer
+freshness: "2026-04-17"
+# TEMPLATE NOTE: drift_check is an object. `last_verified` is required.
+# `truth_source_hashes` is optional — record it with `node scripts/skill-graph-drift.js
+# --record --apply <skill-dir>`.
+drift_check:
+  last_verified: "2026-04-17"
+# TEMPLATE NOTE: eval_artifacts, eval_state, and routing_eval are the three
+# orthogonal eval-health axes introduced in schema_version 2. Set eval_artifacts
+# to `planned` only as a temporary state — move to `present` once the artifact
+# ships. Set eval_state to `unverified` when no run has been recorded yet.
+#
+# routing_eval: `present` is LINT-ENFORCED since [Unreleased]. Setting `present`
+# requires (1) populated `examples` + `anti_examples` below, AND (2) a passing
+# run of `node scripts/skill-graph-routing-eval.js --skill <name>`. Lint check
+# 12 surfaces each failing prompt. Default to `absent` when authoring; flip
+# to `present` only after the harness agrees. See docs/field-reference.md §
+# routing_eval for the full enforcement contract.
+#
+# SCAFFOLD NOTE — on this specific file (`examples/skill-metadata-template.md`),
+# routing_eval MUST stay `absent` even though the harness happens to report
+# every case passing. The scaffold's job is to model the correct authoring-
+# time default for a brand-new un-verified skill. If this line were flipped
+# to `present`, every skill copy-pasted from the scaffold would inherit a
+# false attestation until the author noticed and downgraded. In your
+# derived copy, leave this line `absent` at first commit; flip it to
+# `present` only after `node scripts/skill-graph-routing-eval.js --skill
+# <your-skill-name>` exits 0 on YOUR skill's own examples + anti_examples.
+eval_artifacts: planned
+eval_state: unverified
+routing_eval: absent
+# TEMPLATE NOTE: Optional. Populate eval_last_run only after the skill has a
+# real eval receipt (scorecard, grader history, CI run). Leave it absent for a
+# brand-new skill with eval_state: unverified.
+# eval_last_run:
+#   at: "2026-05-12T09:30:00Z"
+#   status: pass
+#   runner: "node scripts/skill-audit.js --graded"
+#   receipt: "examples/audits/<skill>/scorecard.md"
+# TEMPLATE NOTE: stability values are `experimental` / `stable` / `frozen` /
+# `deprecated`. When you move a skill to `deprecated`, the schema's `allOf`
+# rule REQUIRES you to also add `superseded_by: <replacement-skill-name>` —
+# without it the skill fails validation. A deprecated + superseded skill looks
+# like:
+#
+#   stability: deprecated
+#   superseded_by: new-skill-name
+#
+# The replacement must be a real skill in the same library. Omit `superseded_by`
+# for any stability other than `deprecated`. See `docs/field-reference.md §
+# superseded_by` for the full rules and the schema's `allOf` enforcement.
+stability: stable
+license: MIT
+# TEMPLATE NOTE: compatibility is an object. Prefer structured fields
+# (`runtimes`, `node`) over free-text `notes`.
+compatibility:
+  notes: "Markdown, YAML, JSON Schema"
+allowed-tools: Read Grep
+# TEMPLATE NOTE: keywords are the pushy activation surface for authoring tasks.
+# Keep terms that a human would type when starting a new skill.
+keywords:
+  - how to write a SKILL.md file
+  - SKILL.md frontmatter YAML
+  - Skill Metadata Protocol v4
+  - Skill Graph schema fields
+  - skill archetype capability vs workflow
+  - skill description routing contract
+  - drift_check eval_artifacts routing_eval
+  - new skill scaffold template
+  - SKILL.md authoring gate
+# TEMPLATE NOTE: triggers is present because this skill is routable by explicit label.
+# Remove this block if your skill activates only by keyword or path matching.
+triggers:
+  - skill-metadata-template
+# TEMPLATE NOTE: paths is present because this template is the entry point whenever
+# examples/skill-metadata-template.md itself is touched. the protocol supports gitignore-style negation —
+# e.g. `- "!skills/experimental/**"` excludes a subdirectory from an otherwise broad
+# glob. Remove this block if your skill is purely conceptual and has no file surface.
+#
+# Previous versions of this block also listed `skills/**/SKILL.md` but that glob is
+# owned by `graph-audit` (the audit tooling that verifies every SKILL.md against the
+# schema). Two skills claiming the same glob produces router ambiguity — the scope
+# tiebreaker (`codebase` > `reference`) picks graph-audit anyway, and reference-scope
+# skills are looked-up rather than path-routed. Lesson: each path glob should map to
+# ONE canonical skill; `scripts/skill-overlap.js` surfaces duplicates as warnings.
+paths:
+  - examples/skill-metadata-template.md
+# TEMPLATE NOTE: examples is new in v0.5.0. 2–5 realistic user prompts the skill
+# SHOULD activate for. Improves retrieval recall over keywords alone. Write in
+# the user's voice, not imperative abstract form. See docs/field-reference.md §
+# examples for full guidance. Omit this block for purely label-routed skills.
+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?"
+# TEMPLATE NOTE: anti_examples names near-miss prompts that should route ELSEWHERE.
+# Pair with relations.boundary to tell the router which skill owns the confusable
+# territory. Leave this block absent until you have seen the router misfire —
+# speculative anti_examples rarely match reality. See docs/field-reference.md §
+# anti_examples.
+anti_examples:
+  - "refactor this skill to be more concise"           # → refactor, not authoring
+  - "my skill's routing isn't activating — why?"       # → skill-router, not template
+# TEMPLATE NOTE: workspace_tags replaces v3 project_tags. Omit it for ambient / cross-project
+# skills (the common case). Add literal project handles or semantic tags when
+# the skill is relevant to a subset of projects in a multi-project workspace.
+# See docs/field-decision-guide.md § 4 for the full decision tree.
+#
+# Example — this template is useful across every skill-authoring project, but
+# the semantic tag scopes it to the Skill Graph authoring workflow rather than
+# arbitrary project docs. A workspace config at `.skill-graph/config.json` can
+# map your literal project handles to tag sets that include `skill-authoring`,
+# so one tag reaches many projects.
+workspace_tags:
+  - skill-authoring
+relations:
+  # TEMPLATE NOTE: boundary items may be bare skill names OR `{skill, reason}`
+  # objects (v3). Reasons are strongly recommended — they make the boundary
+  # self-documenting. Adjacency has been removed here because `documentation`
+  # is already declared as `verify_with` — adjacent ("often used together")
+  # would be redundant and asymmetric.
+  boundary:
+    - skill: refactor
+      reason: "refactor is behavior-preserving code modification, not skill authoring"
+    - skill: skill-router
+      reason: "skill-router dispatches between existing skills at request time; this template creates a NEW skill"
+    - skill: graph-audit
+      reason: "graph-audit verifies the authored metadata of an existing skill; this template is the authoring-time guide"
+  verify_with:
+    - documentation
+# TEMPLATE NOTE: grounding is REQUIRED for grounded skills that make concrete
+# repo claims. Remove this entire block if your skill has grounding_mode: universal
+# and does not anchor to truth sources in the repo.
+grounding:
+  domain_object: Skill authoring for the Skill Metadata Protocol frontmatter
+  grounding_mode: repo_specific
+  truth_sources:
+    - path: docs/skill-metadata-protocol.md
+      anchor: the-40-authored-fields-grouped-by-purpose
+      note: "Protocol anatomy and field requiredness"
+    - path: schemas/skill.schema.json
+      line_range:
+        start: 480
+        end: 590
+      note: "Grounding schema shape"
+    - path: SKILL_AUDIT_CHECKLIST.md
+      anchor: canonical-checklist
+      note: "Audit checklist this template supports"
+  failure_modes:
+    - placeholder_sludge
+    - cargo_cult_meta_sections
+    - description_coverage_collapse
+    - authoring_gate_skipped
+  evidence_priority: repo_code_first
+# TEMPLATE NOTE: portability declares which external agent runtimes this skill is
+# known to work on. `readiness` is the operational rating: `declared` (claim only),
+# `scripted` (export tooling exists), or `verified` (proven with a receipt). `targets`
+# is the list of destination runtimes. Today the supported portable target is `skill-md`
+# (see `schemas/skill.schema.json`). Other runtimes (cursor, windsurf, copilot, agents-md)
+# were removed from the enum in 0.3.0 pending working transforms — re-add via RFC if
+# adoption pressure appears. Remove this block if the skill is internal-only.
+portability:
+  readiness: scripted
+  targets:
+    - skill-md
+# TEMPLATE NOTE: lifecycle declares maintenance policy for the drift sentinel.
+# `stale_after_days` flags the skill as STALE when more than N days have passed
+# since `drift_check.last_verified`. Integration skills (third-party APIs) want
+# shorter values; pure-concept skills want longer. Omit if staleness is not
+# meaningful for your skill.
+lifecycle:
+  stale_after_days: 180
+  review_cadence: quarterly
+# TEMPLATE NOTE: runtime_telemetry is optional. It points at a JSONL feed of
+# real-world success/failure receipts so consumers can corroborate or override
+# `eval_state`. Omit the entire block when no feedback pipeline exists — the
+# skill is still graded on authored `eval_state` and `eval_artifacts`.
+# Each run receipt should carry at minimum `{ timestamp, skill, outcome }`.
+# `metrics.sample_size` and `metrics.success_rate` are the aggregate summary;
+# consumers may compute their own from the raw feed.
+runtime_telemetry:
+  feedback_source: .skill-graph/telemetry/skill-metadata-template.jsonl
+  last_updated: "2026-04-17"
+  metrics:
+    sample_size: 0
+    success_rate: 0
+---
+
+# Skill Template — Scaffold
+
+> **SCAFFOLD — NOT A PRODUCTION SKILL.** This file is the starting point authors copy when creating a new skill. It lives at `examples/skill-metadata-template.md` deliberately; production skills live at `skills/<name>/SKILL.md`. The authoring flow is: copy → rename → adapt → strip teaching annotations → verify → commit. Until you have completed those steps, the file you are editing is a *scaffold*, not a skill.
+
+> **TEMPLATE NOTE — HOW TO READ THIS FILE:** This file is a real, valid, schema-conformant Skill Metadata Protocol skill whose *subject* is skill authoring itself. Read it as a finished specimen of the contract, then adapt it by (1) renaming the identity, (2) rewriting `description`, `## Coverage`, `## Philosophy`, and `## Key Files` for your subject, (3) rewriting `## Verification` to be your skill's self-check, (4) removing any section or field that does not apply to your archetype, and (5) stripping the `> **TEMPLATE NOTE:**` blockquotes and `# TEMPLATE NOTE:` YAML comments — they are authoring scaffolding, never skill content. Never ship placeholder sludge (`your-skill-name`, `path/to/file`, `todo`). If a section does not apply, remove it — do not keep it and fill it with fake content.
+
+> **TEMPLATE NOTE — CONDITIONAL FIELDS:** `extends` is valid only when `type: overlay`. `routing_bundles` only applies when routing-group ownership is part of the skill contract. `triggers` and `paths` are shown because this template is both label-routable and file-activated; most skills need only one. `grounding` is REQUIRED for `scope: codebase` skills; remove the block entirely for `scope: portable` or `scope: reference`. `workspace_tags` is optional — omit for ambient / cross-project skills. `lifecycle` is optional — omit when staleness is not meaningful. `runtime_telemetry` is optional — omit when no feedback pipeline exists. Generated manifest health fields belong in `skills.manifest.json`, not in the authored `SKILL.md`.
+
+## Coverage
+
+- Frontmatter identity: `name`, `description`, `version`, `type`, `category`, `scope`, `owner`, and the governance fields required by every Skill Metadata Protocol skill
+- Semantic layer discipline: how `description:` (routing contract, ≤ 3 sentences) differs from `## Coverage` (scope map, bulleted topic list) and why each must stay in its own layer
+- Teaching-layer delivery: how to use `> **TEMPLATE NOTE:**` blockquotes and `# TEMPLATE NOTE:` YAML comments to teach authors without cargo-culting meta sections into every new skill
+- Archetype-driven body structure: which `## H2` sections each of the four archetypes (`capability`, `workflow`, `router`, `overlay`) must contain
+- Grounding via `grounding`: when a skill should declare truth sources and failure modes, and when it should stay `grounding_mode: universal`
+- drift evidence: when to record `drift_check.truth_source_hashes` and how the drift sentinel consumes them
+- v4 workspace tagging: when to add `workspace_tags`, when to leave a skill ambient, and how workspace semantic-tag mapping composes
+- Adapter workflow: how to strip a template down, how to detect and remove cargo-culted meta, and how to verify a new skill against `schemas/skill.schema.json` before committing
+
+## Philosophy
+
+A template 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 scaffolding. The teaching layer — meta-commentary about how to read and adapt the template — 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 when adapting the file.
+
+## Key Files
+
+| File | Purpose |
+|---|---|
+| `docs/skill-metadata-protocol.md` | Authoritative field semantics: required vs optional, conditional requiredness, relationship to the plain `SKILL.md` format, archetype section map |
+| `schemas/skill.schema.json` | Enforceable JSON Schema for the frontmatter protocol |
+| `SKILL_AUDIT_CHECKLIST.md` | The audit checklist every new skill should pass before commit |
+
+## Verification
+
+Use this checklist as the authoring gate before committing a skill adapted from this template. 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 skill's 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` has been recorded when truth sources exist
+- [ ] `compatibility` is an object (not a free-text string) when present
+- [ ] `eval_artifacts` matches actual artifact presence (if `present`, an eval file exists under `examples/evals/` or alongside the skill); `eval_state` reflects whether a real passing run has been recorded; `routing_eval` reflects whether trigger/routing coverage is explicitly checked
+- [ ] All `relations` entries point to skills that exist in the target repo; `boundary` entries with unclear rationale use the `{skill, reason}` form
+- [ ] `workspace_tags` is present when the skill is project-specific OR absent when the skill is ambient — not left at a stale value
+- [ ] No placeholder sludge (`your-skill-name`, `path/to/file`, `todo`) remains
+- [ ] No `> **TEMPLATE NOTE:**` blockquotes or `# TEMPLATE NOTE:` YAML comments remain in the adapted skill
+- [ ] The adapted skill validates against `schemas/skill.schema.json` as a real skill
+
+## Do NOT Use When
+
+| Instead of this template | Use | Why |
+|---|---|---|
+| `skill-metadata-template` | the target skill directly | Editing an existing skill is refactor-in-place, not authoring from a template |
+| `skill-metadata-template` | `documentation` | General technical writing is not skill authoring; use `documentation` for docs, guides, and specs |
+| `skill-metadata-template` | `docs/skill-metadata-protocol.md` | When you need the full field reference, read the contract document directly |
+
+## References
+
+- `docs/skill-metadata-protocol.md § Relationship to the SKILL.md format` - how Skill Metadata Protocol extends the base format
+- `docs/skill-metadata-protocol.md § Example Template Rule` — the no-placeholder-sludge rule this template enforces
+- `docs/skill-metadata-protocol.md § Archetype section map` — required H2 sections per archetype
+- `docs/manifest-field-mapping.md § Migration Note — v2 → v3` — the field-name cleanup the v4 bump introduced
+- `SKILL_AUDIT_CHECKLIST.md` — the checklist this template's Verification section is derived from