bmad-module-skill-forge 0.3.0 → 0.5.0

package/docs/index.md

@@ -1,10 +1,10 @@
 ---
 title: Skill Forge (SKF)
-description: AST-verified, provenance-backed agent skills from code repositories, documentation, and developer discourse
+description: Turn code and docs into instructions AI agents can actually follow
 template: splash
 hero:
   title: Skill Forge (SKF)
-  tagline: AST-verified, provenance-backed agent skills from code repositories, documentation, and developer discourse
+  tagline: Turn code and docs into instructions AI agents can actually follow.
   actions:
     - text: Getting Started
       link: ./getting-started/
@@ -15,62 +15,35 @@ hero:
       icon: external
 ---
 
-## What is Skill Forge?
+## What does Skill Forge do?
 
-Skill Forge is an automated skill compiler for the AI agent ecosystem. It transforms code repositories, documentation, and developer discourse into [agentskills.io](https://agentskills.io)-compliant, version-pinned, provenance-backed agent skills. Every instruction traces to verifiable sources — zero hallucination tolerance.
-
-- **AST-Verified**: Structural truth via ast-grep — no guessing, no hallucination.
-- **Provenance-Backed**: Every claim traces to source code with file and line references.
-- **Progressive Tiers**: Quick (no setup) → Forge (ast-grep) → Deep (QMD knowledge).
-- **Ecosystem-First**: Checks for official skills before generating community ones.
+AI agents hallucinate API calls. They invent function names, guess parameter types, and produce code that doesn't compile. Skill Forge fixes this by analyzing code repositories, documentation, and developer discourse — extracting real signatures and patterns and compiling them into verified instruction files that any AI agent can follow. Every instruction traces back to where it came from.
 
 ## Quick Install
 
 Requires [Node.js](https://nodejs.org/) >= 22.
 
-**Standalone:**
-
 ```bash
 npx bmad-module-skill-forge install
 ```
 
-**Or as a custom module with BMad Method** (for the full development workflow):
-
-```bash
-npx bmad-method install    # select "Add custom modules" and point to src/
-```
-
-Then interact with the forge agent:
+Then set up your environment and generate your first skill:
 
 ```
-@Ferris SF    # Setup your forge environment
-@Ferris QS    # Quick Skill — generate in under a minute
+@Ferris SF              # Set up your forge
+@Ferris QS <package>    # Generate a skill in under a minute
 ```
 
-See the [Getting Started](./getting-started.md) guide for all installation methods.
-
-## Core Workflows
-
-| Workflow | Trigger | Purpose |
-|----------|---------|---------|
-| [Setup Forge](/workflows/#setup-forge-sf) | SF | Initialize forge, detect tools, set tier |
-| [Brief Skill](/workflows/#brief-skill-bs) | BS | Scope and design a skill |
-| [Create Skill](/workflows/#create-skill-cs) | CS | Compile a skill from a brief |
-| [Quick Skill](/workflows/#quick-skill-qs) | QS | Fast skill, no brief needed |
-| [Stack Skill](/workflows/#stack-skill-ss) | SS | Consolidated project stack skill |
-| [Update Skill](/workflows/#update-skill-us) | US | Regenerate after source changes |
-| [Audit Skill](/workflows/#audit-skill-as) | AS | Drift detection |
-| [Test Skill](/workflows/#test-skill-ts) | TS | Verify completeness |
-| [Export Skill](/workflows/#export-skill-ex) | EX | Package for distribution |
-| [Analyze Source](/workflows/#analyze-source-an) | AN | Discover what to skill |
+See the [Getting Started](./getting-started/) guide for full installation and usage instructions.
 
 ## Documentation
 
-- **[Getting Started](./getting-started.md)** — Installation, prerequisites, first steps
-- **[Architecture](./architecture.md)** — Output format, confidence model, tiers, tool ecosystem
-- **[Agents](./agents.md)** — Ferris agent: modes, capabilities, communication style
-- **[Workflows](./workflows.md)** — All 10 workflows with commands and connection diagram
-- **[Examples](./examples.md)** — Real-world scenarios, tips, and troubleshooting
+- **[Getting Started](./getting-started/)** — Installation, prerequisites, and your first skill
+- **[Concepts](./concepts/)** — Plain-English definitions of key terms (provenance, tiers, drift, and more)
+- **[How It Works](./how-it-works/)** — Architecture, capability model, output format, and design decisions
+- **[Workflows](./workflows/)** — All 10 workflows with commands and connection diagrams
+- **[Agents](./agents/)** — Ferris: the AI agent that runs all SKF workflows
+- **[Examples](./examples/)** — Real-world scenarios, tips, and troubleshooting
 
 ## Support
 

package/docs/workflows.md

@@ -5,7 +5,7 @@ description: All 10 SKF workflows with commands, steps, and connection diagram
 
 # Workflows Reference
 
-SKF includes 10 workflows organized by purpose:
+SKF has 10 workflows. You trigger them by typing commands to [Ferris](../agents.md), the AI agent that runs everything. Each workflow handles a specific part of the skill lifecycle — from analyzing source code to packaging for distribution. If any terms are unfamiliar, see the [Concepts](../concepts.md) page for plain-English definitions.
 
 ---
 

package/package.json

@@ -1,8 +1,8 @@
 {
   "$schema": "https://json.schemastore.org/package.json",
   "name": "bmad-module-skill-forge",
-  "version": "0.3.0",
-  "description": "BMAD module — AST-verified, provenance-backed agent skills compiler with progressive capability tiers (Quick/Forge/Deep)",
+  "version": "0.5.0",
+  "description": "BMAD module — Turn code and docs into instructions AI agents can actually follow. Progressive capability tiers (Quick/Forge/Deep).",
   "keywords": [
     "bmad",
     "bmad-method",

package/src/knowledge/agentskills-spec.md

@@ -36,7 +36,9 @@ description: >
 
 **Frontmatter constraints:**
 - `name`: 1-64 characters, lowercase alphanumeric + hyphens, must match parent directory name
+  - **Naming convention:** Prefer gerund form (verb + -ing) for clarity: `processing-pdfs`, `analyzing-spreadsheets`, `managing-databases`. Noun phrases (`pdf-processing`) and action-oriented forms (`process-pdfs`) are acceptable alternatives. Avoid vague names (`helper`, `utils`, `tools`).
 - `description`: 1-1024 characters, trigger-optimized for agent matching
+  - **MUST use third-person voice.** The description is injected into the system prompt; inconsistent point-of-view causes discovery problems. Write "Processes Excel files and generates reports" — never "I can help you process Excel files" or "You can use this to process Excel files."
 
 **Body:** Free-form markdown — no structural restrictions, but Skill Forge follows a consistent section order (see skill-sections.md in create-skill/data/).
 
@@ -52,6 +54,8 @@ skill-name/
 
 All subdirectories are exactly one level deep. Files are loaded on demand when SKILL.md directs — never automatically.
 
+Scripts and assets extracted by Skill Forge inherit provenance from their source repository. Each file receives a `[SRC:{source_path}:L1]` citation (T1-low confidence) and a SHA-256 content hash for drift detection. Scripts must follow the quality principles in the Script Quality section below. Assets are static files loaded on demand — agents use them as directed by SKILL.md instructions.
+
 ## Progressive Disclosure Model
 
 The format implements a three-phase loading model:
@@ -141,6 +145,24 @@ the user's configuration against the expected structure.
 - Line count is a guideline — exceeding 500 lines produces a warning
 - Path validation prevents broken references in the published skill
 
+## MCP Tool References
+
+If a skill references MCP (Model Context Protocol) tools, always use fully qualified names to avoid "tool not found" errors: `ServerName:tool_name` (e.g., `BigQuery:bigquery_schema`, `GitHub:create_issue`). Without the server prefix, agents may fail to locate the tool when multiple MCP servers are available.
+
+## Script Quality
+
+Skills that include executable scripts in `scripts/` must follow these principles:
+
+- **Solve, don't punt.** Scripts handle errors explicitly rather than failing and leaving the agent to figure it out. Provide fallback behavior, descriptive error messages, and recovery paths.
+- **No voodoo constants.** Every magic number or configuration value must be justified with a comment explaining why that value was chosen. If you don't know the right value, the agent won't either.
+- **Descriptive error output.** Write error messages to stdout/stderr that enable agents to self-correct without user intervention (e.g., "Field 'signature_date' not found. Available fields: customer_name, order_total").
+
+## Development Methodology
+
+- **Evaluation-driven development.** Define 2-3 concrete use cases and realistic test prompts before building the skill. Build evaluations before writing extensive documentation — this ensures the skill solves real problems rather than documenting imagined ones.
+- **Realistic test prompts.** Test with prompts the way real users actually talk — with typos, casual abbreviations, and incomplete context. A skill tested only with clean prompts will break in unexpected ways in production.
+- **Iterative refinement.** Observe how agents navigate and use the skill. Watch for unexpected exploration paths, missed references, overreliance on certain sections, and ignored content. Iterate based on observed behavior, not assumptions.
+
 ## Anti-Patterns
 
 - Writing skills as documentation (README-style) instead of procedural agent instructions
@@ -148,6 +170,9 @@ the user's configuration against the expected structure.
 - Vague descriptions ("helps with databases") — descriptions must be specific and trigger-optimized
 - Including redundant content that duplicates what the agent already knows (standard language features, basic CLI commands)
 - Bundling large library code inside skills — skills reference existing tools, not replace them
+- Time-sensitive instructions ("If before August 2025, use the old API") — use versioned sections instead
+- Offering too many tool/library options without a clear default — provide one recommended approach with escape hatches for edge cases
+- Inconsistent terminology — mixing synonyms ("API endpoint", "URL", "route") confuses agent execution
 
 ## Related Fragments
 

package/src/knowledge/manual-section-integrity.md

@@ -38,6 +38,14 @@ by the forge during updates or regeneration.
 - Nested \[MANUAL\] blocks are forbidden — trigger an ERROR if detected
 - Markers apply to any output file: `SKILL.md`, `references/*.md`, integration files
 
+### [MANUAL] Subdirectories
+
+User-authored scripts and assets are placed in `scripts/[MANUAL]/` and `assets/[MANUAL]/` subdirectories within the skill package. These follow the same preservation principle as markdown `<!-- [MANUAL] -->` markers:
+
+- Files in `[MANUAL]/` subdirectories are preserved unconditionally during `update-skill`
+- Source-derived scripts/assets (outside `[MANUAL]/`) are refreshed from source during updates
+- Conflicts (user file has same name as source file outside `[MANUAL]/`) are flagged as HIGH severity
+
 ## Pattern Examples
 
 ### Example 1: Adding Manual Context to a Generated Skill

package/src/knowledge/overview.md

@@ -27,9 +27,10 @@ With knowledge files:
 | [progressive-capability.md](progressive-capability.md)     | Quick/Forge/Deep tier philosophy and behavior adaptation          | All 10                             |
 | [agentskills-spec.md](agentskills-spec.md)                 | agentskills.io output format principles and compliance            | CS, QS, SS, US, TS, EX             |
 | [skill-lifecycle.md](skill-lifecycle.md)                   | End-to-end pipeline, artifact flow, workflow selection            | All 10                             |
-| [provenance-tracking.md](provenance-tracking.md)           | Provenance-map.json, evidence reports, claim traceability         | CS, QS, SS, US, AS, TS             |
+| [provenance-tracking.md](provenance-tracking.md)           | Provenance-map.json entries and file_entries, evidence reports, claim traceability | CS, QS, SS, US, AS, TS             |
 | [manual-section-integrity.md](manual-section-integrity.md) | \[MANUAL\] marker preservation and merge algorithm                | CS, US, AS, TS, EX                 |
 | [qmd-registry.md](qmd-registry.md)                         | Progressive QMD collection registry and collection gate principle | SF, BS, CS, US, AS                 |
+| [split-body-strategy.md](split-body-strategy.md)           | Selective vs full split-body, detection pattern, agent accuracy   | CS, QS, US, TS, EX                |
 
 ## JiT Loading Protocol
 

package/src/knowledge/provenance-tracking.md

@@ -147,6 +147,19 @@ With provenance tracking:
 - Provenance timestamps show when each entry was last verified
 - The merge preserves \[MANUAL\] section provenance (author: "manual", no source location)
 
+### File-Level Provenance (file_entries)
+
+Scripts and assets use a separate `file_entries` array in `provenance-map.json`, distinct from the export-level `entries` array:
+
+| Field | Description |
+|-------|-------------|
+| `file_name` | Path relative to skill root (e.g., `scripts/validate.sh`) |
+| `file_type` | `script` or `asset` |
+| `source_file` | Path relative to source root |
+| `confidence` | Always `T1-low` (file-copy, not AST-verified) |
+| `extraction_method` | Always `file-copy` |
+| `content_hash` | SHA-256 of file content (for drift detection) |
+
 ## Inline Citation Rules
 
 Citations appear directly in SKILL.md content:

package/src/knowledge/skf-knowledge-index.csv

@@ -3,9 +3,10 @@ overview,Knowledge Overview,"Entry point — knowledge map, JiT loading protocol
 zero-hallucination,Zero Hallucination Principle,"Foundational principle — uncitable content is excluded not guessed, every claim traces to source","integrity,provenance,extraction",core,knowledge/zero-hallucination.md
 confidence-tiers,Confidence Tiers,"Trust model — T1/T1-low/T2/T3 labels, citation formats, tier interaction rules","confidence,citations,evidence,tiers",core,knowledge/confidence-tiers.md
 progressive-capability,Progressive Capability,"Quick/Forge/Deep philosophy — every tier is legitimate, positive framing, graceful degradation","tiers,quick,forge,deep,capability",core,knowledge/progressive-capability.md
-agentskills-spec,agentskills.io Specification,"Format principles — frontmatter, progressive disclosure, directory structure, compliance rules","agentskills,format,compliance,output",core,knowledge/agentskills-spec.md
+agentskills-spec,agentskills.io Specification,"Format principles — frontmatter, progressive disclosure, directory structure, compliance rules, MCP tool naming, script quality, development methodology","agentskills,format,compliance,output,mcp,scripts,methodology",core,knowledge/agentskills-spec.md
 skill-lifecycle,Skill Lifecycle,"End-to-end pipeline — workflow connections, artifact flow, decision rules for workflow selection","lifecycle,pipeline,workflows,artifacts",core,knowledge/skill-lifecycle.md
-provenance-tracking,Provenance Tracking,"Provenance mechanism — provenance-map.json, evidence reports, claim traceability","provenance,evidence,traceability,citations",core,knowledge/provenance-tracking.md
+provenance-tracking,Provenance Tracking,"Provenance mechanism — provenance-map.json entries and file_entries, evidence reports, claim traceability","provenance,evidence,traceability,citations,file-entries",core,knowledge/provenance-tracking.md
 manual-section-integrity,Manual Section Integrity,"[MANUAL] preservation — marker format, merge algorithm, orphan detection","manual,preservation,merge,markers",core,knowledge/manual-section-integrity.md
 qmd-registry,QMD Collection Registry,"Progressive registry architecture — producer/consumer/janitor roles, collection gate principle, forge-tier.yaml registry schema","qmd,registry,collections,deep,indexing",core,knowledge/qmd-registry.md
 doc-fetcher,Doc Fetcher,"T3 external documentation — tool-agnostic URL fetching, quarantine rules, conflict resolution","doc-fetcher,t3,external,documentation,quarantine",extended,knowledge/doc-fetcher.md
+split-body-strategy,Split-Body Strategy,"Selective split guidance — detection pattern, recommended approach, impact on tessl scores and snippet anchors","split-body,selective-split,references,body-size",core,knowledge/split-body-strategy.md

package/src/knowledge/skill-lifecycle.md

@@ -25,7 +25,7 @@ With lifecycle awareness:
 | Setup | SF (Setup Forge) | Detect environment and set capability tier | `forge-tier.yaml` |
 | Discovery | AN (Analyze Source) | Scan project, identify skillable units | Analysis report, skill briefs |
 | Design | BS (Brief Skill) | Interactive scope definition for one skill | `skill-brief.yaml` |
-| Compilation | CS, QS, SS (Create/Quick/Stack) | Extract source and compile skill | `SKILL.md`, metadata, provenance |
+| Compilation | CS, QS, SS (Create/Quick/Stack) | Extract source and compile skill | `SKILL.md`, metadata, provenance, `scripts/`, `assets/` (when source contains them) |
 | Maintenance | US, AS (Update/Audit) | Detect drift and refresh skills | Updated `SKILL.md`, drift report |
 | Verification | TS (Test Skill) | Quality gate — completeness scoring | Test report, pass/fail decision |
 | Distribution | EX (Export Skill) | Package and inject into agent context | agentskills.io bundle, snippets |
@@ -108,7 +108,7 @@ SF → forge-tier.yaml
        ↓ (read by all subsequent workflows)
 AN → analysis-report.md + skill-brief.yaml[]
        ↓ (briefs consumed by CS)
-CS → SKILL.md + metadata.json + provenance-map.json + evidence-report.md
+CS → SKILL.md + metadata.json + provenance-map.json + scripts/ + assets/ (when present) + evidence-report.md
        ↓ (skill consumed by TS)
 TS → test-report.md (pass/fail gate)
        ↓ (passing skill consumed by EX)

package/src/knowledge/split-body-strategy.md

@@ -0,0 +1,41 @@
+# Split-Body Strategy
+
+## Principle
+
+Selective split is the recommended strategy when `split-body` is needed. Extract only the largest Tier 2 section(s) to stay under the `body.max_lines` limit — keep all actionable Tier 1 content inline. Full split-body reduces agent accuracy because on-demand retrieval underperforms inline passive context.
+
+## Rationale
+
+Vercel research shows inline passive context achieves 100% task accuracy vs 79% for on-demand retrieval. Full split-body moves all Tier 2 content to `references/`, forcing agents to retrieve it on demand. Selective split preserves the most-used content inline while still satisfying the body size constraint.
+
+Without selective split awareness:
+- `skill-check split-body --write` extracts everything, reducing agent effectiveness
+- tessl content scores drop dramatically (65% → 38%) because only SKILL.md body is evaluated
+- Context snippet anchors (`#quick-start`, `#key-types`) may break if those sections move to references
+
+With selective split awareness:
+- Only the largest Tier 2 section(s) are extracted (usually Full API Reference or Full Type Definitions)
+- Quick Start, Key API Summary, Key Types, Migration Warnings stay inline
+- Agent accuracy remains high for common tasks
+- tessl scores reflect actual inline content quality
+
+## Split-Body Detection Pattern
+
+A split-body skill is identified by:
+1. A `references/` directory exists alongside SKILL.md
+2. SKILL.md Tier 2 sections (headings starting with `## Full`) contain only stubs or are absent — their content lives in `references/*.md`
+3. The skill's full documented content spans SKILL.md + `references/*.md`
+
+When processing a split-body skill, any workflow step that reads SKILL.md content must also traverse `references/*.md` to get the complete picture.
+
+## Recommended Approach
+
+When `body.max_lines` is exceeded:
+1. Identify which Tier 2 section(s) are largest (usually `## Full API Reference`)
+2. Extract only those specific sections to `references/`
+3. Keep all Tier 1 sections and smaller Tier 2 sections inline
+4. Verify context snippet anchors still resolve after extraction
+
+## Scripts and Assets Interaction
+
+Split-body affects only SKILL.md content movement to `references/`. The `scripts/` and `assets/` directories are unaffected — they remain as top-level siblings of SKILL.md regardless of split-body decisions. They do not count toward the body line limit.

package/src/module.yaml

@@ -1,7 +1,7 @@
 code: skf
 name: "SKF: Skill Forge — Evidence-Based Agent Skills Compiler"
-header: "Automated skill compiler — AST-verified, provenance-backed agent skills from code repositories, documentation, and developer discourse"
-subheader: "Zero hallucination tolerance. Every instruction traces to code."
+header: "Turn code and docs into instructions AI agents can actually follow"
+subheader: "Every instruction traces to source. Zero hallucination tolerance."
 description: "Skill Forge transforms code repositories, documentation, and developer discourse into agentskills.io-compliant, version-pinned, provenance-backed agent skills. Uses ast-grep for structural truth, QMD for knowledge intelligence, and a progressive capability model (Quick/Forge/Deep). Standalone module — no other modules required. Recommended alongside BMM for full development workflow integration."
 default_selected: false
 

package/src/workflows/analyze-source/data/skill-brief-schema.md

@@ -24,6 +24,8 @@ Defines the output contract for skill-brief.yaml files generated by analyze-sour
 |-------|------|------------|-------------|
 | source_type | string | `source` or `docs-only` | Default `source`. When `docs-only`: `source_repo` optional, `doc_urls` required |
 | doc_urls | array | `{url, label}` objects | Documentation URLs for T3 content. Required when `source_type: "docs-only"` |
+| `scripts_intent` | string | `detect` / `none` / free-text | Describes whether scripts should be extracted. Values: `detect` (auto-detect from source — default when absent), `none` (skip scripts), or a free-text description of expected scripts (e.g., "CLI validation tools in bin/"). |
+| `assets_intent` | string | `detect` / `none` / free-text | Describes whether assets should be extracted. Values: `detect` (auto-detect from source — default when absent), `none` (skip assets), or a free-text description of expected assets (e.g., "JSON schemas in schemas/"). |
 
 ## Version Detection
 

package/src/workflows/analyze-source/data/unit-detection-heuristics.md

@@ -70,6 +70,32 @@ Do NOT recommend as a skillable unit if:
 5. **Vendor/dependency**: Third-party code copied into project
 6. **Already skilled**: Existing skill found in forge_data_folder (recommend update-skill instead)
 
+## Script/Asset Detection Signals
+
+During per-unit analysis, check for scripts and assets alongside code exports.
+
+**Script signals:**
+
+| Strength | Signal | Example |
+|----------|--------|---------|
+| Strong | Entry point in `package.json` `bin`, Cargo.toml `[[bin]]`, pyproject.toml `[project.scripts]` | `"bin": { "migrate": "scripts/migrate.js" }` |
+| Strong | Shebang + executable file | `#!/usr/bin/env python` in `scripts/setup.py` |
+| Moderate | File in `scripts/`, `bin/`, `tools/`, `cli/` directory | `scripts/validate.sh` |
+| Moderate | CI/CD reference to script | `.github/workflows/test.yml` runs `scripts/test.sh` |
+
+**Asset signals:**
+
+| Strength | Signal | Example |
+|----------|--------|---------|
+| Strong | JSON Schema file with `$schema` key | `schemas/config.schema.json` |
+| Strong | Config template with `.example` or `.template` extension | `config.yaml.example` |
+| Moderate | File in `assets/`, `templates/`, `schemas/`, `configs/`, `examples/` directory | `templates/report.hbs` |
+| Moderate | OpenAPI/GraphQL definition | `openapi.json`, `schema.graphql` |
+
+**Per-unit output:** Record `has_scripts: boolean`, `has_assets: boolean`, `script_files: string[]`, `asset_files: string[]`.
+
+**Disqualify:** Generated files (dist/, build/), vendored dependencies, IDE configs (.vscode/, .idea/), binary files (.so, .dll, .jar).
+
 ## Stack Skill Candidate Detection
 
 Flag units as stack skill candidates when:

package/src/workflows/analyze-source/steps-c/step-02-scan-project.md

@@ -167,7 +167,7 @@ Replace the placeholder `[Appended by step-02-scan-project]` with the full scan
 
 Update {outputFile} frontmatter:
 ```yaml
-stepsCompleted: ['step-01-init', 'step-02-scan-project']
+stepsCompleted: [append 'step-02-scan-project' to existing array]
 lastStep: 'step-02-scan-project'
 ```
 

package/src/workflows/analyze-source/steps-c/step-03-identify-units.md

@@ -150,7 +150,7 @@ Replace the placeholder `[Appended by step-03-identify-units]` with:
 
 Update {outputFile} frontmatter:
 ```yaml
-stepsCompleted: ['step-01-init', 'step-02-scan-project', 'step-03-identify-units']
+stepsCompleted: [append 'step-03-identify-units' to existing array]
 lastStep: 'step-03-identify-units'
 ```
 

package/src/workflows/analyze-source/steps-c/step-04-map-and-detect.md

@@ -91,13 +91,14 @@ DO NOT BE LAZY — For EACH qualifying unit, launch a subprocess (or analyze in
    - Primary export patterns (barrel exports, direct exports, re-exports)
    - Public API surface size estimate
    - Key entry points
+   - Script/asset presence: check for `scripts/`, `bin/`, `assets/`, `templates/` directories and files matching detection signals in `{heuristicsFile}`. Record counts in per-unit findings.
    - Analysis strategy used and coverage confidence
 
 **Per-unit export summary:**
 
-| Unit | Files | Exports | Export Pattern | API Surface |
-|------|-------|---------|----------------|-------------|
-| {name} | {count} | {count} | {pattern} | {small/medium/large} |
+| Unit | Files | Exports | Export Pattern | API Surface | Scripts/Assets |
+|------|-------|---------|----------------|-------------|----------------|
+| {name} | {count} | {count} | {pattern} | {small/medium/large} | {N scripts, M assets or --} |
 
 ### 3. Map Import Graph
 
@@ -187,7 +188,7 @@ Replace `[Appended by step-04-map-and-detect]` under Integration Points with:
 
 Update {outputFile} frontmatter:
 ```yaml
-stepsCompleted: ['step-01-init', 'step-02-scan-project', 'step-03-identify-units', 'step-04-map-and-detect']
+stepsCompleted: [append 'step-04-map-and-detect' to existing array]
 lastStep: 'step-04-map-and-detect'
 stack_skill_candidates: [{list flagged candidate groupings}]
 ```

package/src/workflows/analyze-source/steps-c/step-05-recommend.md

@@ -181,7 +181,7 @@ Replace `[Appended by step-05-recommend]` with:
 
 Update {outputFile} frontmatter:
 ```yaml
-stepsCompleted: ['step-01-init', 'step-02-scan-project', 'step-03-identify-units', 'step-04-map-and-detect', 'step-05-recommend']
+stepsCompleted: [append 'step-05-recommend' to existing array]
 lastStep: 'step-05-recommend'
 confirmed_units: [{list of confirmed unit names}]
 stack_skill_candidates: [{updated list with user decisions}]

package/src/workflows/analyze-source/steps-c/step-06-generate-briefs.md

@@ -179,7 +179,7 @@ Replace `[Appended by step-06-generate-briefs]` with:
 
 Update {outputFile} frontmatter:
 ```yaml
-stepsCompleted: ['step-01-init', 'step-02-scan-project', 'step-03-identify-units', 'step-04-map-and-detect', 'step-05-recommend', 'step-06-generate-briefs']
+stepsCompleted: [append 'step-06-generate-briefs' to existing array]
 lastStep: 'step-06-generate-briefs'
 nextWorkflow: '{primary recommendation}'
 ```

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

@@ -99,6 +99,8 @@ Load the following from the skill directory:
 - `name`, `version`, `generation_date`, `confidence_tier` used during creation
 - `source_root` — Resolved source code path used during extraction
 
+**Detect split-body state:** If a `references/` directory exists and SKILL.md's `## Full` headings are absent or stubs, this is a split-body skill. Flag `split_body: true` in the baseline so downstream steps (especially semantic diff in step-04) know to also read `references/*.md` for complete content comparison.
+
 ### 4. Load Provenance Map
 
 Search for provenance map at `{forge_data_folder}/{skill_name}/provenance-map.json`

package/src/workflows/audit-skill/steps-c/step-03-structural-diff.md

@@ -108,6 +108,20 @@ For each changed export, record:
 - What changed (signature / type / location)
 - Confidence tier
 
+### 4b. Detect Script/Asset Drift
+
+**Only execute if provenance-map.json contains `file_entries`.**
+
+For each entry in `file_entries`:
+1. Locate the source file at the original `source_file` path
+2. Compute current SHA-256 content hash
+3. Compare against stored `content_hash`
+- CHANGED: hash mismatch → record as script/asset content drift
+- MISSING: source file no longer exists → record as removed
+- NEW: source contains files matching script/asset patterns not in `file_entries` → record as added
+
+Append results to the Structural Drift section as "### Script/Asset Drift ({count})".
+
 ### 5. Compile Structural Drift Section
 
 Append to {outputFile}:

package/src/workflows/brief-skill/data/scope-templates.md

@@ -58,3 +58,7 @@ Prompt: "Which of these would you like to include? (Enter numbers, or 'all'):"
 
 Exclusions will include all internal implementation files, tests, and utilities.
 Prompt: "Any additional items you'd like to include or exclude?"
+
+## Scripts & Assets Detection (Optional Refinement)
+
+When `scripts_intent` or `assets_intent` is `detect` (default), SKF auto-detects from source directories matching: `scripts/`, `bin/`, `tools/`, `cli/` (for scripts) and `assets/`, `templates/`, `schemas/`, `configs/`, `examples/` (for assets). Detection applies to all scope types except `docs-only`.

package/src/workflows/brief-skill/data/skill-brief-schema.md

@@ -20,6 +20,8 @@
 |-------|------|-------------|------------|
 | source_type | string | Source mode: `source` or `docs-only` | Default `source`. When `docs-only`: `source_repo` optional, `doc_urls` required |
 | doc_urls | array | Documentation URLs for T3 content | Each entry: `{url, label}`. Required when `source_type: "docs-only"` |
+| `scripts_intent` | string | Describes whether scripts should be extracted. Values: `detect` (auto-detect from source — default when absent), `none` (skip scripts), or a free-text description of expected scripts (e.g., "CLI validation tools in bin/"). |
+| `assets_intent` | string | Describes whether assets should be extracted. Values: `detect` (auto-detect from source — default when absent), `none` (skip assets), or a free-text description of expected assets (e.g., "JSON schemas in schemas/"). |
 
 When `source_type: "docs-only"`:
 - `source_repo` becomes optional (set to doc site URL for reference)
@@ -79,6 +81,8 @@ scope:
 # doc_urls:
 #   - url: "https://docs.example.com/api"
 #     label: "API Reference"
+# scripts_intent: detect         # Optional: detect | none | description
+# assets_intent: detect          # Optional: detect | none | description
 ---
 ```
 

package/src/workflows/brief-skill/steps-c/step-03-scope-definition.md

@@ -135,6 +135,18 @@ Does this look right? You can adjust before we continue."
 
 Wait for confirmation. Make adjustments if requested.
 
+### 5b. Scripts & Assets Intent (Optional)
+
+**Only ask when `scope.type` is `full-library` or `specific-modules` (skip for `public-api` and `docs-only`).**
+
+"Does this library include executable scripts (CLI tools, validation scripts, setup helpers) or static assets (config templates, JSON schemas, example configs) that should be packaged with the skill?"
+
+- **[D] Auto-detect** from source (default) — SKF will scan for `scripts/`, `bin/`, `assets/`, `templates/`, `schemas/` directories
+- **[N] None expected** — skip script/asset detection
+- Or describe what you expect (free text)
+
+Record the response as `scripts_intent` and `assets_intent` in the brief. Default to `detect` if user does not respond or skips.
+
 ### 6. Present MENU OPTIONS
 
 Display: **Select an Option:** [A] Advanced Elicitation [P] Party Mode [C] Continue to Brief Confirmation

package/src/workflows/create-skill/data/compile-assembly-rules.md

@@ -14,8 +14,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`, `analyzing-spreadsheets`) for clarity.
+- `description`: non-empty, max 1024 chars, optimized for agent discovery. **MUST use third-person voice** ("Processes Excel files..." not "I can help you..." or "You can use this to..."). Inconsistent point-of-view causes discovery problems since the description is injected into the system prompt.
 - Only `name` and `description` in frontmatter — `version` and `author` go in metadata.json
 - No other frontmatter fields for standard skills (only `name`, `description`, `license`, `compatibility`, `metadata`, `allowed-tools` are permitted by spec)
 
@@ -77,6 +77,14 @@ These sections form the essential standalone body. Target: **under 300 lines tot
 - Basic CLI commands if the library has a CLI interface
 - Skip if no CLI exists
 
+**Section 7b — Scripts & Assets (~10 lines, if applicable):**
+- Manifest table of included scripts with filename, one-line purpose, and provenance citation
+- Manifest table of included assets with filename, one-line purpose, and provenance citation
+- Each entry: `scripts/{filename}` or `assets/{filename}`, purpose, `[SRC:{source_path}:L1]`
+- Include a note: "Load scripts from `scripts/` and assets from `assets/` when directed by the instructions above."
+- **Skip entirely** when no scripts or assets detected in extraction inventory — do not emit an empty section
+- Like Sections 4b and 7, parsers must treat this section as optional
+
 **Section 8 — Manual Sections:**
 - Seed empty `<!-- [MANUAL] -->` markers:
 ```markdown
@@ -108,3 +116,36 @@ Do NOT repeat Tier 1's name/purpose/key-params table format in Tier 2. Tier 2 is
 4. If Tier 1 alone exceeds 300 lines, reduce Key API Summary and Architecture at a Glance
 5. Tier 1 sections are kept short enough that `split-body` targets the larger Tier 2 sections (`## Full ...` headings) instead
 6. After split-body, SKILL.md must still contain all Tier 1 sections with actionable content
+
+### Reference File Rules
+
+- **Table of contents required** for any reference file exceeding 100 lines — include a `## Contents` section at the top listing all sub-sections. This ensures agents can see the full scope even when previewing with partial reads.
+- One file per major function group or type — group by module, file, or functional area
+- Name files descriptively: `form_validation_rules.md`, not `doc2.md`
+
+### Content Quality Rules
+
+These rules apply to all content assembled in SKILL.md and reference files.
+
+**Degrees of freedom:** Match instruction specificity to the task's fragility and variability:
+- **High freedom** (text guidance): When multiple approaches are valid and context determines the best one. Example: code review patterns, architecture suggestions.
+- **Medium freedom** (pseudocode/parameterized scripts): When a preferred pattern exists but variation is acceptable. Example: configuration templates, report generation.
+- **Low freedom** (exact scripts, no parameters): When operations are fragile and consistency is critical. Example: database migrations, deployment sequences. Use "Run exactly this" language.
+
+**Consistent terminology:** Choose one term per concept and use it throughout the skill. Do not mix synonyms (e.g., "API endpoint" vs "URL" vs "route", or "field" vs "box" vs "element"). Consistency helps agents understand and follow instructions deterministically.
+
+**Avoid time-sensitive information:** Do not include date-conditional instructions ("If before August 2025, use the old API"). Instead, document the current method and place deprecated patterns in a collapsible "Old patterns" section with the deprecation date.
+
+**Template and examples patterns:**
+- **For strict requirements** (API responses, data formats): Provide an exact template with "ALWAYS use this exact structure" language.
+- **For flexible guidance** (reports, analysis): Provide a sensible default template with "Adjust sections as needed" language.
+- **Input/output examples:** When output quality depends on seeing examples and concrete pairs exist in source tests or official docs, include 2-3 input/output pairs sourced from those tests or docs. Examples help agents understand desired style and detail more clearly than descriptions alone. If no examples exist in source, note the gap rather than fabricating pairs — zero hallucination applies.
+
+**Workflow checklist pattern:** When a skill includes multi-step workflows, provide a copy-paste checklist that agents can track progress against:
+```markdown
+Copy this checklist and track your progress:
+- [ ] Step 1: {action}
+- [ ] Step 2: {action}
+```
+
+**Verifiable intermediate outputs:** For skills involving batch operations, destructive changes, or complex validation, recommend the plan-validate-execute pattern: create a structured plan file (e.g., `changes.json`), validate it with a script, then execute. This catches errors before changes are applied.