bmad-module-skill-forge 0.4.0 → 0.5.0

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

@@ -234,43 +234,9 @@ constraints:
     regex: '^[A-Z]'
 ```
 
-### Re-Export Tracing
+### Re-Export Tracing and Script/Asset Extraction
 
-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.
+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
 

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,6 +123,9 @@ 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}",
@@ -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

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

@@ -3,6 +3,7 @@ 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'
 ---
@@ -118,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
 
@@ -135,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:
@@ -155,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
@@ -170,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 `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,7 +115,7 @@ 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
 

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

@@ -101,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.
@@ -123,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"
 
@@ -185,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

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

@@ -47,5 +47,5 @@
 - **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
+- Section anchors must be verified against actual SKILL.md headings during generation. For split-body skills (where `references/` exists and `## Full` headings are stubs), if a heading is missing from SKILL.md, rewrite the anchor to point to the reference file path (preferred). Omit the anchor line only if the heading cannot be found in either SKILL.md or `references/*.md`
 - Skill path is relative to project root

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

@@ -59,9 +59,11 @@ Verify the skill directory contains the expected agentskills.io package layout:
 ├── SKILL.md              ← Required: Active skill document
 ├── metadata.json         ← Required: Machine-readable metadata
 ├── context-snippet.md    ← Will be generated/updated in step-03
-└── references/           ← Optional: Progressive disclosure
-    ├── {function-a}.md
-    └── {function-b}.md
+├── references/           ← Optional: Progressive disclosure
+│   ├── {function-a}.md
+│   └── {function-b}.md
+├── scripts/              ← Optional: Executable automation
+└── assets/               ← Optional: Templates, schemas, configs
 ```
 
 **Check each component:**
@@ -75,6 +77,8 @@ Verify the skill directory contains the expected agentskills.io package layout:
    - `generation_date` (ISO date string)
    - `confidence_tier` ("Quick", "Forge", or "Deep")
 3. `references/` — If exists, check at least one .md file present
+4. `scripts/` — If exists, verify at least one file present and each file referenced in SKILL.md Section 7b exists. Warn for orphaned scripts (present but not referenced).
+5. `assets/` — If exists, verify at least one file present and each file referenced in SKILL.md Section 7b exists. Warn for orphaned assets (present but not referenced).
 
 ### 2. Validate Metadata Completeness
 

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

@@ -73,7 +73,8 @@ Load {snippetFormatData} and read the format template for the skill type.
 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.
+4. **Anchor verification (split-body awareness):** For each section anchor (`#quick-start`, `#key-types`), verify the heading exists in SKILL.md. If a `references/` directory exists and `## Full` headings in SKILL.md are absent or stubs (indicating split-body, not a stack skill's structural references), rewrite the anchor to point to the reference file path (e.g., `references/{file}.md#key-types`). If the heading cannot be resolved in either location, omit that anchor line from the snippet.
+5. Derive gotchas from: T2-future annotations in evidence report (breaking changes), async requirements, version-specific behavior. If no gotchas, omit the gotchas line.
 
 Generate:
 ```
@@ -157,6 +158,7 @@ ONLY WHEN snippet generation is complete (or skipped due to passive_context opt-
 
 - Snippet format loaded from {snippetFormatData}
 - Content generated matching exact Vercel-aligned format
+- Section anchors verified against SKILL.md headings (split-body anchors rewritten or omitted)
 - Token count estimated and within target
 - File written (or previewed in dry-run)
 - Passive context opt-out correctly handled (skip when disabled)

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

@@ -79,8 +79,8 @@ description: >
 ```
 
 **Frontmatter rules:**
-- `name`: lowercase alphanumeric + hyphens only, must match the skill output directory name
-- `description`: non-empty, max 1024 chars, optimized for agent discovery
+- `name`: lowercase alphanumeric + hyphens only, must match the skill output directory name. Prefer gerund form (`processing-pdfs`) for clarity.
+- `description`: non-empty, max 1024 chars, optimized for agent discovery. MUST use third-person voice ("Processes..." not "I can..." or "You can...").
 - No other frontmatter fields — only `name` and `description` for community skills
 
 **Required sections (after frontmatter):**
@@ -93,6 +93,7 @@ description: >
 - **Configuration:** If configuration options were found in source
 - **Dependencies:** Key dependencies from manifest
 - **Notes:** Caveats, limitations, extraction confidence level
+- **Scripts & Assets Note** (if source contains `scripts/`, `bin/`, `assets/`, `templates/`, or `schemas/` directories): "This package may include scripts and assets. Run create-skill for full extraction with provenance tracking."
 
 **If confidence is low:**
 - Include a note: "This skill was generated with limited source data. Consider running create-skill for a more thorough compilation."

package/src/workflows/test-skill/data/scoring-rules.md

@@ -27,6 +27,10 @@ When running in naive mode (no coherence category):
 
 When neither skill-check nor tessl is available, redistribute the 10% external validation weight proportionally to the other active categories. When only one tool is available, use that tool's score as the external validation score.
 
+## tessl and Split-Body Interaction
+
+tessl evaluates SKILL.md body content only — it does not read `references/*.md` files. After split-body extraction, the tessl content score will drop significantly (e.g., 65% to 38%) because Tier 2 content is no longer inline. This is expected behavior and does not reflect actual content quality. When reporting scores for a split-body skill, note: "tessl content score reflects post-split inline content only. Use the pre-split tessl score as the content quality baseline."
+
 ## Tier-Dependent Scoring
 
 ### Quick Tier (no tools)
@@ -78,5 +82,10 @@ If no integration patterns exist, combined coherence equals reference validity.
 | High | Signature mismatch between source and SKILL.md |
 | Medium | Missing type or interface documentation |
 | Medium | Migration section present/absent mismatch with T2-future annotation data (Deep tier) |
+| Medium | Script/asset directory exists but no Scripts & Assets section in SKILL.md |
+| Medium | Scripts & Assets section references file not found in scripts/ or assets/ directory |
+| Low | Script/asset file present without provenance entry in provenance-map.json file_entries |
 | Low | Missing optional metadata or examples |
+| Low | Description trigger optimization recommended (third-person voice, negative triggers, or keyword coverage gaps) |
 | Info | Style suggestions, non-blocking observations |
+| Info | Discovery testing not performed — realistic prompt testing recommended before export |

package/src/workflows/test-skill/steps-c/step-03-coverage-check.md

@@ -85,6 +85,8 @@ Read SKILL.md and extract all documented items:
 
 Build the **documented inventory** — a list of everything the SKILL.md claims the source provides.
 
+**Split-body traversal:** If a `references/` directory exists alongside SKILL.md and SKILL.md's `## Full` headings are absent or stubs (not a stack skill's structural references), extend the documented inventory scan to include all `references/*.md` files. After split-body, Tier 2 content (Full API Reference, Full Type Definitions) lives in reference files — the inventory must reflect the full skill content regardless of where it resides.
+
 ### 2. Analyze Source Code (Tier-Dependent)
 
 Start from the package entry point (see 0b) and identify the public API surface. Then analyze those exports at the appropriate tier depth.
@@ -223,7 +225,7 @@ ONLY WHEN all source files have been analyzed, the Coverage Analysis section has
 
 ### ✅ SUCCESS:
 
-- All source files analyzed at appropriate tier depth
+- All source files analyzed at appropriate tier depth; split-body references/ traversed when present
 - Every finding has file:line citation (Forge/Deep) or file-level reference (Quick)
 - Per-export status table complete
 - Category scores calculated per scoring rules

package/src/workflows/test-skill/steps-c/step-04-coherence-check.md

@@ -72,6 +72,7 @@ Perform lightweight structural checks:
 - Section headers are properly formatted
 - Code examples have language annotations
 - No broken markdown (unclosed code blocks, malformed tables)
+- If `scripts/` or `assets/` directory exists alongside SKILL.md, a "Scripts & Assets" section (Section 7b) should be present
 
 **Internal consistency:**
 - Exports referenced in usage examples match exports listed in exports section
@@ -101,6 +102,7 @@ Scan SKILL.md for all cross-references:
 - Skill references (`See SKILL.md for {other-skill}`, `Integrates with {package}`)
 - Type imports (`import { Type } from './module'`)
 - Integration pattern references (middleware chains, plugin hooks, shared state)
+- Script/asset references (`scripts/{file}`, `assets/{file}`) in SKILL.md body
 
 Launch a subprocess to grep/regex SKILL.md for reference patterns and return all found references with line numbers as structured JSON (`references_found[]` with line, type, target fields). If subprocess unavailable, scan in main thread.
 
@@ -114,6 +116,7 @@ DO NOT BE LAZY — For EACH reference found, launch a subprocess that:
    - Type imports: type is actually exported from the referenced module
    - Skill references: referenced skill exists in skills output folder
    - Integration patterns: documented pattern matches actual implementation
+   - Script/asset references: verify the referenced file exists in the skill's `scripts/` or `assets/` directory
 3. Returns structured validation JSON per reference (reference, line, target_exists, type_match, signature_match, issues[])
 
 If subprocess unavailable, validate each reference in main thread.
@@ -147,7 +150,7 @@ Build integration completeness findings:
 
 **Only execute if forge tier is Deep.** Skip silently for Quick/Forge tiers.
 
-Check whether SKILL.md contains a "Migration & Deprecation Warnings" section (Section 4b). Then check the skill's `evidence-report.md` (at `forge-data/{skill_name}/evidence-report.md`) for T2-future annotation counts.
+Check whether SKILL.md contains a "Migration & Deprecation Warnings" section (Section 4b). Then check the skill's `evidence-report.md` (at `{forge_data_folder}/{skill_name}/evidence-report.md`) for T2-future annotation counts.
 
 - **If T2-future annotations > 0 AND Section 4b is absent:** Flag as Medium severity gap: "Migration section missing — T2-future annotations exist but Section 4b is not present in SKILL.md Tier 1."
 - **If T2-future annotations = 0 AND Section 4b is present:** Flag as Medium severity gap: "Migration section unexpected — Section 4b is present but no T2-future annotations were produced."

package/src/workflows/test-skill/steps-c/step-04b-external-validators.md

@@ -58,9 +58,13 @@ Read {outputFile} frontmatter to get the skill directory path (`skillDir`).
 
 ### 1b. Check for Recent Validation Results (Auto-Reuse)
 
-Before running external validators, check if `{forge_data_folder}/{skill_name}/evidence-report.md` contains validation results (a `## Validation Results` section with quality scores). If recent results exist (from a create-skill run that just completed), auto-reuse them — skip re-running validators and use the existing scores from the evidence report. Record: "External validation: reused from create-skill evidence report." Skip to section 5 (append results).
+Before running external validators, check if `{forge_data_folder}/{skill_name}/evidence-report.md` contains validation results (a `## Validation Results` section with quality scores).
 
-If no evidence report exists or it contains no validation section, proceed to section 2 (fresh run).
+**Staleness check:** Compare the evidence report's generation date against SKILL.md's last-modified timestamp (or `metadata.json` `generation_date`). If SKILL.md was modified after the evidence report was generated (e.g., after update-skill), the cached results are stale — skip auto-reuse and proceed to section 2 for a fresh run.
+
+If recent, non-stale results exist (from a create-skill run that just completed), auto-reuse them — skip re-running validators and use the existing scores. Record: "External validation: reused from create-skill evidence report." Skip to section 5 (append results).
+
+If no evidence report exists, it contains no validation section, or results are stale, proceed to section 2 (fresh run).
 
 ### 2. Run skill-check
 
@@ -118,7 +122,7 @@ Store in context: `tessl_description_score`, `tessl_content_score`, `tessl_avera
 
 **If tessl content score < 70%:** Flag a warning:
 
-"**Content quality warning:** tessl scored content at {score}%. This often indicates SKILL.md lacks inline actionable content (e.g., after split-body). Consider inlining Quick Start and common workflows directly in SKILL.md."
+"**Content quality warning:** tessl scored content at {score}%. This often indicates SKILL.md lacks inline actionable content (e.g., after split-body). If this is a split-body skill, the score drop is expected — tessl evaluates only SKILL.md body, not `references/*.md` (see scoring-rules.md). Consider using selective split to keep actionable content inline."
 
 **If tessl fails entirely:** Record `tessl_score: N/A`, log warning, continue.
 

package/src/workflows/test-skill/steps-c/step-05-score.md

@@ -5,7 +5,7 @@ description: 'Calculate completeness score from coverage and coherence findings'
 nextStepFile: './step-06-report.md'
 outputFile: '{forge_data_folder}/{skill_name}/test-report-{skill_name}.md'
 scoringRulesFile: '../data/scoring-rules.md'
-sourceAccessProtocol: '../data/{sourceAccessProtocol}'
+sourceAccessProtocol: '../data/source-access-protocol.md'
 ---
 
 # Step 5: Score

package/src/workflows/test-skill/steps-c/step-06-report.md

@@ -83,8 +83,13 @@ Load `{scoringRulesFile}` for gap severity classification:
 | **High** | Signature mismatch between source and SKILL.md |
 | **Medium** | Missing type or interface documentation |
 | **Medium** | Migration section present/absent mismatch with T2-future annotation data (Deep tier) |
+| **Medium** | Script/asset directory exists but no Scripts & Assets section in SKILL.md |
+| **Medium** | Scripts & Assets section references file not found in scripts/ or assets/ directory |
+| **Low** | Script/asset file present without provenance entry in provenance-map.json file_entries |
 | **Low** | Missing optional metadata or examples |
+| **Low** | Description trigger optimization recommended (third-person voice, negative triggers, or keyword coverage gaps) |
 | **Info** | Style suggestions, non-blocking observations |
+| **Info** | Discovery testing not performed — realistic prompt testing recommended before export |
 
 ### 3. Classify and Order Gaps
 
@@ -98,6 +103,25 @@ Load the Gap Report section format from `{outputFormatsFile}`. Count gaps by sev
 
 If no gaps found, append a clean pass message recommending **export-skill** workflow.
 
+### 4b. Discovery and Description Quality Recommendations
+
+After gap enumeration, append a **Discovery Quality** subsection to the gap report. Use the `Gap Entry Format` from `{outputFormatsFile}` for any Low/Info entries. The prose recommendations below are appended after the gap entries:
+
+**Description optimization:** If tessl `description_score` (from step 04b) is below 90%, or if skill-check flagged description issues, recommend description improvements:
+- Check that the description uses third-person voice consistently
+- Check for specific trigger keywords that match how users would phrase requests
+- Check for negative triggers ("NOT for: ...") to prevent false matches
+- Check for alternative skill references for excluded use cases
+
+**Discovery testing recommendation:** Regardless of pass/fail, always append:
+
+"**Discovery testing recommended.** Before export, test the skill with 3-5 realistic prompts phrased the way real users actually talk — with casual language, typos, incomplete context, and implicit references. A skill tested only with clean prompts may fail to trigger in production. Example realistic prompt patterns:
+- Vague: 'can you help me with this csv file my boss sent'
+- Implicit: 'why did revenue drop last quarter'
+- Abbreviated: 'run the {skill-name} thing on this data'"
+
+Record discovery testing status as Info-level in the gap table. This is advisory — it does not affect the score.
+
 ### 5. Finalize Output Document
 
 Update `{outputFile}` frontmatter:
@@ -132,6 +156,8 @@ Update `{outputFile}` frontmatter:
 
 ---
 
+**See Discovery Quality section in the report for description optimization and realistic prompt testing recommendations.**
+
 **Test report finalized.**"
 
 ### 7. Present MENU OPTIONS
@@ -163,6 +189,7 @@ This is the final step of the test-skill workflow. When the user selects C, the
 - Gaps classified by severity using scoring rules
 - Gaps ordered by severity (Critical first)
 - Every gap has a specific, actionable remediation suggestion
+- Discovery quality section appended with description optimization and testing recommendations
 - Remediation summary with counts and effort estimates
 - Output document finalized with all stepsCompleted
 - Correct next workflow recommended (export-skill or update-skill)

package/src/workflows/update-skill/steps-c/step-02-detect-changes.md

@@ -112,6 +112,14 @@ Launch subprocesses in parallel that compare source state against provenance map
 - Cross-reference deleted files/exports with added files/exports
 - If content similarity > 80%: classify as RENAMED instead of deleted+added
 
+**Category D — Script/asset file changes:**
+- Compare `file_entries` from provenance-map.json against current source files
+- For each file_entry: compute current SHA-256 content hash, compare against stored hash
+- Files with changed hashes → MODIFIED_FILE
+- Files in provenance but missing from source → DELETED_FILE
+- Files in source matching detection patterns (scripts/, bin/, assets/, templates/) but not in provenance → NEW_FILE
+- Files in `scripts/[MANUAL]/` or `assets/[MANUAL]/` → SKIP (user-authored, preserved)
+
 Aggregate all subprocess results into a unified change manifest.
 
 **If degraded mode (no provenance map):**
@@ -136,6 +144,9 @@ Change Manifest:
   exports_renamed: [count]
   exports_moved: [count]
 
+  scripts_modified, scripts_added, scripts_deleted: {counts}
+  assets_modified, assets_added, assets_deleted: {counts}
+
   Per-file detail:
     {file_path}:
       status: MODIFIED|ADDED|DELETED|MOVED

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

@@ -100,6 +100,14 @@ Follow the merge priority order from {mergeConflictRulesFile}:
 - Place before any [MANUAL] blocks at section boundary
 - No conflicts expected (new content, no existing [MANUAL])
 
+**Priority 6 — Process script/asset file changes (from Category D in change manifest):**
+- MODIFIED_FILE: queue file for re-copy from source, update `file_entries` content_hash
+- DELETED_FILE: queue file for removal from `scripts/` or `assets/`, remove from `file_entries`
+- NEW_FILE: queue file for copy from source, add to `file_entries`
+- Files in `scripts/[MANUAL]/` or `assets/[MANUAL]/` are never modified (user-authored)
+- Update Section 7b manifest table to reflect changes
+- Update `metadata.json` `scripts[]`/`assets[]` arrays and `stats.scripts_count`/`stats.assets_count`
+
 ### 4. Check for Conflicts
 
 Scan all merge operations for flagged conflicts:

package/src/workflows/update-skill/steps-c/step-05-validate.md

@@ -73,7 +73,7 @@ Launch subprocesses in parallel for each validation category, aggregating result
 
 **If available**, run: `npx skill-check check <skill-dir> --fix --format json --no-security-scan`
 
-Parse JSON output for quality score (0-100), auto-fixed issues, and remaining diagnostics. If `body.max_lines` reported, run: `npx skill-check split-body <skill-dir> --write`
+Parse JSON output for quality score (0-100), auto-fixed issues, and remaining diagnostics. If `body.max_lines` reported, prefer selective split: extract only the largest Tier 2 section(s) to `references/`, keeping all Tier 1 content inline (see `knowledge/split-body-strategy.md`). Fall back to `npx skill-check split-body <skill-dir> --write` only if selective split is not feasible. After any split, verify `#quick-start` and `#key-types` anchors still resolve in SKILL.md.
 
 **If unavailable**, perform manual check: validate merged SKILL.md structure, verify required sections (exports, usage patterns, conventions), verify export entries have name/type/signature/file:line reference, flag missing sections.