bmad-module-skill-forge 0.3.0 → 0.5.0

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/export-skill/workflow.md

@@ -49,7 +49,7 @@ description: Package for distribution + platform-aware context injection
 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`
-- `skills_output_folder`, `forge_data_folder`
+- `skills_output_folder`, `forge_data_folder`, `sidecar_path`
 
 ### 2. First Step Execution
 

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/data/source-access-protocol.md

@@ -23,6 +23,8 @@ Check if `{source_path}` (from metadata.json `source_root`) exists on disk. If y
 **State 2 — Local absent, provenance-map exists:**
 Check `{forge_data_folder}/{skill_name}/provenance-map.json`. If present, use it as the baseline export inventory — each entry contains structured fields: `export_name`, `export_type`, `params[]`, `return_type`, `source_file`, `source_line`, `confidence`, and `ast_node_type`. Cross-reference against SKILL.md documented exports for name-matching and param-by-param coverage. Signature verification compares SKILL.md's documented params/return types against provenance-map entries directly. If remote reading tools are available (zread, deepwiki, gh API, or similar), supplement by reading the entry point file for live signature verification. Set `analysis_confidence: provenance-map`.
 
+**State 2 limitations:** Signature verification at State 2 is **string comparison only**, not semantic. Provenance-map stores parameters as flat string arrays (e.g., `["data: Union[BinaryIO, list, str]"]`), so `str` vs `String` or `list` vs `List[Any]` would be treated as mismatches even when semantically equivalent. For full type-aware verification (handling type aliases, generic equivalence), State 1 (local source) with AST re-parsing is required. When the SKILL.md was compiled from the same provenance-map (typical for create-then-test flows), strings match exactly and this limitation has no practical effect.
+
 **State 3 — No provenance-map, metadata exports exist (quick-skill path):**
 If no provenance-map.json exists (typical for quick-skill output), fall back to `metadata.json`'s `exports[]` array for the export name list. Coverage check becomes a self-consistency comparison: are all names in `exports[]` documented in SKILL.md with description, parameters, and return type? Signatures cannot be verified. If remote reading tools are available, supplement by reading the entry point for live export comparison. Set `analysis_confidence: metadata-only`.
 
@@ -35,3 +37,9 @@ If none of the above succeed, fall through to docs-only mode (section 0 already
 Set `analysis_confidence` in context for use in Section 2 analysis depth, step-05 output, and step-05 scoring.
 
 **Confidence tier mapping:** `full` = T1, `provenance-map` = T1, `metadata-only` = T1-low, `remote-only` = T1-low, `docs-only` = T3. This aligns with the T1/T1-low/T2/T3 scale used across all SKF workflows.
+
+**Degradation notice rules:** When `analysis_confidence` is `provenance-map`, check the `confidence` field of provenance-map entries before emitting a degradation recommendation:
+
+- **All/most entries T1 (AST-verified):** The provenance-map data is already at highest confidence. Do NOT recommend re-running with a local clone — it would produce identical results. Use: "Resolved via: provenance-map (T1 AST-verified at compilation time). Local clone not required — provenance data is already at highest confidence."
+- **Mixed T1/T1-low entries:** Report the breakdown. Recommend local clone only for the T1-low entries: "Resolved via: provenance-map ({n} T1, {m} T1-low). Re-run with local clone to upgrade T1-low entries to full AST verification."
+- **All/most entries T1-low or lower:** Keep the standard recommendation: "Re-run with local clone for full AST-backed verification."

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."
@@ -168,7 +171,7 @@ Basic structural validation of **{skill_name}**:
 - {N} structural issues found
 - Coherence category not scored (weight redistributed to coverage)
 
-**Proceeding to scoring...**"
+**Proceeding to external validation...**"
 
 **For Contextual Mode:**
 "**Coherence check complete (contextual mode).**
@@ -180,11 +183,11 @@ Reference validation of **{skill_name}**:
 
 **{N} issues found** — details in Coherence Analysis section.
 
-**Proceeding to scoring...**"
+**Proceeding to external validation...**"
 
 ### 8. Auto-Proceed
 
-Display: "**Proceeding to scoring...**"
+Display: "**Proceeding to external validation...**"
 
 #### Menu Handling Logic:
 
@@ -197,7 +200,7 @@ Display: "**Proceeding to scoring...**"
 
 ## CRITICAL STEP COMPLETION NOTE
 
-ONLY WHEN coherence analysis is complete (naive structural or contextual full validation), the Coherence Analysis section has been appended to {outputFile}, and coherence scores (if contextual) have been calculated, will you then load and read fully `{nextStepFile}` to execute scoring.
+ONLY WHEN coherence analysis is complete (naive structural or contextual full validation), the Coherence Analysis section has been appended to {outputFile}, and coherence scores (if contextual) have been calculated, will you then load and read fully `{nextStepFile}` to execute external validation.
 
 ---
 

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

@@ -56,6 +56,16 @@ Run external validation tools (`skill-check` and `tessl`) against the skill dire
 
 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).
+
+**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
 
 **Check availability:**
@@ -112,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,6 +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/source-access-protocol.md'
 ---
 
 # Step 5: Score
@@ -136,14 +137,14 @@ Append the **Completeness Score** section to `{outputFile}`:
 **Analysis Confidence:** {full | provenance-map | metadata-only | remote-only | docs-only}
 ```
 
-If `analysis_confidence` is not `full`, append a degradation notice:
+If `analysis_confidence` is not `full`, append a degradation notice. **The notice must be confidence-aware** — see the degradation notice rules in `{sourceAccessProtocol}`:
 
 ```markdown
 ### Access Degradation Notice
 
-**Resolved via:** {analysis_confidence}
-**Impact:** {describe limitation — e.g., "Signature checks limited to name-matching. Source file:line citations from provenance-map, not live AST."}
-**Recommendation:** Re-run with local clone for full AST-backed verification.
+**Resolved via:** {analysis_confidence} {confidence breakdown if provenance-map, e.g., "(T1 AST-verified at compilation time)" or "(12 T1, 3 T1-low)"}
+**Impact:** {describe limitation — e.g., "Signature checks limited to name-matching. Source file:line citations from provenance-map, not live AST." — or "Provenance data is at highest confidence; no limitation." for all-T1 provenance-map}
+**Recommendation:** {confidence-dependent — see {sourceAccessProtocol} degradation notice rules. Do NOT recommend local clone when provenance-map entries are already T1.}
 ```
 
 ### 7. Update Output Frontmatter

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/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/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-03-re-extract.md

@@ -4,6 +4,7 @@ description: 'Tier-aware AST extraction on changed files only, producing fresh e
 
 nextStepFile: './step-04-merge.md'
 extractionPatternsData: '../../create-skill/data/extraction-patterns.md'
+tierDegradationRulesData: '../data/tier-degradation-rules.md'
 remoteSourceResolutionData: '../data/remote-source-resolution.md'
 ---
 

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.
 

package/src/workflows/update-skill/steps-c/step-06-write.md

@@ -96,6 +96,11 @@ Write to `{forge_data_folder}/{skill_name}/provenance-map.json`:
 **For new exports:**
 - Add new entry with full structured fields: `export_name`, `export_type`, `params[]`, `return_type`, `source_file`, `source_line`, `confidence`, `extraction_method`, `ast_node_type`
 
+**For script/asset file changes (if `file_entries` exists):**
+- MODIFIED_FILE: copy updated file to `scripts/` or `assets/`, update `content_hash` in `file_entries`
+- DELETED_FILE: remove file from `scripts/` or `assets/`, remove entry from `file_entries`
+- NEW_FILE: copy file to `scripts/` or `assets/`, add entry to `file_entries` with `file_name`, `file_type`, `source_file`, `confidence: "T1-low"`, `extraction_method: "file-copy"`, `content_hash`
+
 **Add update operation metadata:**
 ```json
 {
@@ -177,7 +182,7 @@ External tool checks deferred from step-05 now run against the written files:
 
 **If skill-check available:**
 - Run: `npx skill-check check {skills_output_folder}/{skill_name} --fix --format json --no-security-scan`
-- If `body.max_lines` reported, run: `npx skill-check split-body {skills_output_folder}/{skill_name} --write`
+- If `body.max_lines` reported, prefer selective split (see `knowledge/split-body-strategy.md`). Fall back to `npx skill-check split-body {skills_output_folder}/{skill_name} --write` if not feasible. Verify anchors resolve after split.
 - Run: `npx skill-check diff` if original version was preserved
 - Run: `npx skill-check check {skills_output_folder}/{skill_name} --format json` for security scan
 

package/tools/cli/lib/ui.js

@@ -61,7 +61,7 @@ class UI {
     console.log(row(chalk.white.bold('Skill Forge') + chalk.dim(` v${version}`)));
     console.log(row(chalk.dim('Agent Skill Compiler') + ' '.repeat(15) + brand.spark('⚒')));
     console.log(mid);
-    console.log(row(chalk.dim('AST-verified · version-pinned · zero hallucination')));
+    console.log(row(chalk.dim('Code · Docs · Discourse → Verified agent skills')));
     console.log(bottom);
     console.log();