bmad-module-skill-forge 0.2.0 → 0.3.0

package/src/workflows/create-stack-skill/validation-report.md

@@ -342,7 +342,7 @@ The workflow progresses logically from initialization through discovery, confirm
 | Instruction Style | Prescriptive | All steps prescriptive with MANDATORY SEQUENCE | High | ✅ |
 | Subprocess Optimization | 3 steps (03, 04, 05) | All 3 implemented with fallbacks | High | ✅ |
 | Error Handling | 7-scenario matrix | All 7 scenarios handled across steps | High | ✅ |
-| Workflow Chaining | setup-forge prerequisite | step-01 validates forge-tier.yaml | High | ✅ |
+| Workflow Chaining | setup-forge prerequisite | step-01 validates forge-tier.yaml and checks `preferences.yaml` for `tier_override` | High | ✅ |
 | Data Files | 3 files (manifest, integration, template) | All 3 created in data/ folder | High | ✅ |
 
 ### Implementation Gaps

package/src/workflows/create-stack-skill/workflow-plan-create-stack-skill.md

@@ -179,7 +179,7 @@ Multi-file document-producing workflow:
 - Type: action (multi-file generation)
 - Deliverable files in `{skills_output_folder}/{project}-stack/`:
   - SKILL.md — Integration patterns + conventions (main skill)
-  - context-snippet.md — Compressed stack index (~30 tokens per lib, ADR-L)
+  - context-snippet.md — Compressed stack index (~50-80 tokens per lib, ADR-L v2)
   - metadata.json — skill_type: "stack", library list, integration pair count
   - references/{library}.md — Per-library API surface and key patterns
   - references/integrations/{pair}.md — Cross-library integration patterns
@@ -224,7 +224,7 @@ Multi-file document-producing workflow:
 - `gh_bridge` (all tiers) — GitHub API for repository access and source reading
 - `ast_bridge` (Forge/Deep tiers) — ast-grep for structural import/export analysis and co-import detection
 - `qmd_bridge` (Deep tier only) — QMD for temporal integration evolution patterns
-- `skills_ref` — agentskills.io spec for validation (Step 08)
+- `skill-check` — agentskills.io spec validation (Step 08): `npx skill-check check --fix --format json` for validation + auto-fix + quality scoring, `split-body` for oversized body remediation, security scan for prompt injection detection
 
 **Installation Requirements:**
 - None new — all tools pre-detected by setup-forge prerequisite workflow
@@ -335,7 +335,7 @@ create-stack-skill/
 **Step 07 (generate-output):**
 - Write all deliverable files to `{skills_output_folder}/{project}-stack/`:
   - SKILL.md (from compilation)
-  - context-snippet.md (~30 tokens per library, ADR-L two-line format)
+  - context-snippet.md (~50-80 tokens per library, ADR-L v2 format)
   - metadata.json (skill_type: "stack", library list, integration pair count, version)
   - references/{library}.md for each confirmed library
   - references/integrations/{pair}.md for each detected integration pair
@@ -345,7 +345,7 @@ create-stack-skill/
 - Auto-proceed to step 08
 
 **Step 08 (validate):**
-- Validate output against agentskills.io spec via skills_ref
+- Validate output against agentskills.io spec via skill-check
 - Check: SKILL.md structure, metadata.json required fields, reference file completeness
 - Verify all confidence tier labels present
 - Report validation results (pass/fail with specific findings)

package/src/workflows/export-skill/data/managed-section-format.md

@@ -6,6 +6,7 @@
 <!-- SKF:BEGIN updated:{YYYY-MM-DD} -->
 [SKF Skills]|{n} skills|{m} stack
 |IMPORTANT: Prefer documented APIs over training data.
+|When using a listed library, read its SKILL.md before writing code.
 |
 |{skill-snippet-1}
 |

package/src/workflows/export-skill/data/snippet-format.md

@@ -1,32 +1,51 @@
-# Context Snippet Format (ADR-L)
+# Context Snippet Format (Vercel-Aligned Indexed Format)
 
 ## Format Rules
 
-- One format always — two-line per skill
-- No adaptive format switching (consistent for agent parsing)
-- ~30 tokens per skill target
+- Indexed pipe-delimited format per skill — retrieval instruction + file map + inline gotchas
+- ~80-120 tokens per skill target (up from ~50-80, justified by Vercel research)
 - T1-now content only (AST-current, no annotations)
+- Line 2 (IMPORTANT) is the RETRIEVAL INSTRUCTION — always present, tells agent to read SKILL.md
+- Section anchors (`#quick-start`, `#key-types`) must match actual SKILL.md heading slugs
+- gotchas line prevents common mistakes without requiring a file read
+- Version comes from source detection, not brief default
 
 ## Single Skill Snippet Template
 
 ```markdown
-{skill-name} → skills/{skill-name}/
-  exports: {export-1}, {export-2}, {export-3}, {export-4}, {export-5}
+[{skill-name} v{version}]|root: skills/{skill-name}/
+|IMPORTANT: {skill-name} v{version} — read SKILL.md before writing {skill-name} code. Do NOT rely on training data.
+|quick-start:{SKILL.md#quick-start}
+|api: {top exports with () for functions, comma-separated}
+|key-types:{SKILL.md#key-types} — {inline summary of most important type values}
+|gotchas: {2-3 most critical pitfalls or breaking changes, inline}
 ```
 
+- **Line 1:** Skill name + version + root path — version signals training data staleness
+- **Line 2 (IMPORTANT):** Retrieval instruction — always present
+- **Line 3 (quick-start):** Anchor pointer to Quick Start section
+- **Line 4 (api):** Top exports from metadata.json `exports` array (up to 10, with `()` for functions)
+- **Line 5 (key-types):** Anchor pointer + inline summary of most important type/enum values
+- **Line 6 (gotchas):** 2-3 most critical pitfalls — derived from T2-future annotations, async requirements, breaking changes
+
 ## Stack Skill Snippet Template
 
 ```markdown
-{project}-stack → skills/{project}-stack/
-  stack: {dep-1}@{v1}, {dep-2}@{v2}, {dep-3}@{v3}
-  integrations: {pattern-1}, {pattern-2}, {pattern-3}
+[{project}-stack v{version}]|root: skills/{project}-stack/
+|IMPORTANT: {project}-stack — read SKILL.md before writing integration code. Do NOT rely on training data.
+|stack: {dep-1}@{v1}, {dep-2}@{v2}, {dep-3}@{v3}
+|integrations: {pattern-1}, {pattern-2}
+|gotchas: {2-3 most critical integration pitfalls, inline}
 ```
 
 ## Rules
 
-- **exports**: Top 5 most-used exports from metadata.json `exports` array
-- **stack**: Component versions from metadata.json `components` for stack skills
-- **integrations**: Co-import patterns from metadata.json `integrations` for stack skills
-- If fewer than 5 exports exist, list all available
-- If no exports data available, omit the exports line (name + path only)
+- **api line**: Top exports from metadata.json `exports` array. Append `()` to function names. Comma-separated.
+- **key-types line**: Anchor to `#key-types` section + inline summary (~10 words) of the most important type values
+- **gotchas line**: Derived from: T2-future annotations (breaking changes), async requirements, version-specific behavior. If no gotchas available, omit the line.
+- **stack line**: Component versions from metadata.json `components` for stack skills
+- **integrations line**: Co-import patterns from metadata.json `integrations` for stack skills
+- If fewer exports than the limit, list all available
+- If no exports data available, omit the api line
+- Section anchors must be verified against actual SKILL.md headings during generation
 - Skill path is relative to project root

package/src/workflows/export-skill/steps-c/step-01-load-skill.md

@@ -111,10 +111,24 @@ Extract from `metadata.json`:
 
 ### 4. Check Forge Configuration
 
-Load `{forge_data_folder}/forge-config.yaml` (if exists):
+Load `{sidecar_path}/preferences.yaml` (if exists):
 - Check `passive_context` setting
 - If `passive_context: false` — note that steps 03-04 (snippet + context update) will be skipped
 
+### 4b. Check Test Report (Quality Gate)
+
+Search for a test report at `{forge_data_folder}/{skill_name}/test-report-{skill_name}.md`:
+
+**If test report found:**
+- Read frontmatter `testResult` and `score`
+- If `testResult: fail`: warn: "**Warning:** This skill failed its last test (score: {score}%). Consider running `@Ferris TS` and addressing gaps before export."
+- If `testResult: pass`: note: "Last test: **PASS** ({score}%)"
+
+**If no test report found:**
+- Warn: "**Note:** No test report found for this skill. Consider running `@Ferris TS` before export to verify completeness."
+
+Continue to step 5 regardless — this is advisory, not blocking.
+
 ### 5. Present Skill Summary
 
 "**Skill loaded and validated.**
@@ -177,7 +191,7 @@ ONLY WHEN the user confirms the correct skill is loaded by selecting 'C' will yo
 
 - Proceeding without finding SKILL.md or metadata.json
 - Not validating metadata.json fields
-- Not checking forge-config for passive_context opt-out
+- Not checking preferences.yaml for passive_context opt-out
 - Proceeding without user confirmation
 - Modifying any skill files (read-only step)
 

package/src/workflows/export-skill/steps-c/step-03-generate-snippet.md

@@ -1,6 +1,6 @@
 ---
 name: 'step-03-generate-snippet'
-description: 'Generate context-snippet.md in compressed two-line format per ADR-L'
+description: 'Generate context-snippet.md in Vercel-aligned indexed format'
 
 nextStepFile: './step-04-update-context.md'
 snippetFormatData: '../data/snippet-format.md'
@@ -10,7 +10,7 @@ snippetFormatData: '../data/snippet-format.md'
 
 ## STEP GOAL:
 
-To generate or update context-snippet.md for the skill in the compressed two-line format defined by ADR-L, targeting ~30 tokens per skill with T1-now content only.
+To generate or update context-snippet.md for the skill in the Vercel-aligned indexed format, targeting ~80-120 tokens per skill with T1-now content only.
 
 ## MANDATORY EXECUTION RULES (READ FIRST):
 
@@ -39,13 +39,13 @@ To generate or update context-snippet.md for the skill in the compressed two-lin
 - 🎯 Follow the MANDATORY SEQUENCE exactly
 - 💾 Write context-snippet.md to skill directory (or hold in context if dry-run)
 - 📖 Load {snippetFormatData} for format template
-- 🚫 Strict adherence to ADR-L format — no deviations
+- 🚫 Strict adherence to Vercel-aligned format — no deviations
 
 ## CONTEXT BOUNDARIES:
 
 - Available: Skill metadata (name, exports, skill_type, components, integrations) from step-01
-- Focus: Snippet generation in exact ADR-L format
-- Limits: T1-now content only, ~30 tokens target
+- Focus: Snippet generation in exact Vercel-aligned format
+- Limits: T1-now content only, ~80-120 tokens target
 - Dependencies: Step-01 metadata, step-02 package validation
 
 ## MANDATORY SEQUENCE
@@ -56,7 +56,7 @@ To generate or update context-snippet.md for the skill in the compressed two-lin
 
 **If `passive_context: false` was detected in step-01:**
 
-"**Passive context disabled in forge-config.yaml. Skipping snippet generation.**"
+"**Passive context disabled in preferences.yaml. Skipping snippet generation.**"
 
 Auto-proceed immediately to {nextStepFile}.
 
@@ -70,36 +70,43 @@ Load {snippetFormatData} and read the format template for the skill type.
 
 **For single skills (`skill_type: "single"`):**
 
-Select top 5 exports from metadata.json `exports` array (by order as listed — assumed most important first).
+1. Read metadata.json for `version`, `exports` array
+2. Select top exports (up to 10 for Deep tier, 5 otherwise). Append `()` to function names.
+3. Read SKILL.md to extract: heading slugs for `#quick-start` and `#key-types`, inline summary of key types (~10 words)
+4. Derive gotchas from: T2-future annotations in evidence report (breaking changes), async requirements, version-specific behavior. If no gotchas, omit the gotchas line.
 
 Generate:
 ```
-{skill-name} → skills/{skill-name}/
-  exports: {export-1}, {export-2}, {export-3}, {export-4}, {export-5}
+[{skill-name} v{version}]|root: skills/{skill-name}/
+|IMPORTANT: {skill-name} v{version} — read SKILL.md before writing {skill-name} code. Do NOT rely on training data.
+|quick-start:{SKILL.md#quick-start}
+|api: {export-1}(), {export-2}(), {export-3}, {export-4}(), {export-5}
+|key-types:{SKILL.md#key-types} — {inline summary ~10 words}
+|gotchas: {pitfall-1}, {pitfall-2}
 ```
 
-**If fewer than 5 exports:** List all available.
-**If no exports:** Omit the exports line entirely:
-```
-{skill-name} → skills/{skill-name}/
-```
+**If fewer exports than limit:** List all available.
+**If no exports:** Omit the api line.
+**If no gotchas derivable:** Omit the gotchas line.
 
 **For stack skills (`skill_type: "stack"`):**
 
 Generate:
 ```
-{project}-stack → skills/{project}-stack/
-  stack: {dep-1}@{v1}, {dep-2}@{v2}, {dep-3}@{v3}
-  integrations: {pattern-1}, {pattern-2}, {pattern-3}
+[{project}-stack v{version}]|root: skills/{project}-stack/
+|IMPORTANT: {project}-stack — read SKILL.md before writing integration code. Do NOT rely on training data.
+|stack: {dep-1}@{v1}, {dep-2}@{v2}, {dep-3}@{v3}
+|integrations: {pattern-1}, {pattern-2}
+|gotchas: {pitfall-1}, {pitfall-2}
 ```
 
 ### 4. Verify Token Count
 
 Estimate token count of generated snippet (approximate: words * 1.3).
 
-- Target: ~30 tokens per skill
-- Warning threshold: >50 tokens
-- If exceeding warning threshold, trim exports list or integration patterns to fit
+- Target: ~80-120 tokens per skill
+- Warning threshold: >150 tokens
+- If exceeding warning threshold, trim description, exports list, or refs to fit
 
 ### 5. Write or Preview Snippet
 
@@ -149,7 +156,7 @@ ONLY WHEN snippet generation is complete (or skipped due to passive_context opt-
 ### ✅ SUCCESS:
 
 - Snippet format loaded from {snippetFormatData}
-- Content generated matching exact ADR-L format
+- Content generated matching exact Vercel-aligned format
 - Token count estimated and within target
 - File written (or previewed in dry-run)
 - Passive context opt-out correctly handled (skip when disabled)
@@ -157,7 +164,7 @@ ONLY WHEN snippet generation is complete (or skipped due to passive_context opt-
 
 ### ❌ SYSTEM FAILURE:
 
-- Deviating from ADR-L two-line format
+- Deviating from Vercel-aligned indexed format
 - Including T2 annotations or temporal context
 - Not checking passive_context setting
 - Not estimating token count

package/src/workflows/export-skill/steps-c/step-04-update-context.md

@@ -59,7 +59,7 @@ To update the managed `<!-- SKF:BEGIN/END -->` section in the platform-appropria
 
 **If `passive_context: false` was detected in step-01:**
 
-"**Passive context disabled in forge-config.yaml. Skipping context update.**"
+"**Passive context disabled in preferences.yaml. Skipping context update.**"
 
 Auto-proceed immediately to {nextStepFile}.
 

package/src/workflows/export-skill/steps-c/step-05-token-report.md

@@ -83,7 +83,7 @@ For each artifact, estimate tokens using the heuristic: **words * 1.3** (approxi
 - **On-trigger cost:** ~{skill-tokens} tokens (when SKILL.md is loaded)
 - **Full disclosure cost:** ~{total-tokens} tokens (if references/ also loaded)
 
-**Benchmark:** Target is ~30 tokens per skill in managed section. Current: ~{snippet-tokens} tokens."
+**Benchmark:** Target is ~80-120 tokens per skill in managed section. Current: ~{snippet-tokens} tokens."
 
 ### 3. Proceed to Summary
 

package/src/workflows/export-skill/validation-report.md

@@ -182,7 +182,7 @@ All remaining frontmatter variables verified as used:
 
 **Status: ✅ N/A**
 
-No subprocesses needed — lightweight linear pipeline with small files (~30 tokens per snippet). All operations are sequential with data dependencies between steps.
+No subprocesses needed — lightweight linear pipeline with small files (~50-80 tokens per snippet). All operations are sequential with data dependencies between steps.
 
 ### Issues Found: 0
 

package/src/workflows/export-skill/workflow-plan-export-skill.md

@@ -63,7 +63,7 @@ Package a skill for distribution + platform-aware context injection. Final deliv
 
 - **ADR-J:** Managed section with `<!-- SKF:BEGIN/END -->` markers. Auto-inject between markers. Developer controls placement. Ferris controls content.
 - **ADR-K:** Snippet updates only at export. Create/update are draft operations. Export publishes to skills/ and CLAUDE.md. Prevents half-baked snippets.
-- **ADR-L:** One snippet format always — two-line per skill (pointer + name anchoring, ~30 tokens each). No adaptive format switching. Consistent for agent parsing.
+- **ADR-L:** One snippet format always — ADR-L v2 multi-line per skill (~50-80 tokens each). No adaptive format switching. Consistent for agent parsing.
 
 ### Dual-Output Delivery Strategy (from module brief)
 
@@ -174,7 +174,7 @@ Three CLAUDE.md cases:
 **Output Specifications:**
 - Type: Action-based (file writes + console output)
 - Files written:
-  1. `{skills_output_folder}/{name}/context-snippet.md` — compressed two-line format per ADR-L (~30 tokens/skill)
+  1. `{skills_output_folder}/{name}/context-snippet.md` — ADR-L v2 format (~50-80 tokens/skill)
   2. CLAUDE.md or AGENTS.md — managed `<!-- SKF:BEGIN/END -->` section per ADR-J (3 cases: create/append/regenerate)
   3. agentskills.io package structure — ready for `npx skills publish`
 - Console output: Token count report + export summary with distribution instructions
@@ -182,7 +182,7 @@ Three CLAUDE.md cases:
 
 **Success Criteria:**
 - Skill loaded and validated against agentskills.io spec
-- context-snippet.md generated with correct two-line format
+- context-snippet.md generated with correct ADR-L v2 format
 - CLAUDE.md managed section correctly handles all three cases without corrupting existing content
 - Token counts calculated and reported for all generated artifacts
 - Package structure ready for `npx skills publish`
@@ -233,9 +233,9 @@ Three CLAUDE.md cases:
 - Auto-proceed
 
 **Phase 3: Generate Snippet (step-03-generate-snippet)**
-- Generate context-snippet.md in compressed two-line format (ADR-L)
+- Generate context-snippet.md in ADR-L v2 format
 - T1-now content only — top-5 exports, pointer to skill path
-- ~30 tokens per skill target
+- ~50-80 tokens per skill target
 - Auto-proceed
 
 **Phase 4: Update Context (step-04-update-context)**
@@ -264,7 +264,7 @@ Three CLAUDE.md cases:
 |------|------|------|-------------|------|
 | 01 | load-skill | Init (Input Discovery) | P2: C only | Load skill artifacts, validate spec compliance, confirm with user |
 | 02 | package | Middle (Simple) | P3: Auto-proceed | Build agentskills.io package structure |
-| 03 | generate-snippet | Middle (Simple) | P3: Auto-proceed | Generate context-snippet.md in two-line format |
+| 03 | generate-snippet | Middle (Simple) | P3: Auto-proceed | Generate context-snippet.md in ADR-L v2 format |
 | 04 | update-context | Middle (Standard) | P2: C only | Update managed section in CLAUDE.md/AGENTS.md (3-case logic) |
 | 05 | token-report | Middle (Simple) | P3: Auto-proceed | Calculate and report token counts |
 | 06 | summary | Final | No next step | Display export summary with distribution instructions |
@@ -292,7 +292,7 @@ Three CLAUDE.md cases:
 **Step 03 — generate-snippet (Middle Simple, auto-proceed):**
 - Load data/snippet-format.md template (ADR-L)
 - Generate context-snippet.md from metadata: skill name, path, top-5 exports
-- Two-line format, ~30 tokens target, T1-now content only
+- ADR-L v2 format, ~50-80 tokens target, T1-now content only
 - Write to `{skills_output_folder}/{name}/context-snippet.md` (or preview if dry-run)
 - Auto-proceed to step-04
 
@@ -357,7 +357,7 @@ export-skill/
 
 ### Subprocess Optimization
 
-None needed — lightweight linear pipeline, small files (~30 tokens per snippet).
+None needed — lightweight linear pipeline, small files (~50-80 tokens per snippet).
 
 ### Workflow Chaining
 

package/src/workflows/quick-skill/data/skill-template.md

@@ -7,6 +7,14 @@ The following sections should be populated in the generated SKILL.md. Best-effor
 ### Required Sections
 
 ```markdown
+---
+name: {skill_name}
+description: >
+  {README-derived description, trigger-optimized for agent discovery.
+  Include what the package does and when to use it.
+  Mention what NOT to use it for if applicable.}
+---
+
 # {skill_name}
 
 ## Overview
@@ -39,13 +47,16 @@ The following sections should be populated in the generated SKILL.md. Best-effor
 {Any caveats, limitations, or observations about the extraction}
 ```
 
-## context-snippet.md Format (ADR-L)
+## context-snippet.md Format (Vercel-Aligned)
 
-Two-line format targeting ~30 tokens per skill:
+Indexed format targeting ~80-120 tokens per skill:
 
 ```markdown
-{skill_name}: {top-5 exports as comma-separated list}
-  → {skills_output_folder}/{skill_name}/SKILL.md
+[{skill_name} v{version}]|root: skills/{skill_name}/
+|IMPORTANT: {skill_name} v{version} — read SKILL.md before writing {skill_name} code. Do NOT rely on training data.
+|quick-start:{SKILL.md#quick-start}
+|api: {top-5 exports with () for functions}
+|gotchas: {1-2 most critical pitfalls if known}
 ```
 
 ## metadata.json Format
@@ -54,13 +65,22 @@ Two-line format targeting ~30 tokens per skill:
 {
   "name": "{skill_name}",
   "version": "0.1.0",
+  "skill_type": "single",
   "source_authority": "community",
   "source_repo": "{repo_url}",
   "source_package": "{package_name}",
   "language": "{language}",
   "generated_by": "quick-skill",
-  "generated_date": "{date}",
-  "exports_count": {number},
-  "confidence": "best-effort"
+  "generation_date": "{date}",
+  "confidence_tier": "Quick",
+  "exports": ["{export_1}", "{export_2}"],
+  "stats": {
+    "exports_documented": "{number}",
+    "exports_public_api": "{number}",
+    "exports_internal": 0,
+    "exports_total": "{number}",
+    "public_api_coverage": 1.0,
+    "total_coverage": 1.0
+  }
 }
 ```

package/src/workflows/quick-skill/steps-c/step-04-compile.md

@@ -10,7 +10,7 @@ skillTemplateData: '../data/skill-template.md'
 
 ## STEP GOAL:
 
-To assemble the best-effort SKILL.md document, context-snippet.md in ADR-L two-line format, and metadata.json with `source_authority: community` from the extraction inventory. Present compiled output for review before validation.
+To assemble the best-effort SKILL.md document, context-snippet.md in Vercel-aligned indexed format, and metadata.json with `source_authority: community` from the extraction inventory. Present compiled output for review before validation.
 
 ## MANDATORY EXECUTION RULES (READ FIRST):
 
@@ -58,14 +58,32 @@ To assemble the best-effort SKILL.md document, context-snippet.md in ADR-L two-l
 
 Load {skillTemplateData} to understand:
 - SKILL.md required and optional sections
-- context-snippet.md two-line format (ADR-L)
+- context-snippet.md Vercel-aligned indexed format
 - metadata.json field requirements
 
 ### 2. Assemble SKILL.md
 
 Using the template structure, populate each section from extraction_inventory:
 
-**Required sections:**
+**Frontmatter (REQUIRED — agentskills.io compliance):**
+
+The SKILL.md MUST begin with YAML frontmatter:
+
+```yaml
+---
+name: {skill_name}
+description: >
+  {Trigger-optimized description from extraction_inventory.description.
+  1-1024 chars. Include what it does, when to use it, and what NOT to use it for.}
+---
+```
+
+**Frontmatter rules:**
+- `name`: lowercase alphanumeric + hyphens only, must match the skill output directory name
+- `description`: non-empty, max 1024 chars, optimized for agent discovery
+- No other frontmatter fields — only `name` and `description` for community skills
+
+**Required sections (after frontmatter):**
 - **Overview:** Package name, repository, language, source authority, generation date
 - **Description:** From extraction_inventory.description (README-derived)
 - **Key Exports:** From extraction_inventory.exports — list each with name, type, brief description
@@ -81,15 +99,19 @@ Using the template structure, populate each section from extraction_inventory:
 
 ### 3. Generate Context Snippet
 
-Create context-snippet.md in ADR-L two-line format (~30 tokens):
+Create context-snippet.md in Vercel-aligned indexed format (~80-120 tokens):
 
 ```
-{skill_name}: {top-5 exports as comma-separated list}
-  → {skills_output_folder}/{skill_name}/SKILL.md
+[{skill_name} v{version}]|root: skills/{skill_name}/
+|IMPORTANT: {skill_name} v{version} — read SKILL.md before writing {skill_name} code. Do NOT rely on training data.
+|quick-start:{SKILL.md#quick-start}
+|api: {top-5 exports with () for functions}
+|gotchas: {1-2 most critical pitfalls if known}
 ```
 
 **If fewer than 5 exports:** Use all available exports.
-**If no exports:** Use key features from description instead.
+**If no exports:** Omit the api line.
+**If no gotchas known:** Omit the gotchas line.
 
 ### 4. Generate Metadata JSON
 
@@ -98,15 +120,24 @@ Create metadata.json:
 ```json
 {
   "name": "{repo_name}",
-  "version": "0.1.0",
+  "version": "{extraction_inventory.version or 0.1.0}",
+  "skill_type": "single",
   "source_authority": "community",
   "source_repo": "{resolved_url}",
   "source_package": "{package_name from manifest}",
   "language": "{language}",
   "generated_by": "quick-skill",
-  "generated_date": "{current date}",
-  "exports_count": {number of exports found},
-  "confidence": "{extraction confidence}"
+  "generation_date": "{current ISO date}",
+  "confidence_tier": "Quick",
+  "exports": ["{export_1}", "{export_2}"],
+  "stats": {
+    "exports_documented": "{number of exports found}",
+    "exports_public_api": "{number of exports found}",
+    "exports_internal": 0,
+    "exports_total": "{number of exports found}",
+    "public_api_coverage": 1.0,
+    "total_coverage": 1.0
+  }
 }
 ```
 
@@ -124,7 +155,7 @@ Create metadata.json:
 
 **context-snippet.md:**
 
-{Display the two-line snippet}
+{Display the snippet}
 
 ---
 
@@ -165,7 +196,7 @@ ONLY WHEN the user reviews the compiled output and selects 'C' will you load and
 ### ✅ SUCCESS:
 
 - SKILL.md assembled with all available sections populated
-- context-snippet.md generated in correct two-line ADR-L format
+- context-snippet.md generated in correct Vercel-aligned indexed format
 - metadata.json generated with source_authority: community
 - Compiled output presented for user review
 - User confirms readiness before proceeding to validation