From 4eb6f3af03b3c16b8de8149eb905ee1e47139ed5 Mon Sep 17 00:00:00 2001 From: Kyle Mathews Date: Tue, 3 Mar 2026 09:38:01 -0700 Subject: [PATCH] feat: update domain-discovery and tree-generator meta skills from upstream Syncs with upstream TanStack/playbooks while preserving local customizations (skills/_artifacts paths, scaffold flow, meta-skill feedback, custom skills root). Co-Authored-By: Claude Opus 4.6 --- .../playbooks/meta/domain-discovery/SKILL.md | 183 +++++++++--------- .../playbooks/meta/tree-generator/SKILL.md | 157 +++++++-------- 2 files changed, 157 insertions(+), 183 deletions(-) diff --git a/packages/playbooks/meta/domain-discovery/SKILL.md b/packages/playbooks/meta/domain-discovery/SKILL.md index b53b3918..b3016401 100644 --- a/packages/playbooks/meta/domain-discovery/SKILL.md +++ b/packages/playbooks/meta/domain-discovery/SKILL.md @@ -9,13 +9,13 @@ description: > Produces a domain_map.yaml and skill_spec.md that feed directly into the skill-tree-generator skill. metadata: - version: '3.0' + version: "3.0" category: meta-tooling output_artifacts: - skills/_artifacts/domain_map.yaml - skills/_artifacts/skill_spec.md skills: - - tree-generator + - skill-tree-generator --- # Domain Discovery & Maintainer Interview @@ -60,7 +60,6 @@ reading exhaustively yet. ### 1b — Note initial impressions Log (but do not group yet): - - What the library does in one sentence - The core abstractions a developer interacts with - Which frameworks it supports @@ -154,7 +153,6 @@ Read in this order. Each step builds context for the next. Produce a flat concept inventory. One item per line. No grouping yet. Log every: - - Named concept, abstraction, or lifecycle stage - Public export: function, hook, class, type, constant - Configuration key, its type, and its default value @@ -185,7 +183,6 @@ These become high-priority failure modes. ### 3a — Group concepts into domains Move concept inventory items into groups. Two items belong together when: - - A developer reasons about them together when solving a problem - Solving one correctly requires understanding how the other works - They share a lifecycle, configuration scope, or architectural tradeoff @@ -194,7 +191,6 @@ Move concept inventory items into groups. Two items belong together when: Target 4–7 domains. These are conceptual groupings, not the final skills. Do not create a group for: - - A single hook, function, or class - A single doc or reference page - "Miscellaneous", "Advanced", or "Other" @@ -209,7 +205,6 @@ Phase 2. Each skill should match a specific developer moment while carrying the conceptual depth of its parent domain(s). A skill is well-shaped when: - - A developer would ask for it by name ("help me set up sync") - It covers enough for the agent to complete the task end-to-end - It doesn't require loading 3 other skills to be useful @@ -220,7 +215,6 @@ span domains (a "go-live" checklist touches security, performance, and configuration). Both are fine. Also consider: - - **Lifecycle/journey skills** — if the library's docs include a quickstart guide, go-to-production checklist, or migration path, suggest these as standalone skills. Don't force them if the docs @@ -257,13 +251,13 @@ For each skill, extract failure modes that pass all three tests: **Where to find them:** -| Source | What to extract | -| -------------------- | ------------------------------------------------------------------ | -| Migration guides | Every breaking change → old pattern is the wrong code | -| Doc callouts | Any "note", "warning", "avoid" with surrounding context | -| Source assertions | `throw` and `invariant()` messages describe the failure | -| Default values | Undocumented or surprising defaults that cause wrong behavior | -| Type precision | Source type more restrictive than docs imply | +| Source | What to extract | +|--------|----------------| +| Migration guides | Every breaking change → old pattern is the wrong code | +| Doc callouts | Any "note", "warning", "avoid" with surrounding context | +| Source assertions | `throw` and `invariant()` messages describe the failure | +| Default values | Undocumented or surprising defaults that cause wrong behavior | +| Type precision | Source type more restrictive than docs imply | | Environment branches | `typeof window`, SSR flags, `NODE_ENV` — behavior differs silently | Target 3 failure modes per skill minimum. Complex skills target 5–6. @@ -304,7 +298,6 @@ For each skill, explicitly list what you could NOT determine from docs and source alone. These become interview questions in Phase 4. Common gaps: - - "Docs describe X but don't explain when you'd choose X over Y" - "Migration guide mentions this changed but doesn't say what the old behavior was" @@ -476,60 +469,60 @@ below with their chosen directory. # Status: [draft | reviewed] library: - name: '[package-name]' - version: '[version]' - repository: '[repo URL]' - description: '[one line]' - primary_framework: '[React | Vue | Svelte | framework-agnostic]' + name: "[package-name]" + version: "[version]" + repository: "[repo URL]" + description: "[one line]" + primary_framework: "[React | Vue | Svelte | framework-agnostic]" domains: - - name: '[work-oriented domain name]' - slug: '[kebab-case]' - description: '[conceptual grouping — what a developer is reasoning about]' + - name: "[work-oriented domain name]" + slug: "[kebab-case]" + description: "[conceptual grouping — what a developer is reasoning about]" skills: - - name: '[task-focused skill name]' - slug: '[kebab-case]' - domain: '[parent domain slug]' - description: '[what a developer is doing — matches a specific task/moment]' - type: '[core | framework | lifecycle | composition]' + - name: "[task-focused skill name]" + slug: "[kebab-case]" + domain: "[parent domain slug]" + description: "[what a developer is doing — matches a specific task/moment]" + type: "[core | framework | lifecycle | composition]" covers: - - '[API/hook/concept 1]' - - '[API/hook/concept 2]' + - "[API/hook/concept 1]" + - "[API/hook/concept 2]" tasks: - - '[example task 1]' - - '[example task 2]' - - '[example task 3]' - subsystems: # omit if skill has no independent subsystems - - name: '[adapter/backend name]' - package: '[npm package if separate]' - config_surface: '[brief description of unique config]' - reference_candidates: # omit if no dense API surfaces - - topic: '[e.g. query operators, schema validation]' - reason: '[e.g. >10 distinct operators with signatures]' + - "[example task 1]" + - "[example task 2]" + - "[example task 3]" + subsystems: # omit if skill has no independent subsystems + - name: "[adapter/backend name]" + package: "[npm package if separate]" + config_surface: "[brief description of unique config]" + reference_candidates: # omit if no dense API surfaces + - topic: "[e.g. query operators, schema validation]" + reason: "[e.g. >10 distinct operators with signatures]" failure_modes: - - mistake: '[5-10 word phrase]' - mechanism: '[one sentence]' - source: '[doc page, source file, issue link, or maintainer interview]' - priority: '[CRITICAL | HIGH | MEDIUM]' - status: '[active | fixed-but-legacy-risk | removed]' + - mistake: "[5-10 word phrase]" + mechanism: "[one sentence]" + source: "[doc page, source file, issue link, or maintainer interview]" + priority: "[CRITICAL | HIGH | MEDIUM]" + status: "[active | fixed-but-legacy-risk | removed]" version_context: "[e.g. 'Fixed in v5.2 but agents trained on older code still generate this']" - skills: ['[this-skill-slug]'] # list all skills this belongs to; omit if single-skill + skills: ["[this-skill-slug]"] # list all skills this belongs to; omit if single-skill compositions: - - library: '[other library name]' - skill: '[composition skill name if applicable]' + - library: "[other library name]" + skill: "[composition skill name if applicable]" tensions: - - name: '[short phrase describing the pull]' - skills: ['[skill-slug-a]', '[skill-slug-b]'] - description: '[what conflicts — one sentence]' - implication: '[what an agent gets wrong when it only considers one side]' + - name: "[short phrase describing the pull]" + skills: ["[skill-slug-a]", "[skill-slug-b]"] + description: "[what conflicts — one sentence]" + implication: "[what an agent gets wrong when it only considers one side]" gaps: - - skill: '[skill slug]' - question: '[what still needs input]' - context: '[why this matters]' - status: '[open | resolved]' + - skill: "[skill slug]" + question: "[what still needs input]" + context: "[why this matters]" + status: "[open | resolved]" ``` ### 2. skills/\_artifacts/skill_spec.md @@ -544,43 +537,43 @@ not promotional.] ## Domains -| Domain | Description | Skills | -| ------ | --------------------- | ----------------------- | +| Domain | Description | Skills | +|--------|-------------|--------| | [name] | [conceptual grouping] | [skill-1, skill-2, ...] | ## Skill Inventory -| Skill | Type | Domain | What it covers | Failure modes | -| ------ | -------------------------------------- | -------- | -------------- | ------------- | -| [name] | [core/framework/lifecycle/composition] | [domain] | [list] | [count] | +| Skill | Type | Domain | What it covers | Failure modes | +|-------|------|--------|----------------|---------------| +| [name] | [core/framework/lifecycle/composition] | [domain] | [list] | [count] | ## Failure Mode Inventory ### [Skill name] ([count] failure modes) -| # | Mistake | Priority | Source | Cross-skill? | -| --- | -------- | -------- | ---------------------- | ------------------------ | -| 1 | [phrase] | CRITICAL | [doc/source/interview] | [other skill slugs or —] | +| # | Mistake | Priority | Source | Cross-skill? | +|---|---------|----------|--------|--------------| +| 1 | [phrase] | CRITICAL | [doc/source/interview] | [other skill slugs or —] | [Repeat table for each skill.] ## Tensions -| Tension | Skills | Agent implication | -| -------------- | ------------------- | ----------------------- | +| Tension | Skills | Agent implication | +|---------|--------|-------------------| | [short phrase] | [slug-a] ↔ [slug-b] | [what agents get wrong] | ## Subsystems & Reference Candidates -| Skill | Subsystems | Reference candidates | -| ------ | ------------------------------ | -------------------------- | +| Skill | Subsystems | Reference candidates | +|-------|------------|---------------------| | [slug] | [adapter1, adapter2, ...] or — | [topic needing depth] or — | ## Remaining Gaps -| Skill | Question | Status | -| ------ | ------------------------ | ------ | -| [slug] | [what still needs input] | open | +| Skill | Question | Status | +|-------|----------|--------| +| [slug] | [what still needs input] | open | [Omit this section if all gaps were resolved in the interview.] @@ -595,35 +588,35 @@ not promotional.] ## Composition Opportunities -| Library | Integration points | Composition skill needed? | -| ------- | ------------------ | ----------------------------- | -| [name] | [what interacts] | [yes/no — if yes, skill name] | +| Library | Integration points | Composition skill needed? | +|---------|-------------------|--------------------------| +| [name] | [what interacts] | [yes/no — if yes, skill name] | ``` --- ## Constraints -| Check | Rule | -| ------------------------------------- | -------------------------------------------------------------------------- | -| Quick scan before interview | Never interview without at least reading README and package structure | -| High-level interview before deep read | The maintainer's task map informs what you read deeply | -| Batch only confirmations | Yes/no questions may batch 2–3; open-ended questions get their own message | -| Questions reference findings | No generic questions — cite what you found | -| Skills are task-focused | Each skill matches a developer moment, not a conceptual area | -| 3+ failure modes per skill | Complex skills target 5–6 | -| Every failure mode sourced | Doc page, source file, issue link, or maintainer interview | -| Gaps are explicit | Unknown areas flagged, not guessed | -| No marketing prose | Library description is factual, not promotional | -| domain_map.yaml is valid YAML | Parseable by any YAML parser | -| Draft before detail interview | Present draft for review before Phase 4 | -| Agent-specific failures probed | Always ask AI-agent-specific questions in Phase 4c | -| Compositions discovered from code | Scan peer deps and examples before asking composition questions | -| Cross-skill failure modes tagged | Failure modes spanning skills list all relevant slugs | -| Tensions identified | 2–4 cross-skill tensions; if none found, revisit skill boundaries | -| Subsystems flagged | Skills with 3+ adapters/backends list them as subsystems | -| Dense surfaces flagged | Topics with >10 patterns noted as reference_candidates | -| Lifecycle skills considered | Suggest journey skills when docs have the material | +| Check | Rule | +|-------|------| +| Quick scan before interview | Never interview without at least reading README and package structure | +| High-level interview before deep read | The maintainer's task map informs what you read deeply | +| Batch only confirmations | Yes/no questions may batch 2–3; open-ended questions get their own message | +| Questions reference findings | No generic questions — cite what you found | +| Skills are task-focused | Each skill matches a developer moment, not a conceptual area | +| 3+ failure modes per skill | Complex skills target 5–6 | +| Every failure mode sourced | Doc page, source file, issue link, or maintainer interview | +| Gaps are explicit | Unknown areas flagged, not guessed | +| No marketing prose | Library description is factual, not promotional | +| domain_map.yaml is valid YAML | Parseable by any YAML parser | +| Draft before detail interview | Present draft for review before Phase 4 | +| Agent-specific failures probed | Always ask AI-agent-specific questions in Phase 4c | +| Compositions discovered from code | Scan peer deps and examples before asking composition questions | +| Cross-skill failure modes tagged | Failure modes spanning skills list all relevant slugs | +| Tensions identified | 2–4 cross-skill tensions; if none found, revisit skill boundaries | +| Subsystems flagged | Skills with 3+ adapters/backends list them as subsystems | +| Dense surfaces flagged | Topics with >10 patterns noted as reference_candidates | +| Lifecycle skills considered | Suggest journey skills when docs have the material | --- diff --git a/packages/playbooks/meta/tree-generator/SKILL.md b/packages/playbooks/meta/tree-generator/SKILL.md index d7ed5a6d..bcc7337e 100644 --- a/packages/playbooks/meta/tree-generator/SKILL.md +++ b/packages/playbooks/meta/tree-generator/SKILL.md @@ -9,7 +9,7 @@ description: > skill accuracy. Takes domain_map.yaml and skill_spec.md from skill-domain-discovery as primary inputs. metadata: - version: '3.0' + version: "3.0" category: meta-tooling input_artifacts: - skills/_artifacts/domain_map.yaml @@ -31,14 +31,14 @@ be portable, concise, and grounded in actual library behavior. Every skill has a `type` field in its frontmatter. Valid types: -| Type | Purpose | Example | -| ------------- | ---------------------------------------------------------- | ------------------------- | -| `core` | Framework-agnostic concepts, configuration, patterns | `db-core` | -| `sub-skill` | A focused sub-topic within a core or framework skill | `db-core/live-queries` | -| `framework` | Framework-specific bindings, hooks, components | `react-db` | -| `lifecycle` | Cross-cutting developer journey (getting started, go-live) | `electric-quickstart` | -| `composition` | Integration between two or more libraries | `electric-drizzle` | -| `security` | Audit checklist or security validation | `electric-security-check` | +| Type | Purpose | Example | +|------|---------|---------| +| `core` | Framework-agnostic concepts, configuration, patterns | `db-core` | +| `sub-skill` | A focused sub-topic within a core or framework skill | `db-core/live-queries` | +| `framework` | Framework-specific bindings, hooks, components | `react-db` | +| `lifecycle` | Cross-cutting developer journey (getting started, go-live) | `electric-quickstart` | +| `composition` | Integration between two or more libraries | `electric-drizzle` | +| `security` | Audit checklist or security validation | `electric-security-check` | Agents discover skills via `tanstack playbook list` and read them directly from `node_modules`. Framework skills declare a `requires` dependency on @@ -91,31 +91,31 @@ Use this format: ```yaml # skills/_artifacts/skill_tree.yaml library: - name: '[package-name]' - version: '[version]' - repository: '[repo URL]' - description: '[one line]' + name: "[package-name]" + version: "[version]" + repository: "[repo URL]" + description: "[one line]" generated_from: - domain_map: 'skills/_artifacts/domain_map.yaml' - skill_spec: 'skills/_artifacts/skill_spec.md' -generated_at: '[ISO date]' + domain_map: "skills/_artifacts/domain_map.yaml" + skill_spec: "skills/_artifacts/skill_spec.md" +generated_at: "[ISO date]" skills: - - name: '[task-focused skill name]' - slug: '[kebab-case]' - type: 'core | sub-skill | framework | lifecycle | composition | security' - domain: '[domain slug]' - path: 'skills/[path]/SKILL.md' - description: '[1–2 sentence agent-facing routing key]' + - name: "[task-focused skill name]" + slug: "[kebab-case]" + type: "core | sub-skill | framework | lifecycle | composition | security" + domain: "[domain slug]" + path: "skills/[path]/SKILL.md" + description: "[1–2 sentence agent-facing routing key]" requires: - - '[other skill slugs]' # omit if none + - "[other skill slugs]" # omit if none sources: - - '[Owner/repo]:docs/[path].md' - - '[Owner/repo]:src/[path].ts' + - "[Owner/repo]:docs/[path].md" + - "[Owner/repo]:src/[path].ts" subsystems: - - '[adapter/backend name]' # omit if none + - "[adapter/backend name]" # omit if none references: - - 'references/[file].md' # omit if none + - "references/[file].md" # omit if none ``` ### Step 1 — Plan the file tree @@ -126,17 +126,17 @@ file. The `type` field on each skill (`core`, `framework`, `lifecycle`, **Core vs framework decision:** -| Content | Goes in... | -| ---------------------------------------------- | ---------- | -| Mental models, concepts, lifecycle | Core | -| Configuration options and their effects | Core | -| Type system, generics, inference | Core | -| Common mistakes that apply to all frameworks | Core | -| Hooks (`useX`, `createX`) | Framework | -| Components (``, ``) | Framework | -| Provider setup and wiring | Framework | -| SSR/hydration patterns specific to a framework | Framework | -| Framework-specific gotchas | Framework | +| Content | Goes in... | +|---------|-----------| +| Mental models, concepts, lifecycle | Core | +| Configuration options and their effects | Core | +| Type system, generics, inference | Core | +| Common mistakes that apply to all frameworks | Core | +| Hooks (`useX`, `createX`) | Framework | +| Components (``, ``) | Framework | +| Provider setup and wiring | Framework | +| SSR/hydration patterns specific to a framework | Framework | +| Framework-specific gotchas | Framework | If a library has no framework adapters (e.g. Store, DB), produce only core skills. @@ -160,13 +160,11 @@ setup, and gotchas. The SKILL.md covers what's common; each Choose the structure that matches how the domain map's skills are shaped. Use **nested** (`[lib]-core/[domain]/SKILL.md`) when: - - Developer tasks cluster cleanly into 3–5 conceptual domains - The library has a clear core + framework adapter split - Skills build on each other in a layered way Use **flat** (`skills/[skill-name]/SKILL.md`) when: - - Developer tasks are task-focused and don't nest into domains - The domain discovery process recommended task-focused skills - Skills map 1:1 to distinct developer intents with minimal overlap @@ -288,10 +286,10 @@ not promotional. Framework-agnostic.] ## Sub-Skills -| Need to... | Read | -| ---------- | ------------------------------ | -| [task 1] | [lib]-core/[domain-1]/SKILL.md | -| [task 2] | [lib]-core/[domain-2]/SKILL.md | +| Need to... | Read | +|------------|------| +| [task 1] | [lib]-core/[domain-1]/SKILL.md | +| [task 2] | [lib]-core/[domain-2]/SKILL.md | ## Quick Decision Tree @@ -330,7 +328,6 @@ sources: **1. Setup** Minimum working example for this domain. - - Use the library's core API, not framework-specific hooks - Real package imports with exact names - No `// ...` or `[your code here]` — complete and copy-pasteable @@ -340,7 +337,6 @@ Minimum working example for this domain. **2. Core Patterns** 2–4 patterns. For each: - - One-line heading: what it accomplishes - Complete code block using core API - One sentence of explanation only if not self-explanatory @@ -360,18 +356,15 @@ both files. Do not deduplicate across skills at the cost of coverage. Format: -````markdown +```markdown ### [PRIORITY] [What goes wrong — 5–8 word phrase] Wrong: - ```[lang] // code that looks correct but isn't ``` -```` Correct: - ```[lang] // code that works ``` @@ -379,8 +372,7 @@ Correct: [One sentence: the specific mechanism by which the wrong version fails.] Source: [doc page or source file:line] - -```` +``` Priority levels: - **CRITICAL** — Breaks in production. Security risk or data loss. @@ -404,7 +396,7 @@ Every mistake must be plausible (an agent would generate it), silent ## References - [Complete option reference](references/options.md) -```` +``` Create reference files when any of these apply — not just length overflow: @@ -563,7 +555,6 @@ rather than learning patterns. Use the alternative body structure below for these skill types. **When to use the checklist body:** - - `security` type skills — pre-deploy security validation - `lifecycle` type skills focused on verification (go-live, migration) - Any skill where the primary action is "check these things" not "learn @@ -579,7 +570,7 @@ description: > type: security library: [lib] framework: react -library_version: '[version]' +library_version: "[version]" requires: - react-[lib] --- @@ -587,7 +578,7 @@ requires: **Alternative body template (checklist/audit):** -````markdown +```markdown # [Library Name] — [Security | Go-Live | Migration] Checklist Run through each section before [deploying | releasing | migrating]. @@ -597,11 +588,9 @@ Run through each section before [deploying | releasing | migrating]. ### Check: [what to verify] Expected: - ```[lang] // correct configuration or code ``` -```` Fail condition: [what indicates this check failed] Fix: [one-line remediation] @@ -624,8 +613,7 @@ Common Mistakes in standard skills] - [ ] [Verification 1] - [ ] [Verification 2] - [ ] [Verification 3] - -```` +``` The key differences from the standard body: - No "Setup" section — the agent already has the app running @@ -703,12 +691,11 @@ stale_skills: current_skills: - skill: "[skill name]" reason: "[no changes affect this domain]" -```` +``` ### Step 2 — Update stale skills **BREAKING changes:** - 1. Old pattern becomes a new Common Mistake entry (wrong/correct pair) 2. Update Setup if initialization changed 3. Update Core Patterns if idiomatic approach changed @@ -716,20 +703,17 @@ current_skills: 5. Check both core AND framework skills — breaking changes may affect both **DEPRECATION changes:** - 1. Add Common Mistake: deprecated API as wrong, replacement as correct 2. Update Core Patterns to use non-deprecated API 3. Bump `library_version` **BEHAVIORAL changes:** - 1. Default value changed → add Common Mistake entry 2. Type signature more restrictive → add Common Mistake entry 3. Update affected code blocks 4. Bump `library_version` **ADDITIVE changes:** - 1. Evaluate if new feature belongs in existing domain or needs a new skill 2. If existing: add to Core Patterns or references/ 3. If new skill needed: create it and update the parent skill's sub-skill @@ -744,15 +728,12 @@ current_skills: ### Updated for [library] v[new version] **Breaking changes:** - - [skill name]: [what changed and why] **Deprecation updates:** - - [skill name]: [old API] → [new API] **New skills:** - - [skill name]: [what it covers] ``` @@ -760,26 +741,26 @@ current_skills: ## Constraints — verify for every file -| Check | Rule | -| ------------------------------------------- | ----------------------------------------------------------------------------------- | -| Under 500 lines per SKILL.md | Move excess to references/; also create references for content depth | -| Real imports in every code block | Exact package, correct adapter | -| No external concept explanations | No "TypeScript is...", no "React hooks are..." — library-specific concepts are fine | -| No marketing prose | First body line is heading, code, or dependency note | -| Complete code blocks | Every block works without modification | -| Common Mistakes are silent | Not obvious compile errors | -| Common Mistakes are library-specific | Not generic TS/React mistakes | -| Common Mistakes are sourced | Traceable to doc or source | -| Core skills are framework-agnostic | No hooks, no components, no providers | -| Framework skills have `requires` | Lists core dependency | -| Framework skills open with dependency note | First prose line references core | -| Composition skills require all dependencies | Lists all core + framework skills | -| `name` matches directory | `router-core/search-params` → file at that path | -| `library_version` in every frontmatter | Which version the skill targets | -| Cross-skill failures duplicated | Each listed skill gets the failure mode | -| Tensions cross-referenced | Tension notes in each involved skill point to the other | -| Skills ship with packages | `"skills"` in package.json `files` array | -| Checklist skills use audit template | Security/go-live skills use checklist body, not standard body | +| Check | Rule | +|-------|------| +| Under 500 lines per SKILL.md | Move excess to references/; also create references for content depth | +| Real imports in every code block | Exact package, correct adapter | +| No external concept explanations | No "TypeScript is...", no "React hooks are..." — library-specific concepts are fine | +| No marketing prose | First body line is heading, code, or dependency note | +| Complete code blocks | Every block works without modification | +| Common Mistakes are silent | Not obvious compile errors | +| Common Mistakes are library-specific | Not generic TS/React mistakes | +| Common Mistakes are sourced | Traceable to doc or source | +| Core skills are framework-agnostic | No hooks, no components, no providers | +| Framework skills have `requires` | Lists core dependency | +| Framework skills open with dependency note | First prose line references core | +| Composition skills require all dependencies | Lists all core + framework skills | +| `name` matches directory | `router-core/search-params` → file at that path | +| `library_version` in every frontmatter | Which version the skill targets | +| Cross-skill failures duplicated | Each listed skill gets the failure mode | +| Tensions cross-referenced | Tension notes in each involved skill point to the other | +| Skills ship with packages | `"skills"` in package.json `files` array | +| Checklist skills use audit template | Security/go-live skills use checklist body, not standard body | ---