bmad-module-skill-forge 0.2.0 → 0.3.0

package/src/workflows/create-skill/steps-c/step-07-generate-artifacts.md

@@ -2,6 +2,7 @@
 name: 'step-07-generate-artifacts'
 description: 'Write all output files — 4 deliverables to skills/ and 3 workspace artifacts to forge-data/'
 nextStepFile: './step-08-report.md'
+forgeTierConfig: '{sidecar_path}/forge-tier.yaml'
 ---
 
 # Step 7: Generate Artifacts
@@ -124,16 +125,62 @@ Display brief confirmation:
 
 Proceeding to compilation report..."
 
-### 5. Menu Handling Logic
+### 5. QMD Collection Registration (Deep Tier Only)
+
+**IF forge tier is Deep AND QMD tool is available:**
+
+Index the generated skill artifacts into a QMD collection so that audit-skill and update-skill can perform high-signal searches against curated extraction data instead of raw source files.
+
+**Collection creation:**
+
+Create a QMD collection from both artifact directories:
+```bash
+qmd collection add {project-root}/skills/{name} --name {name}-extraction --mask "**/*"
+qmd embed
+```
+
+If collection already exists (re-run): remove and recreate for atomic replace:
+```bash
+qmd collection remove {name}-extraction
+qmd collection add {project-root}/skills/{name} --name {name}-extraction --mask "**/*"
+qmd embed
+```
+
+**Note:** `qmd embed` generates vector embeddings required for `vector_search` and `deep_search`. Without it, only BM25 keyword `search` works.
+
+**Registry update:**
+
+Read `{forgeTierConfig}` and update the `qmd_collections` array.
+
+If an entry with `name: "{name}-extraction"` already exists, replace it. Otherwise, append:
+
+```yaml
+  - name: "{name}-extraction"
+    type: "extraction"
+    source_workflow: "create-skill"
+    skill_name: "{name}"
+    created_at: "{current ISO date}"
+```
+
+Write the updated forge-tier.yaml.
+
+**Error handling:**
+- If QMD collection creation fails: log the error, note that indexing can be retried via [SF] setup-forge. Do NOT fail the workflow.
+- If forge-tier.yaml update fails: log the error, continue. The collection exists in QMD even if the registry entry failed.
+
+**IF forge tier is NOT Deep:** Skip this section silently. No messaging.
+
+### 6. Menu Handling Logic
 
 **Auto-proceed step — no user interaction.**
 
-After all artifacts are written and verified, immediately load, read entire file, then execute `{nextStepFile}`.
+After all artifacts are written, verified, and optionally indexed into QMD, immediately load, read entire file, then execute `{nextStepFile}`.
 
 #### EXECUTION RULES:
 
 - This is an auto-proceed file writing step with no user choices
 - All 7 files must be written before proceeding
+- QMD indexing failure does NOT block proceeding
 - File write failures are real errors — halt, do not proceed with partial output
 - Proceed directly to next step after successful generation
 
@@ -151,6 +198,8 @@ ONLY WHEN all 7 artifact files are written and verified will you proceed to load
 - All 4 deliverable files written to skills/{name}/
 - All 3 workspace artifact files written to forge-data/{name}/
 - Write completion verified — all 7 files exist
+- Deep tier: QMD collection `{name}-extraction` created/updated and registered in forge-tier.yaml
+- Non-Deep tier: QMD indexing skipped silently
 - Brief confirmation displayed with file list
 - Auto-proceeded to step-08
 
@@ -161,5 +210,6 @@ ONLY WHEN all 7 artifact files are written and verified will you proceed to load
 - Proceeding with partial output if a write fails
 - Not creating directories before writing
 - Not verifying all files were written
+- Failing the workflow due to QMD indexing errors (should degrade gracefully)
 
-**Master Rule:** This step ONLY writes. All content was compiled and validated in previous steps. Write faithfully, verify completely.
+**Master Rule:** This step writes artifacts and registers QMD collections. All content was compiled and validated in previous steps. Write faithfully, verify completely. QMD indexing failures never block the workflow.

package/src/workflows/create-skill/steps-c/step-08-report.md

@@ -66,7 +66,7 @@ Where `{primary_confidence}` is the predominant confidence tier (T1 if Forge/Dee
 | **Language** | {language} |
 | **Forge Tier** | {tier} — {tier_description} |
 | **Files Scanned** | {file_count} |
-| **Exports Documented** | {documented_count} of {total_count} ({coverage}%) |
+| **Exports Documented** | {documented_count} public API ({public_api_coverage}%) / {total_count} total ({total_coverage}%) |
 
 **Confidence Distribution:**
 | Tier | Count | Description |

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

@@ -34,7 +34,7 @@ Compile a skill from a brief — the core compilation engine. Takes a skill-brie
 **Step 3:** extract — AST extraction of exports, signatures, types (tier-dependent: Quick=source reading, Forge=AST, Deep=AST)
 **Step 4:** enrich — QMD knowledge search for temporal context (Deep tier only, skip for Quick/Forge)
 **Step 5:** compile — Assemble SKILL.md sections from extracted data with confidence tiers
-**Step 6:** validate — Validate against agentskills.io spec via skills_ref tool
+**Step 6:** validate — Validate against agentskills.io spec via skill-check tool
 **Step 7:** generate-artifacts — Write SKILL.md, provenance-map.json, evidence-report.md, metadata.json, context-snippet.md, extraction-rules.yaml
 **Step 8:** report — Display compilation summary with confidence tiers, suggest next steps
 
@@ -164,7 +164,7 @@ Compile a skill from a brief — the core compilation engine. Takes a skill-brie
 
 **Success Criteria:**
 - All 7 output files generated without errors
-- SKILL.md validates against agentskills.io spec (via skills_ref)
+- SKILL.md validates against agentskills.io spec (via skill-check)
 - Every instruction has provenance citation with confidence tier (T1/T2/T3)
 - Zero hallucinated content — uncitable claims excluded, not guessed
 - Confidence tier distribution reported (e.g., "20 T1, 3 T2, 0 T3")
@@ -187,7 +187,7 @@ Compile a skill from a brief — the core compilation engine. Takes a skill-brie
 - **Brainstorming:** Excluded — no ideation phases, all steps are deterministic operations
 
 **LLM Features:**
-- **Web-Browsing:** Excluded — source access via gh_bridge, ecosystem check via skills_ref. No raw web needed.
+- **Web-Browsing:** Excluded — source access via gh_bridge, ecosystem check via skill-check. No raw web needed.
 - **File I/O:** Included — essential. Reads skill-brief.yaml, forge-tier.yaml, source files. Writes 7 output files across 2 directory trees (skills/{name}/, forge-data/{name}/).
 - **Sub-Agents:** Excluded — linear pipeline with step dependencies, no parallelizable specialized tasks for single skill compilation
 - **Sub-Processes:** Excluded — sequential dependency chain. Batch mode is a loop wrapper, not parallel processes.
@@ -200,7 +200,7 @@ Compile a skill from a brief — the core compilation engine. Takes a skill-brie
 
 **External Integrations (SKF MCP Tools — all pre-detected by setup-forge):**
 - **gh_bridge:** Required all tiers — source reading, file trees, issues, releases, changelog
-- **skills_ref:** Required all tiers — agentskills.io spec validation, ecosystem check (5s timeout, 24h cache)
+- **skill-check:** Required all tiers — `npx skill-check check --fix --format json` for validation + auto-fix + quality scoring (0-100), `--no-security-scan` for fast validation, security scan for prompt injection detection, `split-body` for oversized body remediation
 - **ast_bridge:** Required Forge/Deep tiers — AST scan_definitions, run_rule, detect_co_imports
 - **qmd_bridge:** Required Deep tier only — search, vector_search, deep_search for temporal context
 
@@ -226,6 +226,8 @@ create-skill/
     ├── step-01-load-brief.md           (~150 lines, Init with Input Discovery)
     ├── step-02-ecosystem-check.md      (~120 lines, conditional gate)
     ├── step-03-extract.md              (~200 lines, complex middle)
+    ├── step-03b-fetch-temporal.md      (~240 lines, conditional auto-proceed)
+    ├── step-03c-fetch-docs.md          (~215 lines, conditional auto-proceed)
     ├── step-04-enrich.md               (~130 lines, conditional middle)
     ├── step-05-compile.md              (~200 lines, complex middle)
     ├── step-06-validate.md             (~120 lines, simple middle)
@@ -240,6 +242,8 @@ create-skill/
 | 01 | load-brief | Init (Input Discovery) | Auto-proceed (P3) | Load brief, resolve source, load forge tier |
 | 02 | ecosystem-check | Middle (Simple) | Conditional: auto if no match, user choice if match | Check ecosystem |
 | 03 | extract | Middle (Standard) | C only (P2) — Gate 2 | Tier-dependent extraction |
+| 03b | fetch-temporal | Middle (Simple) | Auto-proceed (P3) — Deep only | Fetch temporal context (issues, PRs, changelogs) and index into QMD |
+| 03c | fetch-docs | Middle (Simple) | Auto-proceed (P3) — when doc_urls present | Fetch remote documentation from brief-specified URLs for T3-confidence content |
 | 04 | enrich | Middle (Simple) | Auto-proceed (P3) — Deep only | QMD enrichment |
 | 05 | compile | Middle (Simple) | Auto-proceed (P3) | Assemble SKILL.md |
 | 06 | validate | Middle (Simple) | Auto-proceed (P3) | Validate spec |
@@ -258,10 +262,11 @@ create-skill/
 - Auto-proceed to step-02
 
 **step-02-ecosystem-check** (Conditional Gate)
-- Call skills_ref.check_ecosystem(brief.name) — 5-second timeout, 24-hour cache
+- Query agentskills.io registry API for brief.name — 5-second timeout, 24-hour cache
 - If match found: present to user with [P] Proceed / [I] Install existing / [A] Abort
 - If no match OR timeout: auto-proceed silently
-- If skills_ref unavailable: skip silently (tool unavailability is not an error)
+- If registry API unavailable: skip silently (API unavailability is not an error)
+- Note: ecosystem lookup requires registry API, not `skill-check` CLI (which validates local skills only)
 
 **step-03-extract** (Standard Middle — Gate 2)
 - Load extraction-patterns.md data file
@@ -270,6 +275,27 @@ create-skill/
 - Build extraction inventory: export count, signatures, types, confidence breakdown
 - Present summary, user confirms [C] Continue
 
+**step-03b-fetch-temporal** (Simple Middle — Conditional Auto-proceed)
+- Deep tier only — Quick/Forge skip silently
+- GitHub repos only — non-GitHub sources skip silently
+- Fetch temporal context (issues, PRs, releases, changelog) via `gh` CLI
+- Targeted function searches using top_exports from extraction inventory
+- Index fetched content into QMD collection (`{skill-name}-temporal`)
+- Register collection in forge-tier.yaml; clean up staging directory
+- Cache-aware: skip re-fetch if collection < 7 days old
+- All failures degrade gracefully — never blocks the workflow
+
+**step-03c-fetch-docs** (Simple Middle — Conditional Auto-proceed)
+- Runs at any tier when `doc_urls` are present in the brief
+- Tool-agnostic: uses whatever web fetching capability is available (Firecrawl, WebFetch, web-reader, curl, etc.)
+- Fetches remote documentation from brief-specified URLs for T3-confidence content
+- Root URL detection: discovers and fetches relevant subpages for documentation sites
+- All extracted items cited as T3 with `[EXT:{url}]` provenance
+- T3 items never override existing T1/T1-low/T2 extractions
+- Supports docs-only briefs (T3 inventory replaces empty extraction inventory)
+- Deep tier: indexes fetched docs into QMD collection (`{skill-name}-docs`)
+- All failures degrade gracefully — never blocks the workflow
+
 **step-04-enrich** (Simple Middle — Conditional)
 - Deep tier: QMD searches per extracted function — issues, PRs, changelogs. T2 annotations.
 - Not Deep: skip silently, auto-proceed
@@ -283,9 +309,9 @@ create-skill/
 - Auto-proceed
 
 **step-06-validate** (Simple Middle)
-- skills_ref.validate_schema() + validate_frontmatter()
+- `npx skill-check check --fix --format json` (schema + frontmatter + auto-fix + quality score)
 - Pass: auto-proceed. Fail: attempt auto-fix, re-validate, halt if still failing.
-- skills_ref unavailable: skip, add warning to evidence report
+- skill-check unavailable: skip automated validation, add warning to evidence report
 
 **step-07-generate-artifacts** (Simple Middle)
 - Create directories: skills/{name}/, skills/{name}/references/, forge-data/{name}/
@@ -305,12 +331,18 @@ create-skill/
 step-01  READS: forge-tier.yaml, skill-brief.yaml
          SETS:  tier, brief_data, source_location
               ↓
-step-02  READS: skills_ref ecosystem
+step-02  READS: agentskills.io registry API (ecosystem check — not skill-check CLI)
          SETS:  ecosystem_status
               ↓
 step-03  READS: source code via gh_bridge/ast_bridge
          SETS:  extraction_inventory
               ↓
+step-03b READS: source_repo via gh CLI, top_exports from extraction_inventory (Deep only)
+         CREATES: QMD temporal collection ({skill-name}-temporal)
+              ↓
+step-03c READS: doc_urls from brief_data (when present, any tier)
+         SETS:  T3 items merged into extraction_inventory
+              ↓
 step-04  READS: QMD collections (Deep only)
          SETS:  enrichment_annotations
               ↓
@@ -449,7 +481,7 @@ Low-priority: Pattern 4 could parallelize batch --batch per-brief, not primary u
 - Next Step: step-07-generate-artifacts.md
 
 **Key Design Decisions:**
-- skills_ref validation: schema + frontmatter + metadata cross-check
+- skill-check validation: `check --fix --format json` (schema + frontmatter + quality score + auto-fix + security scan)
 - Auto-fix pattern: validate → fix → re-validate (once per failure)
 - Tool unavailability: skip with warning, not halt
 - Validation failures are warnings — proceed to generation

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

@@ -2,13 +2,14 @@
 name: create-skill
 description: Compile a skill from a brief. Supports --batch for multiple briefs.
 web_bundle: true
+installed_path: '{project-root}/_bmad/skf/workflows/skillforge/create-skill'
 ---
 
 # Create Skill
 
 **Goal:** Compile a verified agent skill from a skill-brief.yaml and source code, producing an agentskills.io-compliant SKILL.md with provenance map, evidence report, and progressive disclosure references.
 
-**Your Role:** You are a skill compilation engine performing structural extraction and assembly. This workflow is mostly autonomous with two strategic confirmation gates — one after ecosystem check (if a match is found) and one after source extraction (to confirm findings before compilation). All other steps auto-proceed. Apply zero hallucination tolerance: every instruction in the output must trace to source code with a confidence tier citation.
+**Your Role:** You are a skill compilation engine performing structural extraction and assembly. This workflow is mostly autonomous with three interaction points — one after ecosystem check (if a match is found), one after source extraction (to confirm findings before compilation), and one after content quality review (when tessl produces suggestions). All other steps auto-proceed. Apply zero hallucination tolerance: every instruction in the output must trace to source code with a confidence tier citation.
 
 ## WORKFLOW ARCHITECTURE
 
@@ -45,7 +46,7 @@ web_bundle: true
 
 Load and read full config from {project-root}/_bmad/skf/config.yaml and resolve:
 
-- `project_name`, `output_folder`, `user_name`, `communication_language`, `document_output_language`
+- `project_name`, `output_folder`, `user_name`, `communication_language`, `document_output_language`, `sidecar_path`, `skills_output_folder`, `forge_data_folder`
 
 ### 2. First Step Execution
 

package/src/workflows/create-stack-skill/data/stack-skill-template.md

@@ -3,6 +3,14 @@
 ## SKILL.md Section Structure
 
 ```markdown
+---
+name: {project_name}-stack
+description: >
+  Stack skill for {project_name} — {lib_count} libraries with
+  {integration_count} integration patterns. Use when working with
+  this project's technology stack.
+---
+
 # {project_name} Stack Skill
 
 > {lib_count} libraries | {integration_count} integration patterns | Forge tier: {tier}
@@ -41,13 +49,16 @@
 - {convention_2}
 ```
 
-## context-snippet.md Format (ADR-L)
+## context-snippet.md Format (Vercel-Aligned)
 
-Two-line format per library, targeting ~30 tokens per entry:
+Indexed format targeting ~80-120 tokens per stack:
 
 ```markdown
-**{library}** ({import_count} imports): {top_3_exports}
-  → integrates with: {comma-separated integration partners}
+[{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: {1-2 most critical integration pitfalls}
 ```
 
 ## metadata.json Structure
@@ -55,10 +66,12 @@ Two-line format per library, targeting ~30 tokens per entry:
 ```json
 {
   "skill_type": "stack",
-  "skill_name": "{project}-stack",
+  "name": "{project}-stack",
   "version": "1.0.0",
-  "created": "{date}",
-  "forge_tier": "{Quick|Forge|Deep}",
+  "generation_date": "{ISO-8601}",
+  "confidence_tier": "{Quick|Forge|Deep}",
+  "source_authority": "{official|community|internal}",
+  "exports": [],
   "library_count": 0,
   "integration_count": 0,
   "libraries": ["lib1", "lib2"],

package/src/workflows/create-stack-skill/steps-c/step-01-init.md

@@ -68,10 +68,10 @@ STOP — do not proceed.
 
 Extract:
 - `forge_tier` — Quick, Forge, or Deep
-- `available_tools` — list of detected tools (gh_bridge, ast_bridge, qmd_bridge, skills_ref)
+- `available_tools` — list of detected tools (gh_bridge, ast_bridge, qmd_bridge, skill-check)
 - `project_root` — project root path
 
-Check for `tier_override` in preferences.yaml if it exists.
+**Apply tier override:** Read `{sidecar_path}/preferences.yaml`. If `tier_override` is set and is a valid tier value (Quick, Forge, or Deep), use it instead of the detected tier.
 
 ### 2. Validate Available Tools
 

package/src/workflows/create-stack-skill/steps-c/step-04-parallel-extract.md

@@ -52,6 +52,20 @@ For each confirmed dependency, extract key exports, usage patterns, and API surf
 
 ### 1. Prepare Extraction Plan
 
+**AST Tool Availability Check (Forge/Deep only):**
+
+This workflow operates on local project files and installed library packages. Remote source resolution does not apply — libraries are analyzed as they exist within the project's dependency tree.
+
+**If AST tool is unavailable at Forge/Deep tier:**
+
+⚠️ **Warn the user explicitly:** "AST tools are unavailable — extraction will use source reading (T1-low). Run [SF] Setup Forge to detect and configure AST tools for T1 confidence."
+
+Degrade to Quick tier extraction. Note the degradation reason in context for the evidence report.
+
+**Per-file AST failure handling:**
+
+If ast-grep fails on an individual file (parse error, unsupported syntax), fall back to source reading for that file only. Label the affected file's results T1-low; unaffected files retain T1. Log a warning noting which file degraded and why.
+
 For each library in `confirmed_dependencies`, determine extraction strategy based on forge tier:
 
 **Quick Tier:**

package/src/workflows/create-stack-skill/steps-c/step-06-compile-stack.md

@@ -55,7 +55,28 @@ Assemble the main SKILL.md by combining per-library extractions with the integra
 
 Load `{stackSkillTemplate}` and prepare SKILL.md section structure.
 
-### 2. Compile Integration Layer
+### 2. Generate Frontmatter
+
+The SKILL.md MUST begin with YAML frontmatter (agentskills.io compliance):
+
+```yaml
+---
+name: {project_name}-stack
+description: >
+  Stack skill for {project_name} — {lib_count} libraries with
+  {integration_count} integration patterns. Use when working with
+  this project's technology stack. NOT for: individual library usage
+  outside this project's conventions.
+---
+```
+
+**Frontmatter rules:**
+
+- `name`: lowercase alphanumeric + hyphens only, must match skill output directory name
+- `description`: non-empty, max 1024 chars, trigger-optimized for agent discovery
+- No other frontmatter fields — only `name`, `description`, `license`, `compatibility`, `metadata`, `allowed-tools` are permitted by spec
+
+### 3. Compile Integration Layer
 
 **This is the core value of the stack skill.** Compile in order:
 
@@ -75,7 +96,7 @@ Load `{stackSkillTemplate}` and prepare SKILL.md section structure.
   - Role in the stack architecture
   - How it connects to partner libraries
 
-### 3. Compile Per-Library Sections
+### 4. Compile Per-Library Sections
 
 For each confirmed library (ordered by integration connectivity, then import count):
 
@@ -85,7 +106,7 @@ For each confirmed library (ordered by integration connectivity, then import cou
 - Confidence tier label
 - Link to reference file: `./references/{library}.md`
 
-### 4. Compile Project Conventions
+### 5. Compile Project Conventions
 
 Extract project-specific conventions from the extractions:
 - Common initialization patterns
@@ -93,7 +114,7 @@ Extract project-specific conventions from the extractions:
 - Configuration conventions
 - Import organization patterns
 
-### 5. Compile Library Reference Index
+### 6. Compile Library Reference Index
 
 Create the reference index table:
 
@@ -101,7 +122,7 @@ Create the reference index table:
 |---------|---------|-------------|------------|-----------|
 | ... | ... | ... | ... | ... |
 
-### 6. Present Compiled SKILL.md Preview
+### 7. Present Compiled SKILL.md Preview
 
 "**Stack skill compilation complete. Please review:**
 
@@ -122,7 +143,7 @@ Create the reference index table:
 - Are the per-library summaries accurate?
 - Any sections to adjust before writing output?"
 
-### 7. Present MENU OPTIONS
+### 8. Present MENU OPTIONS
 
 Display: **Select:** [C] Continue to Output Generation
 
@@ -134,7 +155,7 @@ Display: **Select:** [C] Continue to Output Generation
 #### Menu Handling Logic:
 
 - IF C: Store skill_content, then load, read entire file, then execute {nextStepFile}
-- IF Any other: Process as feedback, adjust compilation, redisplay preview, then [Redisplay Menu Options](#7-present-menu-options)
+- IF Any other: Process as feedback, adjust compilation, redisplay preview, then [Redisplay Menu Options](#8-present-menu-options)
 
 ---
 

package/src/workflows/create-stack-skill/steps-c/step-07-generate-output.md

@@ -100,10 +100,13 @@ Load structure from `{stackSkillTemplate}` integrations section:
 
 Write `{skills_output_folder}/{project_name}-stack/context-snippet.md`:
 
-Use ADR-L two-line format targeting ~30 tokens per library entry:
+Use the Vercel-aligned indexed format targeting ~80-120 tokens:
 ```
-**{library}** ({import_count} imports): {top_3_exports}
-  → integrates with: {comma-separated integration partners}
+[{project_name}-stack v{version}]|root: skills/{project_name}-stack/
+|IMPORTANT: {project_name}-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: {1-2 most critical integration pitfalls}
 ```
 
 ### 6. Write metadata.json
@@ -113,10 +116,10 @@ Write `{skills_output_folder}/{project_name}-stack/metadata.json`:
 ```json
 {
   "skill_type": "stack",
-  "skill_name": "{project_name}-stack",
-  "version": "1.0.0",
-  "created": "{current_date}",
-  "forge_tier": "{tier}",
+  "name": "{project_name}-stack",
+  "version": "{primary_library_version or 1.0.0}",
+  "generation_date": "{current_date}",
+  "confidence_tier": "{tier}",
   "library_count": N,
   "integration_count": N,
   "libraries": ["lib1", "lib2"],

package/src/workflows/create-stack-skill/steps-c/step-08-validate.md

@@ -68,103 +68,104 @@ Check that all expected files exist from written_files[]:
 
 Record any missing files as **ERROR** findings.
 
-### 2. Validate SKILL.md Structure
+### 2. Check Tool Availability
+
+Run: `npx skill-check -h`
+
+- If succeeds: Use skill-check for automated validation in sections 3, 9
+- If fails: Use manual fallback paths in those sections
+
+**Important:** Do not assume availability — empirical check required.
+
+### 3. Validate SKILL.md via skill-check (if available)
+
+**If available**, run: `npx skill-check check <skill-dir> --fix --format json --no-security-scan`
+
+This validates frontmatter, description, body limits, links, formatting — and auto-fixes deterministic issues. Parse JSON for `qualityScore`, `diagnostics[]`, `fixed[]`.
+
+**If `body.max_lines` reported**, run: `npx skill-check split-body <skill-dir> --write`, then re-validate.
+
+**If unavailable**, perform manual frontmatter check:
+- [ ] Frontmatter present with `---` delimiters
+- [ ] `name` — present, non-empty, lowercase alphanumeric + hyphens, 1-64 chars, matches `{project_name}-stack`
+- [ ] `description` — present, non-empty, 1-1024 characters
+- [ ] No unknown fields — only `name`, `description`, `license`, `compatibility`, `metadata`, `allowed-tools` permitted
+
+Record frontmatter violations as **WARNING** findings. Invalid frontmatter will fail `npx skills add` and `npx skill-check check`.
+
+### 4. Validate SKILL.md Body Structure
 
 Load `{stackSkillTemplate}` and verify SKILL.md contains expected sections:
 
 - [ ] Header with project name, library count, integration count, forge tier
-- [ ] Integration Patterns section (should appear BEFORE per-library summaries)
+- [ ] Integration Patterns section (before per-library summaries)
 - [ ] Library Reference Index table
 - [ ] Per-Library Summaries section
 - [ ] Conventions section
 
 Record missing sections as **WARNING** findings.
 
-### 3. Validate metadata.json Fields
+### 5. Validate metadata.json Fields
 
 Parse metadata.json and verify required fields:
 
 - [ ] `skill_type` equals "stack"
-- [ ] `skill_name` matches `{project_name}-stack`
-- [ ] `version` is present
-- [ ] `created` is present
-- [ ] `forge_tier` matches the tier from step 01
-- [ ] `library_count` matches actual number of reference files
-- [ ] `integration_count` matches actual integration pair files
-- [ ] `libraries` array is present and non-empty
-- [ ] `confidence_distribution` object is present with T1/T1-low/T2 keys
+- [ ] `name` matches `{project_name}-stack`
+- [ ] `version` and `generation_date` present
+- [ ] `confidence_tier` matches tier from step 01
+- [ ] `library_count` matches actual reference files; `integration_count` matches pair files
+- [ ] `libraries` array present and non-empty
+- [ ] `confidence_distribution` object present with T1/T1-low/T2 keys
 
 Record mismatches as **WARNING** findings.
 
-### 4. Validate Reference File Completeness
+### 6. Validate Reference File Completeness
 
-For each confirmed library, verify `references/{library}.md` exists and contains:
-- [ ] Library name header
-- [ ] Version from manifest
-- [ ] Key Exports section
-- [ ] Usage Patterns section
+For each confirmed library, verify `references/{library}.md` contains: library name header, version from manifest, Key Exports section, Usage Patterns section.
 
-For each integration pair (if any), verify `references/integrations/{libraryA}-{libraryB}.md` exists and contains:
-- [ ] Integration pair header
-- [ ] Type classification
-- [ ] Integration Pattern section
-- [ ] Key Files section
+For each integration pair, verify `references/integrations/{libraryA}-{libraryB}.md` contains: integration pair header, type classification, Integration Pattern section, Key Files section.
 
 Record missing or incomplete files as **WARNING** findings.
 
-### 5. Validate Confidence Tier Labels
+### 7. Validate Confidence Tier Labels
 
-Scan across all output files for confidence tier coverage:
+Scan all output files for confidence tier coverage:
 
-- [ ] SKILL.md: Each per-library summary has a confidence label
-- [ ] SKILL.md: Each integration pair entry has a confidence label
-- [ ] Reference files: Each has a confidence label in its header
+- [ ] SKILL.md: each per-library summary and integration pair entry has a confidence label
+- [ ] Reference files: each has a confidence label in its header
 - [ ] metadata.json: confidence_distribution sums match library_count
 
 Record missing tier labels as **WARNING** findings.
 
-### 6. Validate context-snippet.md
+### 8. Validate context-snippet.md
 
-Verify context-snippet.md follows ADR-L two-line format:
-- [ ] Each library has an entry with import count and top exports
-- [ ] Integration partners listed on second line
-- [ ] No library from confirmed list is missing
+Verify context-snippet.md follows Vercel-aligned indexed format:
+- [ ] First line matches: `[{project}-stack v{version}]|root: skills/{project}-stack/`
+- [ ] Second line starts with `|IMPORTANT:`
+- [ ] Stack and integrations lines present
+- [ ] Approximate token count is ~80-120 tokens
 
 Record format violations as **WARNING** findings.
 
-### 7. Display Validation Results
-
-**If all checks pass:**
-
-"**Validation complete — all checks passed.**
+### 9. Security Scan (if skill-check available)
 
-- **Files:** {file_count}/{file_count} present
-- **SKILL.md:** Structure valid
-- **metadata.json:** All required fields present
-- **References:** {lib_count} library + {pair_count} integration files verified
-- **Confidence tiers:** Complete coverage
+Run: `npx skill-check check <skill-dir> --format json` (security scan enabled by default).
 
-**Proceeding to summary report...**"
+Record security findings as advisory **WARNING** findings — they do not block the report.
 
-**If warnings found:**
+**If unavailable:** Skip with note in validation results.
 
-"**Validation complete with {warning_count} finding(s).**
+### 10. Display Validation Results
 
-**Findings:**
-{For each finding:}
-- ⚠ {severity}: {description} — {file_path}
+**If all checks pass:**
 
-**Summary:**
-- **Files:** {present_count}/{expected_count} present
-- **Warnings:** {warning_count}
-- **Errors:** {error_count}
+"**Validation complete — all checks passed.** Files: {count}/{count} present. SKILL.md structure valid. metadata.json fields verified. {lib_count} library + {pair_count} integration files verified. Confidence tiers: complete coverage. **Proceeding to summary report...**"
 
-{If errors (missing files):}
-**Note:** Missing files may indicate a write failure in step 07. Review evidence-report.md for details.
+**If warnings found:**
 
-**Proceeding to summary report...**"
+"**Validation complete with {warning_count} finding(s).** Findings: {list each: severity, description, file_path}. Files: {present}/{expected} present. Warnings: {count}. Errors: {count}. {If errors: Note missing files may indicate a write failure in step 07.} **Proceeding to summary report...**"
 
-### 8. Auto-Proceed to Next Step
+### 11. Auto-Proceed to Next Step
 
 Load, read the full file and then execute `{nextStepFile}`.
 
@@ -174,20 +175,17 @@ Load, read the full file and then execute `{nextStepFile}`.
 
 ### ✅ SUCCESS:
 
-- All expected files checked for existence
-- SKILL.md validated against template structure
-- metadata.json fields verified
-- Reference files checked for completeness
-- Confidence tier coverage verified
-- Validation results displayed with specific findings
+- All expected files checked; `npx skill-check check --fix` executed if available (or manual fallback)
+- Quality score captured; auto-fix and split-body applied as needed; security scan executed (or skipped with note)
+- SKILL.md validated against template; metadata.json fields verified; reference files checked
+- Confidence tier coverage verified; validation results displayed with specific findings
 - Advisory mode: always proceeded to report
 
 ### ❌ SYSTEM FAILURE:
 
-- Modifying any output files during validation
-- Halting the workflow on validation warnings
-- Not checking all expected files
-- Reporting vague findings without file paths
-- Skipping the confidence tier check
+- Modifying output files during validation (except via skill-check --fix)
+- Halting on validation warnings; not checking all expected files
+- Reporting vague findings without file paths; skipping confidence tier check
+- Not recording quality score when skill-check is available
 
-**Master Rule:** Validate everything, modify nothing. Advisory findings — always proceed to report.
+**Master Rule:** Validate everything, fix what's deterministic via skill-check, scan for security issues. Advisory findings — always proceed to report.