bmad-module-skill-forge 0.4.0 → 0.5.0

package/README.md

@@ -89,7 +89,7 @@ See the [workflows docs](https://armelhbobdad.github.io/bmad-module-skill-forge/
 
 - **[Getting Started](https://armelhbobdad.github.io/bmad-module-skill-forge/getting-started/)** — Installation, prerequisites, and your first skill
 - **[Concepts](https://armelhbobdad.github.io/bmad-module-skill-forge/concepts/)** — Plain-English definitions of all key terms
-- **[How It Works](https://armelhbobdad.github.io/bmad-module-skill-forge/architecture/)** — Architecture, capability tiers, output format, and design decisions
+- **[How It Works](https://armelhbobdad.github.io/bmad-module-skill-forge/how-it-works/)** — Architecture, capability tiers, output format, and design decisions
 - **[Workflows](https://armelhbobdad.github.io/bmad-module-skill-forge/workflows/)** — All 10 workflows with commands and connection diagrams
 - **[Agents](https://armelhbobdad.github.io/bmad-module-skill-forge/agents/)** — Ferris: the AI agent that runs all SKF workflows
 - **[Examples](https://armelhbobdad.github.io/bmad-module-skill-forge/examples/)** — Real-world scenarios, tips, and troubleshooting

package/docs/concepts.md

@@ -51,7 +51,7 @@ Your capability tier depends on which tools you have installed. Each tier builds
 - **Forge** — Adds [ast-grep](https://ast-grep.github.io). SKF uses AST parsing for structural truth. Instructions are verified against the actual code structure.
 - **Deep** — Adds [QMD](https://github.com/tobi/qmd). SKF indexes knowledge for semantic search. Skills get enriched with historical context, deprecation warnings, and cross-reference intelligence.
 
-You don't need all tools to start. SKF detects what you have and sets your tier automatically. See [How It Works](../architecture.md) for the full technical treatment.
+You don't need all tools to start. SKF detects what you have and sets your tier automatically. See [How It Works](../how-it-works.md) for the full technical treatment.
 
 ---
 

package/docs/examples.md

@@ -44,7 +44,7 @@ Provenance tags trace each instruction to its source:
 - `[EXT:url]` — sourced from external documentation
 - `[QMD:collection:doc]` — surfaced from indexed developer discourse (issues, PRs, changelogs)
 
-See [How It Works](../architecture.md) for the full output structure.
+See [How It Works](../how-it-works.md) for the full output structure.
 
 ---
 

package/docs/index.md

@@ -40,7 +40,7 @@ See the [Getting Started](./getting-started/) guide for full installation and us
 
 - **[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](./architecture/)** — Architecture, capability model, output format, and design decisions
+- **[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

package/package.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json.schemastore.org/package.json",
   "name": "bmad-module-skill-forge",
-  "version": "0.4.0",
+  "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",

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/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.

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

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