bmad-module-skill-forge 0.3.0 → 0.5.0

package/src/workflows/create-skill/data/extraction-patterns-tracing.md

@@ -0,0 +1,110 @@
+# Extraction Patterns: Tracing and File-Level Extraction
+
+This file covers re-export tracing protocols and script/asset file-level extraction patterns. For core tier strategies and AST extraction protocol, see `extraction-patterns.md`.
+
+---
+
+## Re-Export Tracing
+
+After initial AST extraction, some top-level exports may resolve to **module imports** rather than direct function definitions. This is common in Python libraries that use `__init__.py` re-exports for a clean public API.
+
+**Detection heuristic:** For each top-level export from `__init__.py` (or equivalent entry point), check if the import path resolves to a directory (contains `__init__.py`) rather than a `.py` file with a matching `def` or `class`. If the initial AST scan found no function/class definition for a known public export, it is likely a module re-export.
+
+**Tracing protocol:**
+
+1. Read the entry point file (e.g., `{package}/__init__.py`) and extract all `from .X import Y` statements
+2. For each import where Y was NOT found by the initial AST scan:
+   - Check if the import path resolves to a directory (e.g., `{package}/api/v1/delete/` exists with `__init__.py`)
+   - If directory: read its `__init__.py` to find the actual re-exported symbol
+   - **Handle aliases:** Check for `from .module import A as B` patterns in the intermediate `__init__.py`. If the parent imports `B`, trace through to `A` in `.module`. If the parent imports `A` but the `__init__.py` only exports it as `B` (via `from .module import A as B`), match by original name `A` and note the alias
+   - Trace the symbol to its definition file and run AST extraction on that file
+3. Cite the actual definition location: `[AST:{definition_file}:L{line}]`
+
+**Examples:**
+
+```python
+# Module re-export — follow required
+from .api.v1.delete import delete    # delete/ is a directory → read delete/__init__.py
+
+# Direct function import — no follow needed
+from .api.v1.add.add import add      # add.py exists with def add()
+
+# Aliased re-export — follow through alias
+# In cognee/api/v1/visualize/__init__.py:
+#   from .start_visualization_server import visualization_server
+# In cognee/__init__.py:
+#   from .api.v1.visualize import start_visualization_server
+# → Match start_visualization_server against both definition names AND alias names
+#   in the intermediate __init__.py to resolve the chain
+```
+
+**Unresolvable imports:** If the import statement is a star-import (`from .X import *`) or a conditional import (`try`/`except`), the symbol cannot be reliably traced via this protocol. Record it with `[SRC:{package}/__init__.py:L{line}]` (T1-low) and a note: "star/conditional import — manual trace required."
+
+**Scope limit:** Only trace re-exports for symbols listed in the top-level entry point's public API. Do not recursively trace beyond one level of `__init__.py` indirection. If a re-export cannot be resolved after one level, record it with a `[SRC:{package}/__init__.py:L{line}]` citation (T1-low) from the import statement itself.
+
+**Other languages:** JS/TS barrel files (`index.ts` with `export { X } from './module'`) follow the same principle — trace the re-export to the definition file. Rust `pub use` and Go package-level re-exports are less common but follow the same heuristic when encountered.
+
+---
+
+## Script/Asset Extraction Patterns
+
+Scripts and assets are file-level artifacts, not code exports. They follow the **file-copy extraction method** — detected in source, copied with provenance citations.
+
+### Detection Heuristics
+
+**Script directories:** `scripts/`, `bin/`, `tools/`, `cli/`
+**Asset directories:** `assets/`, `templates/`, `schemas/`, `configs/`, `examples/`
+
+**Script file signals:**
+
+| Signal | Strength | Pattern |
+|--------|----------|---------|
+| Entry point declaration | Strong | `package.json` `bin` field, Cargo.toml `[[bin]]`, pyproject.toml `[project.scripts]` |
+| Shebang + executable | Strong | `#!/bin/bash`, `#!/usr/bin/env python`, `#!/usr/bin/env node` |
+| CLI argument parser | Moderate | `argparse`, `yargs`, `commander`, `cobra`, `clap` imports in file |
+| Directory convention | Moderate | File in `scripts/`, `bin/`, `tools/` directory |
+| CI/CD reference | Moderate | Script referenced in `.github/workflows/*.yml` |
+
+**Asset file signals:**
+
+| Signal | Strength | Pattern |
+|--------|----------|---------|
+| JSON Schema | Strong | `*.schema.json`, file contains `"$schema"` key |
+| Config template | Strong | `*.example`, `*.template.*`, `*.sample` extension |
+| Official example | Moderate | File in `examples/` directory, referenced in README |
+| OpenAPI/GraphQL | Moderate | `openapi.json`, `*.graphql`, `swagger.yaml` |
+| Design tokens | Weak | `tokens.json`, `theme.json` in `assets/` |
+
+### Inclusion Rules
+
+- Only include files within brief's `scope.include` patterns (or auto-detected directories)
+- Exclude binary files (check extension: `.so`, `.dll`, `.jar`, `.wasm`, `.exe`)
+- Exclude generated files (`dist/`, `build/`, `.webpack/` output)
+- Exclude vendored/third-party files
+- Flag files >500 lines for user confirmation (may be too large for skill package)
+- If `scripts_intent: "none"` or `assets_intent: "none"` in brief, skip that category
+
+### Provenance and Hashing
+
+Each extracted file receives:
+- Citation: `[SRC:{source_path}:L1]` (T1-low — file verified to exist but content not AST-analyzed)
+- Content hash: SHA-256 of file content (for drift detection in audit-skill)
+- Extraction method: `"file-copy"` (distinct from `"ast_bridge"` for code exports)
+
+### Inventory Structure
+
+**Script inventory entry:**
+- `name`: filename (e.g., `validate-config.sh`)
+- `source_file`: path relative to source root
+- `purpose`: extracted from file header comments or README reference (if none found, use filename)
+- `language`: detected from extension or shebang
+- `content_hash`: SHA-256
+- `confidence`: T1-low
+
+**Asset inventory entry:**
+- `name`: filename (e.g., `config-schema.json`)
+- `source_file`: path relative to source root
+- `purpose`: extracted from file header or schema `title`/`description` field
+- `type`: `template`, `schema`, `config`, `example`
+- `content_hash`: SHA-256
+- `confidence`: T1-low

package/src/workflows/create-skill/data/extraction-patterns.md

@@ -26,13 +26,16 @@ Source reading via gh_bridge — infer exports from file structure and content.
 
 ## Forge Tier (AST Available)
 
-Structural extraction via ast_bridge — verified exports with line-level citations.
+Structural extraction via ast-grep — verified exports with line-level citations.
+
+> **Note:** `ast_bridge.*` and `qmd_bridge.*` references below are **conceptual interfaces**, not callable functions. They describe the operation to perform. Use ast-grep (MCP tool or CLI) for `ast_bridge.*` operations and QMD (MCP tool or CLI) for `qmd_bridge.*` operations. See the AST Extraction Protocol section below and the TOOL/SUBPROCESS FALLBACK rule for dispatch details.
 
 ### Strategy
+
 1. Detect language from brief or file extensions
-2. `ast_bridge.scan_definitions(path, language)` — extract all exports
+2. Use ast-grep to extract all exports from `path` for the given `language` (scan definitions)
 3. For each export: function name, full signature, parameter types, return type, line number
-4. `ast_bridge.detect_co_imports(path, libraries[])` — find integration points
+4. Use ast-grep to detect co-imported symbols in `path` for the given `libraries[]`
 5. Build extraction rules YAML for reproducibility
 
 ### Confidence
@@ -130,7 +133,8 @@ When MCP tools are unavailable or the repo exceeds 500 files in scope, use `--js
 # Patterns are matched against the full file path as emitted by ast-grep.
 # Ensure paths are relative to the same root as the patterns (strip ./ prefix if needed).
 ast-grep -p '{pattern}' -l {language} --json=stream {path} | python3 -c "
-import sys, json, fnmatch
+import sys, json, fnmatch, signal
+signal.signal(signal.SIGPIPE, signal.SIG_DFL)
 
 EXCLUDES = {exclude_patterns}
 
@@ -230,82 +234,9 @@ constraints:
     regex: '^[A-Z]'
 ```
 
-### Re-Export Tracing
-
-After initial AST extraction, some top-level exports may resolve to **module imports** rather than direct function definitions. This is common in Python libraries that use `__init__.py` re-exports for a clean public API.
-
-**Detection heuristic:** For each top-level export from `__init__.py` (or equivalent entry point), check if the import path resolves to a directory (contains `__init__.py`) rather than a `.py` file with a matching `def` or `class`. If the initial AST scan found no function/class definition for a known public export, it is likely a module re-export.
-
-**Tracing protocol:**
-
-1. Read the entry point file (e.g., `{package}/__init__.py`) and extract all `from .X import Y` statements
-2. For each import where Y was NOT found by the initial AST scan:
-   - Check if the import path resolves to a directory (e.g., `{package}/api/v1/delete/` exists with `__init__.py`)
-   - If directory: read its `__init__.py` to find the actual re-exported symbol
-   - Trace the symbol to its definition file and run AST extraction on that file
-3. Cite the actual definition location: `[AST:{definition_file}:L{line}]`
-
-**Examples:**
-
-```python
-# Module re-export — follow required
-from .api.v1.delete import delete    # delete/ is a directory → read delete/__init__.py
-
-# Direct function import — no follow needed
-from .api.v1.add.add import add      # add.py exists with def add()
-```
-
-**Unresolvable imports:** If the import statement is a star-import (`from .X import *`) or a conditional import (`try`/`except`), the symbol cannot be reliably traced via this protocol. Record it with `[SRC:{package}/__init__.py:L{line}]` (T1-low) and a note: "star/conditional import — manual trace required."
-
-**Scope limit:** Only trace re-exports for symbols listed in the top-level entry point's public API. Do not recursively trace beyond one level of `__init__.py` indirection. If a re-export cannot be resolved after one level, record it with a `[SRC:{package}/__init__.py:L{line}]` citation (T1-low) from the import statement itself.
-
-**Other languages:** JS/TS barrel files (`index.ts` with `export { X } from './module'`) follow the same principle — trace the re-export to the definition file. Rust `pub use` and Go package-level re-exports are less common but follow the same heuristic when encountered.
-
----
-
-## Tier Degradation Rules
-
-### Remote Source at Forge/Deep Tier
-
-When `source_repo` is a remote URL (GitHub URL or owner/repo format) and the tier is Forge or Deep:
-
-- **ast-grep requires local files** — it cannot operate on remote URLs
-
-**Ephemeral clone strategy (preferred):**
-
-1. Check `git` availability (`git --version`). `git` is effectively guaranteed at Deep tier (via `gh` dependency) but NOT guaranteed at Forge tier.
-2. If `git` is available: perform an ephemeral shallow clone to a system temp path (`{system_temp}/skf-ephemeral-{skill-name}-{timestamp}/`).
-3. For create-skill: use `--depth 1 --single-branch --filter=blob:none`; if `include_patterns` are specified, apply mode selection: if `exclude_patterns` are absent, use cone mode (convert include_patterns to directory roots; use `--skip-checks` for individual file paths); if `exclude_patterns` are present, use `--no-cone` mode (pass gitignore-style patterns with `!`-prefixed excludes — includes first, then negations). See source-resolution-protocols.md for the full conversion rules.
-4. For update-skill: use sparse-checkout with `--skip-checks` scoped to the changed files from the change manifest only (file paths require `--skip-checks`). No `--branch` flag — uses the remote default branch (must match the branch used during original create-skill run).
-5. If clone succeeds: use the local clone path for AST extraction. All results are T1 with `[AST:...]` citations.
-6. Cleanup: delete the temp directory after extraction inventory is built and all data is in context. The clone never persists beyond the extraction step.
-
-**Fallback (clone fails or `git` unavailable):**
-
-- The extraction step MUST warn the user explicitly before degrading
-- **create-skill:** Warning must include actionable guidance — clone locally and update `source_repo` in the brief to the local path
-- **update-skill:** Warning must include actionable guidance — clone locally, re-run [CS] Create Skill with the local path to regenerate provenance data, then re-run the update
-- Extraction proceeds using Quick tier strategy (source reading via gh_bridge)
-- All results labeled T1-low with `[SRC:...]` citations
-- The degradation reason is recorded in the evidence report
-
-Silent degradation is **forbidden**. The user must always know when AST extraction was skipped and why.
-
-### AST Tool Unavailable at Forge/Deep Tier
-
-When the tier is Forge or Deep but ast-grep is not functional:
-
-- The extraction step MUST warn the user explicitly before degrading
-- Warning must include actionable guidance: run [SF] Setup Forge to detect tools
-- Extraction proceeds using Quick tier strategy
-- All results labeled T1-low
-- The degradation reason is recorded in the evidence report
-
-### Per-File AST Failure
+### Re-Export Tracing and Script/Asset Extraction
 
-When ast-grep fails on an individual file (parse error, unsupported syntax):
+See `extraction-patterns-tracing.md` for:
+- **Re-export tracing protocol** — resolving module imports through `__init__.py`, barrel files, `pub use`
+- **Script/asset extraction patterns** — detection heuristics, inclusion rules, provenance, inventory structure
 
-- Fall back to source reading for **that file only**
-- Other files continue with AST extraction
-- The affected file's results are labeled T1-low; unaffected files retain T1
-- Log a warning noting which file degraded and why

package/src/workflows/create-skill/data/skill-sections.md

@@ -17,8 +17,8 @@ description: >
 
 **Frontmatter rules (agentskills.io specification):**
 
-- `name`: 1-64 characters, lowercase alphanumeric + hyphens only, must match parent directory name
-- `description`: 1-1024 characters, trigger-optimized for agent matching
+- `name`: 1-64 characters, lowercase alphanumeric + hyphens only, must match parent directory name. Prefer gerund form (`processing-pdfs`, `analyzing-spreadsheets`) for clarity; noun phrases and action-oriented forms are acceptable alternatives.
+- `description`: 1-1024 characters, trigger-optimized for agent matching. MUST use third-person voice ("Processes..." not "I can..." or "You can...").
 - Only 6 fields permitted: `name`, `description`, `license`, `compatibility`, `metadata`, `allowed-tools`
 - `version` and `author` belong in metadata.json, NOT in frontmatter
 
@@ -38,6 +38,7 @@ SKILL.md uses a two-tier structure to ensure actionable content survives `split-
 | 5 | **Key Types** | ~20 lines | Most important enum/type values inline |
 | 6 | **Architecture at a Glance** | ~10 lines | Bullet list of subsystem categories |
 | 7 | **CLI** | ~10 lines | Basic CLI commands (skip if no CLI) |
+| 7b | **Scripts & Assets** | ~10 lines | Manifest of included scripts and assets (skip if none detected) |
 | 8 | **Manual Sections** | ~5 lines | `<!-- [MANUAL] -->` markers for update-skill |
 
 #### Tier 2 — Reference-Eligible (extracted by split-body into references/)
@@ -56,6 +57,7 @@ SKILL.md uses a two-tier structure to ensure actionable content survives `split-
 - After split-body, SKILL.md retains all Tier 1 content — actionable without loading references
 - An agent loading only SKILL.md (no references) must get enough to act
 - **Section 4b (Migration & Deprecation Warnings)** is conditional: only emitted for Deep tier when T2-future annotations exist. Quick/Forge tiers and Deep tiers without T2-future annotations omit it entirely (no empty section). Parsers and validators must treat this section as optional.
+- **Section 7b (Scripts & Assets)** is conditional: only emitted when `scripts_inventory` or `assets_inventory` is non-empty. Omitted entirely when no scripts or assets are detected. Parsers and validators must treat this section as optional.
 
 ### Provenance Citation Format
 
@@ -121,11 +123,14 @@ Indexed pipe-delimited format for CLAUDE.md managed section (~80-120 tokens per
   "confidence_tier": "{Quick|Forge|Deep}",
   "spec_version": "1.3",
   "generation_date": "{ISO-8601}",
+  "description": "{SKILL.md frontmatter description}",
+  "language": "{primary-source-language}",
+  "ast_node_count": "{number-or-omitted-if-no-ast}",
   "exports": [],
   "tool_versions": {
     "ast_grep": "{version-or-null}",
     "qmd": "{version-or-null}",
-    "skf": "1.0.0"
+    "skf": "{skf_version}"
   },
   "stats": {
     "exports_documented": 0,
@@ -136,8 +141,16 @@ Indexed pipe-delimited format for CLAUDE.md managed section (~80-120 tokens per
     "total_coverage": 0.0,
     "confidence_t1": 0,
     "confidence_t2": 0,
-    "confidence_t3": 0
+    "confidence_t3": 0,
+    "scripts_count": 0,
+    "assets_count": 0
   },
+  "scripts": [
+    { "file": "scripts/{name}", "purpose": "{description}", "source_file": "{source-path}", "confidence": "T1-low" }
+  ],
+  "assets": [
+    { "file": "assets/{name}", "purpose": "{description}", "source_file": "{source-path}", "confidence": "T1-low" }
+  ],
   "dependencies": [],
   "compatibility": "{semver-range}"
 }
@@ -163,6 +176,7 @@ Each reference file includes:
 - Complete usage examples
 - Related functions cross-references
 - Temporal annotations (Deep tier: T2-past, T2-future)
+- **Table of contents** (required for files exceeding 100 lines) — a `## Contents` section at the top listing all sub-sections for agent discoverability
 
 ---
 
@@ -186,10 +200,22 @@ Each reference file includes:
       "extraction_method": "ast_bridge.scan_definitions",
       "ast_node_type": "export_function_declaration"
     }
+  ],
+  "file_entries": [
+    {
+      "file_name": "scripts/{name}",
+      "file_type": "script",
+      "source_file": "{source-path}",
+      "confidence": "T1-low",
+      "extraction_method": "file-copy",
+      "content_hash": "sha256:{hash}"
+    }
   ]
 }
 ```
 
+`scripts` and `assets` arrays in metadata.json are optional — omit entirely (not empty arrays) when no scripts/assets exist. `file_entries` in provenance-map.json is optional — omit when no scripts/assets exist.
+
 ---
 
 ## evidence-report.md Structure
@@ -204,7 +230,7 @@ Each reference file includes:
 ## Tool Versions
 - ast-grep: {version}
 - QMD: {version}
-- SKF: 1.0.0
+- SKF: {skf_version}
 
 ## Extraction Summary
 - Files scanned: {count}

package/src/workflows/create-skill/data/source-resolution-protocols.md

@@ -90,9 +90,17 @@ If `source_repo` is a remote URL (GitHub URL or owner/repo format) AND tier is F
 
    **Note:** `--no-cone` mode is slower than cone mode for very large repositories but eliminates downloading excluded blobs entirely.
 
+   **Always-included root files:**
+
+   Regardless of `include_patterns`, always add these root-level version/manifest files to the sparse-checkout pattern list. These are needed for version reconciliation and must not require a fallback to `gh api`:
+
+   `pyproject.toml`, `package.json`, `Cargo.toml`, `go.mod`, `setup.py`, `setup.cfg`, `VERSION`
+
+   In cone mode, always use the `--skip-checks` command form when adding these files — even if `include_patterns` resolved to only directory roots (which would normally use the form without `--skip-checks`). The command becomes: `git -C {temp_path} sparse-checkout set --skip-checks {directory_roots} pyproject.toml package.json Cargo.toml go.mod setup.py setup.cfg VERSION`. In no-cone mode, list them as explicit include patterns before any negation patterns. Do not flag them as extraneous inclusions during post-checkout filtering.
+
    **Post-checkout filtering:**
 
-   After checkout, apply the original glob `include_patterns` as file-level filters when building the extraction file list — sparse-checkout gets the right directories, glob filtering narrows to the exact files. When `--no-cone` mode was used, most exclude filtering is already done at the git level, but apply `exclude_patterns` as a final pass to catch any edge cases where gitignore pattern matching diverges from the brief's glob semantics.
+   After checkout, apply the original glob `include_patterns` as file-level filters when building the extraction file list — sparse-checkout gets the right directories, glob filtering narrows to the exact files. When `--no-cone` mode was used, most exclude filtering is already done at the git level, but apply `exclude_patterns` as a final pass to catch any edge cases where gitignore pattern matching diverges from the brief's glob semantics. Always-included root files (see above) are exempt from post-checkout filtering.
 
 3. **If clone succeeds:** Update the working source path to `{temp_path}` for all subsequent AST operations in this step. Proceed with the **Forge/Deep Tier** extraction strategy below. Mark `ephemeral_clone_active = true` for cleanup.
 

package/src/workflows/create-skill/data/tier-degradation-rules.md

@@ -0,0 +1,46 @@
+# Tier Degradation Rules
+
+## Remote Source at Forge/Deep Tier
+
+When `source_repo` is a remote URL (GitHub URL or owner/repo format) and the tier is Forge or Deep:
+
+- **ast-grep requires local files** — it cannot operate on remote URLs
+
+**Ephemeral clone strategy (preferred):**
+
+1. Check `git` availability (`git --version`). `git` is effectively guaranteed at Deep tier (via `gh` dependency) but NOT guaranteed at Forge tier.
+2. If `git` is available: perform an ephemeral shallow clone to a system temp path (`{system_temp}/skf-ephemeral-{skill-name}-{timestamp}/`).
+3. For create-skill: use `--depth 1 --single-branch --filter=blob:none`; if `include_patterns` are specified, apply mode selection: if `exclude_patterns` are absent, use cone mode (convert include_patterns to directory roots; use `--skip-checks` for individual file paths); if `exclude_patterns` are present, use `--no-cone` mode (pass gitignore-style patterns with `!`-prefixed excludes — includes first, then negations). See source-resolution-protocols.md for the full conversion rules.
+4. For update-skill: use sparse-checkout with `--skip-checks` scoped to the changed files from the change manifest only (file paths require `--skip-checks`). No `--branch` flag — uses the remote default branch (must match the branch used during original create-skill run).
+5. If clone succeeds: use the local clone path for AST extraction. All results are T1 with `[AST:...]` citations.
+6. Cleanup: delete the temp directory after extraction inventory is built and all data is in context. The clone never persists beyond the extraction step.
+
+**Fallback (clone fails or `git` unavailable):**
+
+- The extraction step MUST warn the user explicitly before degrading
+- **create-skill:** Warning must include actionable guidance — clone locally and update `source_repo` in the brief to the local path
+- **update-skill:** Warning must include actionable guidance — clone locally, re-run [CS] Create Skill with the local path to regenerate provenance data, then re-run the update
+- Extraction proceeds using Quick tier strategy (source reading via gh_bridge)
+- All results labeled T1-low with `[SRC:...]` citations
+- The degradation reason is recorded in the evidence report
+
+Silent degradation is **forbidden**. The user must always know when AST extraction was skipped and why.
+
+## AST Tool Unavailable at Forge/Deep Tier
+
+When the tier is Forge or Deep but ast-grep is not functional:
+
+- The extraction step MUST warn the user explicitly before degrading
+- Warning must include actionable guidance: run [SF] Setup Forge to detect tools
+- Extraction proceeds using Quick tier strategy
+- All results labeled T1-low
+- The degradation reason is recorded in the evidence report
+
+## Per-File AST Failure
+
+When ast-grep fails on an individual file (parse error, unsupported syntax):
+
+- Fall back to source reading for **that file only**
+- Other files continue with AST extraction
+- The affected file's results are labeled T1-low; unaffected files retain T1
+- Log a warning noting which file degraded and why

package/src/workflows/create-skill/steps-c/step-03-extract.md

@@ -3,6 +3,8 @@ name: 'step-03-extract'
 description: 'Tier-dependent source code extraction — AST or source reading for exports, signatures, and types'
 nextStepFile: './step-03b-fetch-temporal.md'
 extractionPatternsData: '../data/extraction-patterns.md'
+extractionPatternsTracingData: '../data/extraction-patterns-tracing.md'
+tierDegradationRulesData: '../data/tier-degradation-rules.md'
 sourceResolutionData: '../data/source-resolution-protocols.md'
 ---
 
@@ -104,7 +106,7 @@ Load `{sourceResolutionData}` completely. Follow the **Remote Source Resolution*
 5. Build extraction rules YAML data for reproducibility
 6. Confidence: All results T1 — `[AST:{file}:L{line}]`
 
-**If AST tool is unavailable at Forge/Deep tier:**
+**If AST tool is unavailable at Forge/Deep tier** (see `{tierDegradationRulesData}` for full rules):
 
 ⚠️ **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."
 
@@ -117,7 +119,7 @@ Degrade to Quick tier extraction. Note the degradation reason in context for the
 
 **Re-export tracing (Forge/Deep only):**
 
-After the initial AST scan, check for public exports from the entry point (`__init__.py`, `index.ts`, `lib.rs`) that were NOT found by AST extraction. These are likely module-level re-exports. Follow the **Re-Export Tracing** protocol in `{extractionPatternsData}` to resolve them to their actual definition files. This ensures module re-export patterns (common in Python libraries with clean public APIs) do not create gaps in the extraction inventory.
+After the initial AST scan, check for public exports from the entry point (`__init__.py`, `index.ts`, `lib.rs`) that were NOT found by AST extraction. These are likely module-level re-exports. Follow the **Re-Export Tracing** protocol in `{extractionPatternsTracingData}` to resolve them to their actual definition files. This ensures module re-export patterns (common in Python libraries with clean public APIs) do not create gaps in the extraction inventory.
 
 ### 4b. Validate Exports Against Package Entry Point
 
@@ -134,6 +136,20 @@ Use the entry point as the authoritative source for `metadata.json`'s `exports[]
 
 **If entry point is missing or unreadable:** Skip validation with a warning. Use the AST-extracted list as-is.
 
+### 4c. Detect and Inventory Scripts/Assets
+
+**If `scripts_intent: "none"` AND `assets_intent: "none"` in brief:** Skip this section.
+
+After export extraction, scan the source for scripts and assets using the detection patterns in `{extractionPatternsTracingData}`:
+
+1. Scan source tree for directories/files matching detection heuristics (scripts/, bin/, tools/, cli/ for scripts; assets/, templates/, schemas/, configs/, examples/ for assets)
+2. For each candidate: verify file exists, check size (flag if >500 lines for user confirmation), exclude binary files
+3. Compute SHA-256 content hash for each included file
+4. Extract purpose from file header comments, shebang, README references, or schema `title`/`description` fields. If no purpose found, use filename.
+5. Record: file_path, purpose, source_path, language (for scripts), type (for assets), content_hash, confidence (T1-low)
+
+Add results to `scripts_inventory[]` and `assets_inventory[]` alongside the existing export inventory.
+
 ### 5. Build Extraction Inventory
 
 Compile all extracted data into a structured inventory:
@@ -154,6 +170,10 @@ Compile all extracted data into a structured inventory:
 - Confidence breakdown (T1 count, T1-low count)
 - `top_exports[]` — sorted list of the top 10-20 public API function names by prominence (import frequency or documentation position). This named field is consumed by step-03b for targeted temporal fetching and cache fingerprinting.
 
+**Script/asset counts (when detected):**
+- `scripts_found`: count of scripts detected
+- `assets_found`: count of assets detected
+
 **Co-import patterns (Forge/Deep only):**
 - Libraries commonly imported alongside extracted exports
 - Integration point suggestions
@@ -169,6 +189,8 @@ Display the extraction findings for user confirmation:
 **Confidence:** {t1_count} T1 (AST-verified), {t1_low_count} T1-low (source reading)
 **Tier used:** {tier}
 **Co-import patterns:** {pattern_count} detected
+{if scripts_found > 0: **Scripts detected:** {scripts_found}}
+{if assets_found > 0: **Assets detected:** {assets_found}}
 
 **Top exports:**
 {list top 10 exports with signatures}

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

@@ -61,7 +61,7 @@ Load `{skillSectionsData}` and `{assemblyRulesData}` completely. These define th
 
 ### 2. Build SKILL.md Content
 
-Assemble each section in order using the assembly rules data file (`{assemblyRulesData}`). The data file specifies frontmatter format, Tier 1 section details (Sections 1-8), Tier 2 section details (Sections 9-11), and assembly ordering rules. Follow it exactly.
+Assemble each section in order using the assembly rules data file (`{assemblyRulesData}`). The data file specifies frontmatter format, Tier 1 section details (Sections 1-8, including conditional Section 7b for scripts/assets), Tier 2 section details (Sections 9-11), and assembly ordering rules. Follow it exactly. Assemble Section 7b (Scripts & Assets) only if `scripts_inventory` or `assets_inventory` is non-empty.
 
 ### 3. Build context-snippet.md Content
 
@@ -97,7 +97,11 @@ Following the structure from the skill-sections data file:
   - `exports_total`: `exports_public_api` + `exports_internal`
   - `public_api_coverage`: `exports_documented / exports_public_api` (1.0 when all public API exports are documented; `null` if `exports_public_api` is 0)
   - `total_coverage`: `exports_documented / exports_total` (may be low for large codebases — this is expected; `null` if `exports_total` is 0)
-- Set `tool_versions` based on tier and available tools
+- Set `description` from the SKILL.md frontmatter `description` field (already assembled in section 2)
+- Set `language` from source analysis (e.g., `"typescript"`, `"python"`) — use the primary language of the entry point file
+- Set `ast_node_count` from extraction stats if ast-grep was used (Forge/Deep tier), otherwise omit
+- Set `tool_versions` based on tier and available tools. Resolve `{skf_version}` from the SKF module's `package.json` `version` field (run `node -p "require('./node_modules/bmad-module-skill-forge/package.json').version"` or read the installed module's `package.json`). If unresolvable, fall back to `git describe --tags --abbrev=0` in the SKF module root. Never hardcode the version.
+- If `scripts_inventory` is non-empty, populate `scripts[]` array and set `stats.scripts_count`. If `assets_inventory` is non-empty, populate `assets[]` array and set `stats.assets_count`. Omit these fields entirely when inventories are empty.
 
 ### 5. Build references/ Content
 
@@ -111,11 +115,11 @@ Group functions logically by module, file, or functional area.
 
 ### 6. Build provenance-map.json Content
 
-One entry per extracted export: export_name, export_type, params[] (typed strings), return_type, source_file, source_line, confidence tier (T1/T1-low/T2), extraction_method, ast_node_type. See `{skillSectionsData}` for full schema.
+One entry per extracted export: export_name, export_type, params[] (typed strings), return_type, source_file, source_line, confidence tier (T1/T1-low/T2), extraction_method, ast_node_type. If `scripts_inventory` or `assets_inventory` is non-empty, add `file_entries[]` with file_name, file_type, source_file, content_hash, confidence, extraction_method. See `{skillSectionsData}` for full schema.
 
 ### 7. Build evidence-report.md Content
 
-Compilation audit trail: generation date, forge tier, source info, tool versions, extraction summary (files/exports/confidence), validation results (populated in step-06), warnings. See `{skillSectionsData}` for full template.
+Compilation audit trail: generation date, forge tier, source info, tool versions, extraction summary (files/exports/confidence), validation results (populated in step-06), warnings. See `{skillSectionsData}` for full template. Use the same `{skf_version}` value resolved in section 4 when populating the Tool Versions block.
 
 ### 8. Menu Handling Logic
 

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

@@ -40,6 +40,7 @@ To validate the compiled SKILL.md content against the agentskills.io specificati
 - 💾 Validation results are added to evidence-report content in context
 - 📖 Auto-fix pattern: validate → fix → re-validate (once)
 - 🚫 Maximum one auto-fix attempt per validation failure
+- ⏸️ **Conditional interaction:** If tessl returns suggestions (section 6b), halt for user input. Otherwise auto-proceed. This is a conditional gate step, not a pure auto-proceed step.
 
 ## CONTEXT BOUNDARIES:
 
@@ -73,6 +74,8 @@ This performs frontmatter validation, description quality checks, body limit enf
 
 **Parse the JSON output** for: `qualityScore` (0-100), `diagnostics[]` (remaining issues), `fixed[]` (auto-corrected issues).
 
+**Context sync after --fix:** If `fixed[]` is non-empty (i.e., `--fix` modified files on disk), re-read the modified SKILL.md to update the in-context copy. Verify the re-read content matches expectations before proceeding. This prevents silent divergence between the in-context SKILL.md and the on-disk version that step-07 will use for artifact generation.
+
 **Note:** `skill-check` may return non-zero exit code even when `errorCount` is 0. Always rely on parsed JSON, not the shell exit code.
 
 - **Score ≥ 70:** Record "Schema: PASS (score: {score}/100)" in evidence-report
@@ -98,10 +101,16 @@ If fails: auto-fix (deterministic), re-validate once, record result. If passes:
 
 **If step 2 reported `body.max_lines` failure:**
 
+**Preferred approach — selective split:** Rather than a full `split-body`, identify which Tier 2 section(s) are largest (usually `## Full API Reference`) and manually extract only those to `references/`. Keep all Tier 1 content and smaller Tier 2 sections inline. This preserves agent accuracy — inline passive context achieves 100% task accuracy vs 79% for on-demand retrieval (per Vercel research). See `knowledge/split-body-strategy.md` for the full rationale.
+
+**If manual selective split is not feasible**, fall back to the automated full split:
+
 ```bash
 npx skill-check split-body <staging-skill-dir> --write
 ```
 
+After any split (selective or full), verify that context snippet section anchors (`#quick-start`, `#key-types`) still resolve to headings in SKILL.md.
+
 Then re-validate: `npx skill-check check <staging-skill-dir> --format json --no-security-scan`
 
 **If skill-check unavailable or no body size issue:** Skip.
@@ -120,15 +129,7 @@ Record any security warnings in evidence-report. Security findings are advisory
 
 **If security scan fails due to missing SNYK_TOKEN:**
 
-Display actionable guidance:
-
-"Security scan requires a Snyk API token. **Important:** The Snyk API requires an Enterprise plan ([authentication docs](https://docs.snyk.io/snyk-api/authentication-for-api)). To enable:
-1. Obtain a Snyk Enterprise account with API access
-2. Get your API token from Account Settings → API Token
-3. Set `SNYK_TOKEN=your-token` in your environment or `.env`
-4. Re-run [SF] Setup Forge to update tool detection, then re-run [CS] Create Skill
-
-If you don't have an Enterprise account, use `--no-security-scan` flag in skill-check to skip, or `--security-scan-runner pipx|uvx|local` to control the execution method. Security scanning is optional and does not affect tier level or block skill compilation."
+Display: "Security scan requires a Snyk Enterprise API token ([docs](https://docs.snyk.io/snyk-api/authentication-for-api)). Set `SNYK_TOKEN=your-token` in environment or `.env`, then re-run [SF] Setup Forge. Without Enterprise, use `--no-security-scan` to skip. Security scanning is optional and does not block skill compilation."
 
 Record: "Security scan skipped — SNYK_TOKEN not configured"
 
@@ -143,7 +144,7 @@ Parse output for: `description_score`, `content_score`, `average_score`, `valida
 - **Content score < 70%:** Record warning: "Content quality warning: tessl scored content at {score}%."
 - **Unavailable:** Skip with note: "Content quality review skipped — tessl tool unavailable"
 
-**Expected scoring for two-tier design:** The Skill Forge two-tier design (Tier 1 Key API Summary + Tier 2 Full API Reference) intentionally includes progressive disclosure. tessl's `conciseness` scorer may flag this as redundancy (typically scoring 2/3), which is expected behavior — not a defect. Content scores >= 60% are acceptable when both tiers are correctly applied with proper differentiation (see step-05 Tier 2 assembly rules). Do NOT consolidate Tier 1 and Tier 2 content to improve the score — the two-tier structure is a deliberate design choice for standalone usability.
+> **EXPECTED BEHAVIOR — Two-Tier Scoring:** The Skill Forge two-tier design (Tier 1 Key API Summary + Tier 2 Full API Reference) intentionally includes progressive disclosure. tessl's `conciseness` scorer will flag this as redundancy (typically scoring 2/3), which is **expected behavior — not a defect**. tessl may also suggest removing `[MANUAL]` markers, moving Full API Reference to a separate file, or consolidating duplicate parameter documentation — **all three suggestions conflict with SKF design principles and must be dismissed.** Acceptable threshold: content scores >= 60% are normal for two-tier skills. Do NOT consolidate Tier 1 and Tier 2 content to improve the score — the two-tier structure is a deliberate design choice for standalone usability.
 
 tessl installs automatically via `npx`. A missing tool is not an error — graceful skip.
 
@@ -182,6 +183,7 @@ Cross-check metadata.json against extraction inventory:
 - `stats.public_api_coverage` and `stats.total_coverage` are correctly computed (null when denominator is 0)
 - `confidence_t1`, `confidence_t2`, `confidence_t3` match actual counts
 - `spec_version` is "1.3"
+- If `scripts[]` or `assets[]` arrays present: verify `stats.scripts_count`/`stats.assets_count` match array lengths; verify `file_entries` count in provenance-map.json matches
 
 Auto-fix any discrepancies (these are computed values).
 

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

@@ -62,6 +62,9 @@ skills/{name}/references/
 forge-data/{name}/
 ```
 
+If `scripts_inventory` is non-empty, also create: `skills/{name}/scripts/`
+If `assets_inventory` is non-empty, also create: `skills/{name}/assets/`
+
 Where `{name}` is the skill name from the brief (kebab-case).
 
 If directories already exist, do not error — proceed with file writing (overwrites existing files).
@@ -85,6 +88,14 @@ Write these 4 files from the compiled content:
 - One file per function group or type
 - Progressive disclosure detail files
 
+**Files 4b (conditional):** `skills/{name}/scripts/*`
+- One file per detected script, copied from source with content preserved
+- Only created when `scripts_inventory` is non-empty
+
+**Files 4c (conditional):** `skills/{name}/assets/*`
+- One file per detected asset, copied from source with content preserved
+- Only created when `assets_inventory` is non-empty
+
 ### 3. Write Workspace Artifacts to forge-data/{name}/
 
 Write these 3 files from the compiled content:
@@ -101,7 +112,7 @@ Write these 3 files from the compiled content:
 ### 4. Verify Write Completion
 
 After all files are written, verify:
-- All 7 files exist at their expected paths
+- All 7 base files exist at their expected paths, plus scripts/ and assets/ files when inventories are non-empty
 - List each file with its path and size
 
 **If any write failed:**
@@ -116,6 +127,8 @@ Display brief confirmation:
 - SKILL.md
 - context-snippet.md
 - metadata.json
+{if scripts: - scripts/ ({scripts_count} files)}
+{if assets: - assets/ ({assets_count} files)}
 - references/ ({reference_count} files)
 
 **Workspace (forge-data/{name}/):**

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

@@ -72,8 +72,8 @@ description: >
 
 **Frontmatter rules:**
 
-- `name`: lowercase alphanumeric + hyphens only, must match skill output directory name
-- `description`: non-empty, max 1024 chars, trigger-optimized for agent discovery
+- `name`: lowercase alphanumeric + hyphens only, must match skill output directory name. Prefer gerund form (`processing-pdfs`) for clarity.
+- `description`: non-empty, max 1024 chars, trigger-optimized for agent discovery. MUST use third-person voice ("Processes..." not "I can..." or "You can...").
 - No other frontmatter fields — only `name`, `description`, `license`, `compatibility`, `metadata`, `allowed-tools` are permitted by spec
 
 ### 3. Compile Integration Layer

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

@@ -83,7 +83,7 @@ Run: `npx skill-check -h`
 
 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 `body.max_lines` reported**, prefer selective split: extract only the largest Tier 2 section(s) to `references/`, keeping Tier 1 content inline (see `knowledge/split-body-strategy.md`). Fall back to `npx skill-check split-body <skill-dir> --write` if not feasible. Verify `#quick-start` and `#key-types` anchors still resolve after split. Then re-validate.
 
 **If unavailable**, perform manual frontmatter check:
 - [ ] Frontmatter present with `---` delimiters