bmad-module-skill-forge 0.3.0 → 0.4.0

package/README.md

@@ -4,7 +4,7 @@
 
 # Skill Forge (SKF)
 
-**Agent Skill Compiler — AST-verified, version-pinned, zero hallucination**
+**Turn code and docs into instructions AI agents can actually follow.**
 
 [![Quality & Validation](https://github.com/armelhbobdad/bmad-module-skill-forge/actions/workflows/quality.yaml/badge.svg)](https://github.com/armelhbobdad/bmad-module-skill-forge/actions/workflows/quality.yaml)
 [![npm](https://img.shields.io/npm/v/bmad-module-skill-forge)](https://www.npmjs.com/package/bmad-module-skill-forge)
@@ -13,7 +13,7 @@
 [![Docs](https://img.shields.io/badge/docs-online-green)](https://armelhbobdad.github.io/bmad-module-skill-forge/)
 [![GitHub stars](https://img.shields.io/github/stars/armelhbobdad/bmad-module-skill-forge?style=social)](https://github.com/armelhbobdad/bmad-module-skill-forge/stargazers)
 
-*Transforms code repositories, documentation, and developer discourse into [agentskills.io](https://agentskills.io)-compliant agent skills with AST-backed provenance.*
+*Skill Forge analyzes your code repositories, documentation, and developer discourse to build verified instruction files for AI agents. Every instruction links back to where it came from — nothing is made up.*
 
 **If SKF helps your agent stop hallucinating, give it a ⭐ — it helps others find this tool.**
 
@@ -21,208 +21,78 @@
 
 ---
 
-SKF is a standalone BMAD module that provides a single expert agent (Ferris, Skill Architect & Integrity Guardian) and ten workflows spanning source analysis, skill briefing, AST-backed compilation, integrity testing, and ecosystem-ready export across progressive capability tiers (Quick/Forge/Deep).
+## The Problem
 
-## Why SKF
+You ask an AI agent to use a library. It invents function names that don't exist. It guesses parameter types. You paste documentation into the context — it still gets details wrong. You write instructions by hand — they go stale the moment the code changes.
 
-- AST-verified instructions with line-level provenance — no hallucinated guidance
-- Progressive capability model that meets developers where they are
-- Full lifecycle: discover, brief, compile, test, audit, update, export
-- Version-pinned skills that track source changes and detect drift
-- Zero hallucination tolerance — every instruction traces to code
+This isn't an edge case. It's the default experience.
 
-## How BMad Works
+## How Skill Forge Fixes This
 
-BMad works because it turns big, fuzzy work into **repeatable workflows**. Each workflow is broken into small steps with clear instructions, so the AI follows the same path every time. It also uses a **shared knowledge base** (standards and patterns) so outputs are consistent, not random. In short: **structured steps + shared standards = reliable results**.
+1. **Analyzes your sources** — extracts real function signatures, types, and patterns from code repositories, documentation websites, and developer discourse
+2. **Compiles verified instruction files** — every instruction links to the exact file and line it came from
+3. **Follows an open standard** — skills comply with the [agentskills.io](https://agentskills.io) spec and work across Claude, Cursor, Copilot, and other AI agents
 
-## How SKF Fits In
+## Before vs After
 
-SKF plugs into BMad the same way a specialist plugs into a team. It uses the same step-by-step workflow engine and shared standards, but focuses exclusively on skill compilation and quality assurance. That means you get **evidence-based agent skills**, **AST-verified instructions**, and **drift detection** that align with the rest of the BMad process.
+**Without SKF** — your agent guesses:
 
-## Architecture & Flow
+```python
+import cognee
 
-BMad is a small **agent + workflow engine**. There is no external orchestrator — everything runs inside the LLM context window through structured instructions.
-
-### Building Blocks
-
-Each workflow directory contains these files, and each has a specific job:
-
-| File                      | What it does                                                                                                        | When it loads                                     |
-|---------------------------|---------------------------------------------------------------------------------------------------------------------|---------------------------------------------------|
-| `forger.agent.yaml`       | Expert persona — identity, principles, critical actions, menu of triggers                                           | First — always in context                         |
-| `workflow.md`             | Human-readable entry point — goals, mode menu (Create/Edit/Validate), routes to first step                          | Second — presents mode choice                     |
-| `steps-c/*.md`            | **Create** steps — primary execution, 4-9 sequential files                                                          | One at a time (just-in-time)                      |
-| `data/*.md`               | Workflow-specific reference data — schemas, heuristics, rules, patterns                                             | Read by steps on demand                           |
-| `templates/*.md`          | Output skeletons with placeholder vars — steps fill these in to produce the final artifact                          | Read by steps when generating output              |
-| `skf-knowledge-index.csv` | Knowledge fragment index — id, name, tags, tier, file path                                                          | Read by steps to decide which fragments to load   |
-| `knowledge/*.md`          | 10 reusable fragments — cross-cutting principles and patterns (e.g., `zero-hallucination.md`, `confidence-tiers.md`) | Selectively read into context when a step directs |
-
-```mermaid
-flowchart LR
-  U[User] --> A[Agent Persona]
-  A --> W[Workflow Entry: workflow.md]
-  W --> S[Step Files: steps-c/]
-  S --> K[Knowledge Fragments<br/>skf-knowledge-index.csv → knowledge/*.md]
-  S --> D[Data & Templates<br/>data/*.md, templates/*.md]
-  S --> O[Outputs: skills/reports<br/>when a step writes output]
+# Agent hallucinates: sync call, wrong parameter name, missing await
+results = cognee.search("What does Cognee do?", mode="graph")
 ```
 
-### How It Works at Runtime
-
-1. **Trigger** — User types `@Ferris CS` (or fuzzy match like `create-skill`). The agent menu in `forger.agent.yaml` maps the trigger to the workflow path.
-2. **Agent loads** — `forger.agent.yaml` injects the persona (identity, principles, critical actions) into the context window. Sidecar files (`forge-tier.yaml`, `preferences.yaml`) are loaded for persistent state.
-3. **Workflow loads** — `workflow.md` presents the mode choice and routes to the first step file.
-4. **Step-by-step execution** — Only the current step file is in context (just-in-time loading). Each step explicitly names the next one. The LLM reads, executes, saves output, then loads the next step. No future steps are ever preloaded.
-5. **Knowledge injection** — Steps consult `skf-knowledge-index.csv` and selectively load fragments from `knowledge/` by tags and relevance. Cross-cutting principles (zero hallucination, confidence tiers, provenance) are loaded only when a step directs — not preloaded.
-6. **Data injection** — Steps read `data/*.md` files as needed (schemas, heuristics, extraction patterns). This is deliberate context engineering: only the data relevant to the current step enters the context window.
-7. **Templates** — When a step produces output (e.g., a skill brief or test report), it reads the template file and fills in placeholders with computed results. The template provides consistent structure; the step provides the content.
-8. **Progress tracking** — Each step appends to an output file with state tracking. Resume mode reads this state and routes to the next incomplete step.
+**With SKF** — your agent reads the verified skill:
 
-### Ferris Operating Modes
+```python
+import cognee
 
-Ferris operates in four workflow-driven modes (mode is determined by which workflow is running, not conversation state):
+# Agent follows the skill instruction:
+# `search(query_text: str, query_type: SearchType = GRAPH_COMPLETION) -> List[SearchResult]`
+# [AST:cognee/api/v1/search/search.py:L26]
+results = await cognee.search(
+    query_text="What does Cognee do?",
+    query_type=cognee.SearchType.GRAPH_COMPLETION
+)
+```
 
-| Mode          | Workflows          | Behavior                                                    |
-|---------------|--------------------|-------------------------------------------------------------|
-| **Architect** | SF, AN, BS, CS, QS, SS | Exploratory, assembling — discovers structure and scope     |
-| **Surgeon**   | US                 | Precise, preserving — extracts and compiles with provenance |
-| **Audit**     | AS, TS             | Judgmental, scoring — evaluates quality and detects drift   |
-| **Delivery**  | EX                 | Packaging, ecosystem-ready — bundles for distribution       |
+The skill told the agent the real function name, the real parameters, and that the call requires `await` — all traced to the exact source line. This is from a [real generated skill](https://github.com/armelhbobdad/oh-my-skills).
 
 ## Install
 
 Requires [Node.js](https://nodejs.org/) >= 22.
 
-There are three ways to install SKF, depending on your setup.
-
-### Method 1: Standalone (recommended for trying SKF)
-
-```bash
-npx bmad-module-skill-forge install
-```
-
-Installs SKF on its own. You'll be prompted for project name, output folders, and which IDEs to configure. The installer generates IDE-specific command files (e.g. `.claude/commands/`, `.cursor/commands/`) so workflows appear in your IDE's command palette.
-
-### Method 2: As a custom module during BMad Method installation
-
-```bash
-npx bmad-method install
-```
-
-When prompted **"Add custom modules from your computer?"**, select Yes and provide the path to the SKF `src/` folder (clone this repo first):
-
-```
-Path to custom module folder: /path/to/bmad-module-skill-forge/src/
-```
-
-This installs BMad core + SKF together with full IDE integration, manifests, and help catalog. Best when you want the complete BMad development workflow.
-
-### Method 3: Add SKF to an existing BMad project
-
-If you already have BMad installed, you can add SKF afterward by running the standalone installer in the same directory:
-
 ```bash
 npx bmad-module-skill-forge install
 ```
 
-The installer detects the existing `_bmad/` directory and installs SKF alongside your current modules. IDE command files are generated for SKF workflows.
-
-## Quickstart
-
-1. **Setup your forge:** `@Ferris SF` — detects tools, sets your tier (Quick/Forge/Deep)
-2. **Quick skill (fastest):** `@Ferris QS <package-name>` — fast skill from a package name
-3. **Full skill:** `@Ferris BS` then `@Ferris CS` — brief then compile for maximum quality
-4. **Stack skill:** `@Ferris SS` — consolidated project stack skill with integration patterns
-5. **Export:** `@Ferris EX` — package for distribution, update CLAUDE.md
-
-## Workflows
-
-| Trigger | Command | Purpose |
-| --- | --- | --- |
-| SF | `skf_setup_forge` | Initialize forge environment, detect tools, set tier |
-| AN | `skf_analyze_source` | Discover what to skill in a large repo |
-| BS | `skf_brief_skill` | Design a skill scope through guided discovery |
-| CS | `skf_create_skill` | Compile a skill from brief (supports --batch) |
-| QS | `skf_quick_skill` | Fast skill from package name or GitHub URL |
-| SS | `skf_create_stack_skill` | Consolidated project stack skill with integration patterns |
-| US | `skf_update_skill` | Smart regeneration preserving \[MANUAL\] sections |
-| AS | `skf_audit_skill` | Drift detection between skill and current source |
-| TS | `skf_test_skill` | Cognitive completeness verification — quality gate before export |
-| EX | `skf_export_skill` | Package for distribution, inject into CLAUDE.md/AGENTS.md |
-
-## Progressive Capability Model
-
-| Tier | Tools | Capability |
-| --- | --- | --- |
-| **Quick** | gh + skill-check + tessl | Source reading + spec validation + content quality review |
-| **Forge** | + ast-grep | Structural truth, T1 confidence |
-| **Deep** | + QMD | Knowledge search, temporal provenance |
-
-The `setup-forge` workflow detects available tools and writes the tier to `forge-tier.yaml`. All subsequent workflows adapt their behavior to the detected tier.
-
-> **Recommended:** If your IDE supports MCP servers, install the [ast-grep MCP server](https://github.com/ast-grep/ast-grep-mcp) alongside the CLI. SKF's extraction protocol prefers the MCP tool for compact, memory-efficient AST queries and falls back to CLI streaming for large codebases.
+You'll be prompted for project name, output folders, and IDE configuration. See the [docs](https://armelhbobdad.github.io/bmad-module-skill-forge/getting-started/) for other install methods.
 
-### Security Scanning (Optional)
+## Quick Start
 
-`skill-check` includes security scanning via [Snyk Agent Scan](https://github.com/snyk/agent-scan) to check for prompt injection risks, sensitive data exposure, and unsafe tool permissions. To enable:
+1. **Set up your environment:** `@Ferris SF` — detects your tools and sets your capability tier
+2. **Generate your first skill:** `@Ferris QS <package-name>` — creates a verified skill in under a minute
+3. **Full quality path:** `@Ferris BS` then `@Ferris CS` — brief first, then compile for maximum accuracy
 
-1. You need a Snyk account with API access — the Snyk API requires an **Enterprise plan** (see [Snyk API authentication docs](https://docs.snyk.io/snyk-api/authentication-for-api))
-2. Copy your API token from Account Settings
-3. Add to your environment: `export SNYK_TOKEN=your-token`
-4. Re-run `@Ferris SF` to detect the token
+See the [workflows docs](https://armelhbobdad.github.io/bmad-module-skill-forge/workflows/) for all 10 available workflows.
 
-> **Note:** The Snyk API is not available on free or Team plans. If you don't have an Enterprise account, security scanning will be skipped gracefully — it does not affect your tier level or block skill compilation.
+## Who Is This For?
 
-Security scanning runs automatically during validation. Use `--no-security-scan` to skip.
+- **You use AI agents to write code** and they keep getting API calls wrong — hallucinating function names, guessing parameter types, inventing methods that don't exist
+- **You maintain a library** and want to ship official, verified instruction files so AI agents use your API correctly
+- **You manage a codebase with many dependencies** and want a consolidated "stack skill" that teaches your agent how all the pieces fit together
+- **You use a SaaS API or closed-source tool** with no public code — SKF can generate skills from documentation alone
 
-## Knowledge Base
+## Learn More
 
-SKF relies on a curated skill compilation knowledge base:
-
-- Index: `src/knowledge/skf-knowledge-index.csv`
-- Fragments: `src/knowledge/`
-
-Workflows load only the fragments required for the current task to stay focused and compliant.
-
-## Configuration
-
-SKF variables are defined in `src/module.yaml` and prompted during install:
-
-| Variable               | Purpose                                                                                              | Default                     |
-|------------------------|------------------------------------------------------------------------------------------------------|-----------------------------|
-| `skills_output_folder` | Where generated skills are saved                                                                     | `{project-root}/skills`     |
-| `forge_data_folder`    | Where workspace artifacts are stored                                                                 | `{project-root}/forge-data` |
-| `tier_override`        | Force a specific tier for comparison or testing (in `_bmad/_memory/forger-sidecar/preferences.yaml`) | `~` (auto-detect)           |
-
-Runtime configuration (tool detection, tier, parallel settings) is managed by the `setup-forge` workflow in `forge-tier.yaml`.
-
-## Module Structure
-
-```
-src/
-├── module.yaml
-├── module-help.csv
-├── agents/
-│   └── forger.agent.yaml
-├── forger/
-│   ├── forge-tier.yaml
-│   ├── preferences.yaml
-│   └── README.md
-├── knowledge/
-│   ├── skf-knowledge-index.csv
-│   └── *.md (10 fragments)
-└── workflows/
-    ├── setup-forge/
-    ├── analyze-source/
-    ├── brief-skill/
-    ├── create-skill/
-    ├── quick-skill/
-    ├── create-stack-skill/
-    ├── update-skill/
-    ├── audit-skill/
-    ├── test-skill/
-    └── export-skill/
-```
+- **[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
+- **[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
 
 ## Acknowledgements
 
@@ -242,7 +112,7 @@ SKF builds on these excellent open-source tools:
 
 ## Contributing
 
-See [CONTRIBUTORS.md](CONTRIBUTORS.md) for guidelines.
+See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
 
 ## License
 

package/docs/agents.md

@@ -5,7 +5,7 @@ description: Ferris agent reference — modes, capabilities, menu, and communica
 
 # Agents Reference
 
-SKF includes 1 specialized agent:
+Ferris is the AI agent that runs all SKF workflows. You always interact with Ferris — he switches modes based on which workflow you invoke.
 
 ---
 

package/docs/architecture.md

@@ -1,11 +1,73 @@
 ---
-title: Architecture
-description: How Skill Forge works — output format, confidence model, progressive tiers, tool ecosystem, and key design decisions
+title: How It Works
+description: How Skill Forge works — the BMad framework, architecture, output format, confidence model, progressive tiers, and tool ecosystem
 ---
 
-# Architecture
+# How It Works
 
-This page explains how SKF works under the hood — the output format, confidence model, progressive capability tiers, tool ecosystem, and the design decisions that make every instruction traceable.
+This page is for people who want to understand how SKF works under the hood. It covers the BMad framework, workflow architecture, capability tiers, output format, tool ecosystem, and key design decisions. For plain-English definitions of key terms, see [Concepts](../concepts.md).
+
+---
+
+## How BMad Works
+
+BMad works because it turns big, fuzzy work into **repeatable workflows**. Each workflow is broken into small steps with clear instructions, so the AI follows the same path every time. It also uses a **shared knowledge base** (standards and patterns) so outputs are consistent, not random. In short: **structured steps + shared standards = reliable results**.
+
+## How SKF Fits In
+
+SKF plugs into BMad the same way a specialist plugs into a team. It uses the same step-by-step workflow engine and shared standards, but focuses exclusively on skill compilation and quality assurance. That means you get **evidence-based agent skills**, **AST-verified instructions**, and **drift detection** that align with the rest of the BMad process.
+
+---
+
+## Architecture & Flow
+
+BMad is a small **agent + workflow engine**. There is no external orchestrator — everything runs inside the LLM context window through structured instructions.
+
+### Building Blocks
+
+Each workflow directory contains these files, and each has a specific job:
+
+| File                      | What it does                                                                                                        | When it loads                                     |
+|---------------------------|---------------------------------------------------------------------------------------------------------------------|---------------------------------------------------|
+| `forger.agent.yaml`       | Expert persona — identity, principles, critical actions, menu of triggers                                           | First — always in context                         |
+| `workflow.md`             | Human-readable entry point — goals, mode menu (Create/Edit/Validate), routes to first step                          | Second — presents mode choice                     |
+| `steps-c/*.md`            | **Create** steps — primary execution, 4-9 sequential files                                                          | One at a time (just-in-time)                      |
+| `data/*.md`               | Workflow-specific reference data — schemas, heuristics, rules, patterns                                             | Read by steps on demand                           |
+| `templates/*.md`          | Output skeletons with placeholder vars — steps fill these in to produce the final artifact                          | Read by steps when generating output              |
+| `skf-knowledge-index.csv` | Knowledge fragment index — id, name, tags, tier, file path                                                          | Read by steps to decide which fragments to load   |
+| `knowledge/*.md`          | 10 reusable fragments — cross-cutting principles and patterns (e.g., `zero-hallucination.md`, `confidence-tiers.md`) | Selectively read into context when a step directs |
+
+```mermaid
+flowchart LR
+  U[User] --> A[Agent Persona]
+  A --> W[Workflow Entry: workflow.md]
+  W --> S[Step Files: steps-c/]
+  S --> K[Knowledge Fragments<br/>skf-knowledge-index.csv → knowledge/*.md]
+  S --> D[Data & Templates<br/>data/*.md, templates/*.md]
+  S --> O[Outputs: skills/reports<br/>when a step writes output]
+```
+
+### How It Works at Runtime
+
+1. **Trigger** — User types `@Ferris CS` (or fuzzy match like `create-skill`). The agent menu in `forger.agent.yaml` maps the trigger to the workflow path.
+2. **Agent loads** — `forger.agent.yaml` injects the persona (identity, principles, critical actions) into the context window. Sidecar files (`forge-tier.yaml`, `preferences.yaml`) are loaded for persistent state.
+3. **Workflow loads** — `workflow.md` presents the mode choice and routes to the first step file.
+4. **Step-by-step execution** — Only the current step file is in context (just-in-time loading). Each step explicitly names the next one. The LLM reads, executes, saves output, then loads the next step. No future steps are ever preloaded.
+5. **Knowledge injection** — Steps consult `skf-knowledge-index.csv` and selectively load fragments from `knowledge/` by tags and relevance. Cross-cutting principles (zero hallucination, confidence tiers, provenance) are loaded only when a step directs — not preloaded.
+6. **Data injection** — Steps read `data/*.md` files as needed (schemas, heuristics, extraction patterns). This is deliberate context engineering: only the data relevant to the current step enters the context window.
+7. **Templates** — When a step produces output (e.g., a skill brief or test report), it reads the template file and fills in placeholders with computed results. The template provides consistent structure; the step provides the content.
+8. **Progress tracking** — Each step appends to an output file with state tracking. Resume mode reads this state and routes to the next incomplete step.
+
+### Ferris Operating Modes
+
+Ferris operates in four workflow-driven modes (mode is determined by which workflow is running, not conversation state):
+
+| Mode          | Workflows          | Behavior                                                    |
+|---------------|--------------------|-------------------------------------------------------------|
+| **Architect** | SF, AN, BS, CS, QS, SS | Exploratory, assembling — discovers structure and scope     |
+| **Surgeon**   | US                 | Precise, preserving — extracts and compiles with provenance |
+| **Audit**     | AS, TS             | Judgmental, scoring — evaluates quality and detects drift   |
+| **Delivery**  | EX                 | Packaging, ecosystem-ready — bundles for distribution       |
 
 ---
 
@@ -22,7 +84,7 @@ AI agents hallucinate APIs. Not sometimes — constantly. The table below shows
 | Copilot/Cursor built-in | Convenient | Generic. Doesn't know YOUR integration patterns. |
 | **Skill Forge** | **Structural truth + automation** | **Rigid. (Feature, not bug.)** |
 
-SKF solves this by mechanically extracting function signatures, type definitions, and usage patterns from source code — then compiling them into verifiable, version-pinned skills that comply with the [agentskills.io specification](https://agentskills.io/specification).
+SKF solves this by mechanically extracting function signatures, type definitions, and usage patterns from code repositories — and enriching them with documentation and developer discourse — then compiling everything into verifiable, version-pinned skills that comply with the [agentskills.io specification](https://agentskills.io/specification).
 
 ---
 
@@ -311,6 +373,45 @@ Provenance maps enable verification: an `official` skill's provenance must trace
 
 ---
 
+## Knowledge Base
+
+SKF relies on a curated skill compilation knowledge base:
+
+- Index: `src/knowledge/skf-knowledge-index.csv`
+- Fragments: `src/knowledge/`
+
+Workflows load only the fragments required for the current task to stay focused and compliant.
+
+## Module Structure
+
+```
+src/
+├── module.yaml
+├── module-help.csv
+├── agents/
+│   └── forger.agent.yaml
+├── forger/
+│   ├── forge-tier.yaml
+│   ├── preferences.yaml
+│   └── README.md
+├── knowledge/
+│   ├── skf-knowledge-index.csv
+│   └── *.md (10 fragments)
+└── workflows/
+    ├── setup-forge/
+    ├── analyze-source/
+    ├── brief-skill/
+    ├── create-skill/
+    ├── quick-skill/
+    ├── create-stack-skill/
+    ├── update-skill/
+    ├── audit-skill/
+    ├── test-skill/
+    └── export-skill/
+```
+
+---
+
 ## Security
 
 - All tool wrappers use array-style subprocess execution — no shell interpolation

package/docs/concepts.md

@@ -0,0 +1,96 @@
+---
+title: Concepts
+description: Plain-English definitions of key Skill Forge terms — agent skills, provenance, confidence tiers, drift, and more
+---
+
+# Concepts
+
+This page defines the key terms you'll encounter in Skill Forge. Each one is explained in plain English with a concrete example.
+
+---
+
+## Agent Skills
+
+An agent skill is an instruction file that tells an AI agent how to use your code. Instead of the agent guessing your API from its training data, it reads the skill and gets real function names, real parameter types, and real usage patterns.
+
+Skills follow the [agentskills.io](https://agentskills.io) open standard, so they work across Claude, Cursor, Copilot, and other AI tools.
+
+**Example:** A skill for `better-auth` tells your agent: "The function is `authClient.signIn.email()`, it takes `{ email: string, password: string }`, and it returns a `Promise<Session>`. Here's the source: `src/client.ts:L47`."
+
+---
+
+## Provenance
+
+Provenance means every instruction in a skill traces back to where it came from. For code, that's a file and line number. For documentation, it's a URL. For developer discourse, it's an issue or PR reference. If SKF can't point to a source, it doesn't include the instruction.
+
+**Examples** (from a [real generated skill](https://github.com/armelhbobdad/oh-my-skills)):
+- `[AST:cognee/api/v1/search/search.py:L26]` — extracted from source code via AST parsing
+- `[SRC:cognee/api/v1/session/__init__.py:L8]` — read from source code without AST verification
+- `[EXT:docs.cognee.ai/getting-started/quickstart]` — sourced from external documentation
+- `[QMD:cognee-temporal:issues.md]` — surfaced from indexed developer discourse
+
+---
+
+## Confidence Tiers (T1/T2/T3)
+
+Each piece of information in a skill carries a confidence level based on where it came from:
+
+- **T1 — AST extraction:** Pulled directly from source code via AST parsing. This is structural truth — the function signature actually exists in the code right now.
+- **T2 — Evidence:** Found in issues, PRs, changelogs, or documentation within the repository. Reliable context, but not as definitive as code.
+- **T3 — External:** Pulled from external documentation or websites. Treated with caution and clearly marked.
+
+**Example:** A function signature is T1. A deprecation warning from a closed GitHub issue is T2. A usage example from a blog post is T3.
+
+---
+
+## Capability Tiers (Quick/Forge/Deep)
+
+Your capability tier depends on which tools you have installed. Each tier builds on the previous one:
+
+- **Quick** — GitHub CLI only. SKF reads source files and builds best-effort skills. Works in under a minute.
+- **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.
+
+---
+
+## Drift
+
+Drift happens when the source code changes but the skill instructions haven't been updated to match. A skill might still reference a function that was renamed, removed, or had its signature changed.
+
+SKF detects drift by comparing the skill's recorded provenance against the current code. The `audit-skill` workflow (`@Ferris AS`) scans for these mismatches.
+
+**Example:** Your skill says `createUser(name: string)` but the function was renamed to `registerUser(name: string, email: string)` in the last release. That's drift.
+
+---
+
+## Version Pinning
+
+Every skill records the exact version (or commit) of the source code it was built from. This means you always know which version of the library the instructions apply to.
+
+When the source updates, you can re-run `@Ferris US` (update-skill) to regenerate the skill for the new version while preserving any manual additions you've made.
+
+---
+
+## BMAD Module
+
+SKF is a plugin (called a "module") for the [BMad Method](https://github.com/bmad-code-org/BMAD-METHOD), a framework for running structured AI workflows. BMad provides the workflow engine — step-by-step execution, shared knowledge bases, and consistent outputs. SKF plugs into that engine and focuses specifically on skill compilation.
+
+You don't need to know BMad to use SKF. The standalone installer sets everything up.
+
+---
+
+## Ferris
+
+Ferris is the AI agent persona that runs all SKF workflows. When you type `@Ferris CS`, you're telling Ferris to run the create-skill workflow.
+
+Ferris switches between four modes depending on which workflow is active: Architect (exploring and building), Surgeon (precise updates), Audit (quality checks), and Delivery (packaging for distribution).
+
+---
+
+## Zero Hallucination
+
+SKF's core principle: if an instruction can't be traced back to actual source code, it doesn't get included in the skill. This is the opposite of how most AI tools work — they generate plausible-sounding content from training data. SKF only includes what it can verify.
+
+This doesn't mean skills are perfect. Quick-tier skills read source files without AST verification, so they rely on best-effort extraction. But even Quick skills cite their sources, and no tier includes invented information.

package/docs/examples.md

@@ -9,6 +9,45 @@ This section provides practical examples for using SKF: Skill Forge.
 
 ---
 
+## What the Output Looks Like
+
+When SKF generates a skill, you get a `SKILL.md` file with machine-readable frontmatter and provenance-backed instructions. Here's a trimmed example from a real skill generated for [cognee](https://github.com/topoteretes/cognee) (browse the full output at [oh-my-skills](https://github.com/armelhbobdad/oh-my-skills)):
+
+**Frontmatter (tells AI agents when to load this skill):**
+
+```yaml
+name: cognee
+description: Use when cognee is a Python AI memory engine that transforms
+  documents into knowledge graphs with vector and graph storage for semantic
+  search and reasoning. Use this skill when writing code that calls cognee's
+  Python API (add, cognify, search, memify, config, datasets, prune, session).
+```
+
+**Body (what your AI agent reads):**
+
+```
+## Key API Summary
+
+| Function | Purpose | Key Params | Source |
+|----------|---------|------------|--------|
+| add() | Ingest text, files, binary data | data, dataset_name | [AST:cognee/api/v1/add/add.py:L22] |
+| cognify() | Build knowledge graph | datasets, graph_model | [AST:cognee/api/v1/cognify/cognify.py:L47] |
+| search() | Query knowledge graph | query_text, query_type | [AST:cognee/api/v1/search/search.py:L26] |
+| memify() | Enrich graph with custom tasks | extraction_tasks, data | [AST:cognee/modules/memify/memify.py:L27] |
+| session.* | Session history and feedback | get_session(), add_feedback() | [SRC:cognee/api/v1/session/__init__.py:L8] |
+| DataPoint | Base class for custom graph nodes | inherit and add fields | [EXT:docs.cognee.ai/guides/custom-data-models] |
+```
+
+Provenance tags trace each instruction to its source:
+- `[AST:file:line]` — extracted from code via AST parsing (highest confidence)
+- `[SRC:file:line]` — read from source code without AST verification
+- `[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.
+
+---
+
 ## Example Workflows
 
 ### Quick Skill — 47 Seconds

package/docs/getting-started.md

@@ -11,7 +11,7 @@ Welcome to Skill Forge! This guide will help you get up and running.
 
 ## What This Module Does
 
-Skill Forge is an automated skill compiler for the AI agent ecosystem. It transforms code repositories, documentation websites, and developer discourse into agentskills.io-compliant, version-pinned, provenance-backed agent skills. Every instruction traces to actual code — zero hallucination tolerance.
+Skill Forge analyzes code repositories, documentation websites, and developer discourse to build verified instruction files ("skills") for AI agents. Instead of your agent guessing API calls from training data, it follows instructions where every function, type, and pattern traces back to its source — a file and line for code, a URL for documentation, an issue or PR for discourse. Skills comply with the [agentskills.io](https://agentskills.io) open standard and work across Claude, Cursor, Copilot, and other AI tools. See the [Concepts](../concepts.md) page for definitions of key terms.
 
 ---
 
@@ -68,6 +68,20 @@ Don't worry if you don't have all tools — SKF detects what's available and set
 
 ---
 
+## Configuration
+
+SKF has two install-time variables (defined in `src/module.yaml`) and one runtime preference:
+
+| Variable               | Purpose                                                                                              | Default                     |
+|------------------------|------------------------------------------------------------------------------------------------------|-----------------------------|
+| `skills_output_folder` | Where generated skills are saved                                                                     | `{project-root}/skills`     |
+| `forge_data_folder`    | Where workspace artifacts are stored                                                                 | `{project-root}/forge-data` |
+| `tier_override`        | Force a specific tier for comparison or testing (in `_bmad/_memory/forger-sidecar/preferences.yaml`) | `~` (auto-detect)           |
+
+Runtime configuration (tool detection, tier, parallel settings) is managed by the `setup-forge` workflow in `forge-tier.yaml`.
+
+---
+
 ## First Steps
 
 ### 1. Setup Your Forge

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](./architecture/)** — 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.4.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/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/create-skill/data/extraction-patterns.md

@@ -26,13 +26,16 @@ Source reading via gh_bridge — infer exports from file structure and content.
 
 ## Forge Tier (AST Available)
 
-Structural extraction via ast_bridge — verified exports with line-level citations.
+Structural extraction via ast-grep — verified exports with line-level citations.
+
+> **Note:** `ast_bridge.*` and `qmd_bridge.*` references below are **conceptual interfaces**, not callable functions. They describe the operation to perform. Use ast-grep (MCP tool or CLI) for `ast_bridge.*` operations and QMD (MCP tool or CLI) for `qmd_bridge.*` operations. See the AST Extraction Protocol section below and the TOOL/SUBPROCESS FALLBACK rule for dispatch details.
 
 ### Strategy
+
 1. Detect language from brief or file extensions
-2. `ast_bridge.scan_definitions(path, language)` — extract all exports
+2. Use ast-grep to extract all exports from `path` for the given `language` (scan definitions)
 3. For each export: function name, full signature, parameter types, return type, line number
-4. `ast_bridge.detect_co_imports(path, libraries[])` — find integration points
+4. Use ast-grep to detect co-imported symbols in `path` for the given `libraries[]`
 5. Build extraction rules YAML for reproducibility
 
 ### Confidence
@@ -130,7 +133,8 @@ When MCP tools are unavailable or the repo exceeds 500 files in scope, use `--js
 # Patterns are matched against the full file path as emitted by ast-grep.
 # Ensure paths are relative to the same root as the patterns (strip ./ prefix if needed).
 ast-grep -p '{pattern}' -l {language} --json=stream {path} | python3 -c "
-import sys, json, fnmatch
+import sys, json, fnmatch, signal
+signal.signal(signal.SIGPIPE, signal.SIG_DFL)
 
 EXCLUDES = {exclude_patterns}
 
@@ -242,6 +246,7 @@ After initial AST extraction, some top-level exports may resolve to **module imp
 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}]`
 
@@ -253,6 +258,14 @@ from .api.v1.delete import delete    # delete/ is a directory → read delete/__
 
 # 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."
@@ -261,51 +274,3 @@ from .api.v1.add.add import add      # add.py exists with def add()
 
 **Other languages:** JS/TS barrel files (`index.ts` with `export { X } from './module'`) follow the same principle — trace the re-export to the definition file. Rust `pub use` and Go package-level re-exports are less common but follow the same heuristic when encountered.
 
----
-
-## Tier Degradation Rules
-
-### Remote Source at Forge/Deep Tier
-
-When `source_repo` is a remote URL (GitHub URL or owner/repo format) and the tier is Forge or Deep:
-
-- **ast-grep requires local files** — it cannot operate on remote URLs
-
-**Ephemeral clone strategy (preferred):**
-
-1. Check `git` availability (`git --version`). `git` is effectively guaranteed at Deep tier (via `gh` dependency) but NOT guaranteed at Forge tier.
-2. If `git` is available: perform an ephemeral shallow clone to a system temp path (`{system_temp}/skf-ephemeral-{skill-name}-{timestamp}/`).
-3. For create-skill: use `--depth 1 --single-branch --filter=blob:none`; if `include_patterns` are specified, apply mode selection: if `exclude_patterns` are absent, use cone mode (convert include_patterns to directory roots; use `--skip-checks` for individual file paths); if `exclude_patterns` are present, use `--no-cone` mode (pass gitignore-style patterns with `!`-prefixed excludes — includes first, then negations). See source-resolution-protocols.md for the full conversion rules.
-4. For update-skill: use sparse-checkout with `--skip-checks` scoped to the changed files from the change manifest only (file paths require `--skip-checks`). No `--branch` flag — uses the remote default branch (must match the branch used during original create-skill run).
-5. If clone succeeds: use the local clone path for AST extraction. All results are T1 with `[AST:...]` citations.
-6. Cleanup: delete the temp directory after extraction inventory is built and all data is in context. The clone never persists beyond the extraction step.
-
-**Fallback (clone fails or `git` unavailable):**
-
-- The extraction step MUST warn the user explicitly before degrading
-- **create-skill:** Warning must include actionable guidance — clone locally and update `source_repo` in the brief to the local path
-- **update-skill:** Warning must include actionable guidance — clone locally, re-run [CS] Create Skill with the local path to regenerate provenance data, then re-run the update
-- Extraction proceeds using Quick tier strategy (source reading via gh_bridge)
-- All results labeled T1-low with `[SRC:...]` citations
-- The degradation reason is recorded in the evidence report
-
-Silent degradation is **forbidden**. The user must always know when AST extraction was skipped and why.
-
-### AST Tool Unavailable at Forge/Deep Tier
-
-When the tier is Forge or Deep but ast-grep is not functional:
-
-- The extraction step MUST warn the user explicitly before degrading
-- Warning must include actionable guidance: run [SF] Setup Forge to detect tools
-- Extraction proceeds using Quick tier strategy
-- All results labeled T1-low
-- The degradation reason is recorded in the evidence report
-
-### Per-File AST Failure
-
-When ast-grep fails on an individual file (parse error, unsupported syntax):
-
-- Fall back to source reading for **that file only**
-- Other files continue with AST extraction
-- The affected file's results are labeled T1-low; unaffected files retain T1
-- Log a warning noting which file degraded and why

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

@@ -125,7 +125,7 @@ Indexed pipe-delimited format for CLAUDE.md managed section (~80-120 tokens per
   "tool_versions": {
     "ast_grep": "{version-or-null}",
     "qmd": "{version-or-null}",
-    "skf": "1.0.0"
+    "skf": "{skf_version}"
   },
   "stats": {
     "exports_documented": 0,
@@ -204,7 +204,7 @@ Each reference file includes:
 ## Tool Versions
 - ast-grep: {version}
 - QMD: {version}
-- SKF: 1.0.0
+- SKF: {skf_version}
 
 ## Extraction Summary
 - Files scanned: {count}

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

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

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

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

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

@@ -3,6 +3,7 @@ name: 'step-03-extract'
 description: 'Tier-dependent source code extraction — AST or source reading for exports, signatures, and types'
 nextStepFile: './step-03b-fetch-temporal.md'
 extractionPatternsData: '../data/extraction-patterns.md'
+tierDegradationRulesData: '../data/tier-degradation-rules.md'
 sourceResolutionData: '../data/source-resolution-protocols.md'
 ---
 
@@ -104,7 +105,7 @@ Load `{sourceResolutionData}` completely. Follow the **Remote Source Resolution*
 5. Build extraction rules YAML data for reproducibility
 6. Confidence: All results T1 — `[AST:{file}:L{line}]`
 
-**If AST tool is unavailable at Forge/Deep tier:**
+**If AST tool is unavailable at Forge/Deep tier** (see `{tierDegradationRulesData}` for full rules):
 
 ⚠️ **Warn the user explicitly:** "AST tools are unavailable — extraction will use source reading (T1-low). Run [SF] Setup Forge to detect and configure AST tools for T1 confidence."
 

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

@@ -97,7 +97,7 @@ Following the structure from the skill-sections data file:
   - `exports_total`: `exports_public_api` + `exports_internal`
   - `public_api_coverage`: `exports_documented / exports_public_api` (1.0 when all public API exports are documented; `null` if `exports_public_api` is 0)
   - `total_coverage`: `exports_documented / exports_total` (may be low for large codebases — this is expected; `null` if `exports_total` is 0)
-- Set `tool_versions` based on tier and available tools
+- Set `tool_versions` based on tier and available tools. Resolve `{skf_version}` from the SKF module's `package.json` `version` field (run `node -p "require('./node_modules/bmad-module-skill-forge/package.json').version"` or read the installed module's `package.json`). If unresolvable, fall back to `git describe --tags --abbrev=0` in the SKF module root. Never hardcode the version.
 
 ### 5. Build references/ Content
 
@@ -115,7 +115,7 @@ One entry per extracted export: export_name, export_type, params[] (typed string
 
 ### 7. Build evidence-report.md Content
 
-Compilation audit trail: generation date, forge tier, source info, tool versions, extraction summary (files/exports/confidence), validation results (populated in step-06), warnings. See `{skillSectionsData}` for full template.
+Compilation audit trail: generation date, forge tier, source info, tool versions, extraction summary (files/exports/confidence), validation results (populated in step-06), warnings. See `{skillSectionsData}` for full template. Use the same `{skf_version}` value resolved in section 4 when populating the Tool Versions block.
 
 ### 8. Menu Handling Logic
 

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

@@ -40,6 +40,7 @@ To validate the compiled SKILL.md content against the agentskills.io specificati
 - 💾 Validation results are added to evidence-report content in context
 - 📖 Auto-fix pattern: validate → fix → re-validate (once)
 - 🚫 Maximum one auto-fix attempt per validation failure
+- ⏸️ **Conditional interaction:** If tessl returns suggestions (section 6b), halt for user input. Otherwise auto-proceed. This is a conditional gate step, not a pure auto-proceed step.
 
 ## CONTEXT BOUNDARIES:
 
@@ -73,6 +74,8 @@ This performs frontmatter validation, description quality checks, body limit enf
 
 **Parse the JSON output** for: `qualityScore` (0-100), `diagnostics[]` (remaining issues), `fixed[]` (auto-corrected issues).
 
+**Context sync after --fix:** If `fixed[]` is non-empty (i.e., `--fix` modified files on disk), re-read the modified SKILL.md to update the in-context copy. Verify the re-read content matches expectations before proceeding. This prevents silent divergence between the in-context SKILL.md and the on-disk version that step-07 will use for artifact generation.
+
 **Note:** `skill-check` may return non-zero exit code even when `errorCount` is 0. Always rely on parsed JSON, not the shell exit code.
 
 - **Score ≥ 70:** Record "Schema: PASS (score: {score}/100)" in evidence-report
@@ -143,7 +146,7 @@ Parse output for: `description_score`, `content_score`, `average_score`, `valida
 - **Content score < 70%:** Record warning: "Content quality warning: tessl scored content at {score}%."
 - **Unavailable:** Skip with note: "Content quality review skipped — tessl tool unavailable"
 
-**Expected scoring for two-tier design:** The Skill Forge two-tier design (Tier 1 Key API Summary + Tier 2 Full API Reference) intentionally includes progressive disclosure. tessl's `conciseness` scorer may flag this as redundancy (typically scoring 2/3), which is expected behavior — not a defect. Content scores >= 60% are acceptable when both tiers are correctly applied with proper differentiation (see step-05 Tier 2 assembly rules). Do NOT consolidate Tier 1 and Tier 2 content to improve the score — the two-tier structure is a deliberate design choice for standalone usability.
+> **EXPECTED BEHAVIOR — Two-Tier Scoring:** The Skill Forge two-tier design (Tier 1 Key API Summary + Tier 2 Full API Reference) intentionally includes progressive disclosure. tessl's `conciseness` scorer will flag this as redundancy (typically scoring 2/3), which is **expected behavior — not a defect**. tessl may also suggest removing `[MANUAL]` markers, moving Full API Reference to a separate file, or consolidating duplicate parameter documentation — **all three suggestions conflict with SKF design principles and must be dismissed.** Acceptable threshold: content scores >= 60% are normal for two-tier skills. Do NOT consolidate Tier 1 and Tier 2 content to improve the score — the two-tier structure is a deliberate design choice for standalone usability.
 
 tessl installs automatically via `npx`. A missing tool is not an error — graceful skip.
 

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/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-04-coherence-check.md

@@ -168,7 +168,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 +180,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 +197,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,12 @@ 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). If recent results exist (from a create-skill run that just completed), auto-reuse them — skip re-running validators and use the existing scores from the evidence report. Record: "External validation: reused from create-skill evidence report." Skip to section 5 (append results).
+
+If no evidence report exists or it contains no validation section, proceed to section 2 (fresh run).
+
 ### 2. Run skill-check
 
 **Check availability:**

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/{sourceAccessProtocol}'
 ---
 
 # 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/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-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/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();