bmad-module-skill-forge 0.2.0 → 0.4.0

package/README.md

@@ -1,204 +1,118 @@
-# Skill Forge (SKF)
-
-SKF (Skill Forge) is a standalone BMAD module that transforms code repositories, documentation websites, and developer discourse into agentskills.io-compliant, version-pinned, provenance-backed agent skills. It 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).
-
-Docs: <https://armelhbobdad.github.io/bmad-module-skill-forge/>
-
-## Why SKF
-
-- 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
-
-## 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**.
+<div align="center">
 
-## How SKF Fits In
+<img src="website/public/img/skf-logo.svg" alt="Skill Forge Logo" width="120" />
 
-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.
+# Skill Forge (SKF)
 
-## Architecture & Flow
+**Turn code and docs into instructions AI agents can actually follow.**
 
-BMad is a small **agent + workflow engine**. There is no external orchestrator — everything runs inside the LLM context window through structured instructions.
+[![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)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![BMad Module](https://img.shields.io/badge/BMad-module-blue)](https://github.com/bmad-code-org/BMAD-METHOD)
+[![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)
 
-### Building Blocks
+*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.*
 
-Each workflow directory contains these files, and each has a specific job:
+**If SKF helps your agent stop hallucinating, give it a ⭐ — it helps others find this tool.**
 
-| 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` | 8 reusable fragments — cross-cutting principles and patterns (e.g., `zero-hallucination.md`, `confidence-tiers.md`) | Selectively read into context when a step directs |
+</div>
 
-```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
+## The Problem
 
-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.
+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.
 
-### Ferris Operating Modes
+This isn't an edge case. It's the default experience.
 
-Ferris operates in four workflow-driven modes (mode is determined by which workflow is running, not conversation state):
+## How Skill Forge Fixes This
 
-| Mode | Workflows | Behavior |
-| --- | --- | --- |
-| **Architect** | AN, BS, SF | Exploratory, assembling — discovers structure and scope |
-| **Surgeon** | CS, QS, SS, 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 |
+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
 
-## Install
+## Before vs After
 
-There are three ways to install SKF, depending on your setup.
+**Without SKF** — your agent guesses:
 
-### Method 1: Standalone (recommended for trying SKF)
+```python
+import cognee
 
-```bash
-npx skill-forge install
+# Agent hallucinates: sync call, wrong parameter name, missing await
+results = cognee.search("What does Cognee do?", mode="graph")
 ```
 
-Or equivalently: `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
+**With SKF** — your agent reads the verified skill:
 
-```bash
-npx bmad-method install
-```
+```python
+import cognee
 
-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/
+# 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
+)
 ```
 
-This installs BMad core + SKF together with full IDE integration, manifests, and help catalog. Best when you want the complete BMad development workflow.
+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).
 
-### Method 3: Add SKF to an existing BMad project
+## Install
 
-If you already have BMad installed, you can add SKF afterward by running the standalone installer in the same directory:
+Requires [Node.js](https://nodejs.org/) >= 22.
 
 ```bash
-npx skill-forge install
+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
+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.
 
-## Workflows
+## Quick Start
 
-| 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 |
+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
 
-## Progressive Capability Model
+See the [workflows docs](https://armelhbobdad.github.io/bmad-module-skill-forge/workflows/) for all 10 available workflows.
 
-| Tier | Tools | Capability |
-| --- | --- | --- |
-| **Quick** | gh + skills_ref | Source reading + spec validation |
-| **Forge** | + ast-grep | Structural truth, T1 confidence |
-| **Deep** | + QMD | Knowledge search, temporal provenance |
+## Who Is This For?
 
-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.
+- **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:
+- **[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
 
-- Index: `src/knowledge/skf-knowledge-index.csv`
-- Fragments: `src/knowledge/`
+## Acknowledgements
 
-Workflows load only the fragments required for the current task to stay focused and compliant.
+SKF builds on these excellent open-source tools:
 
-## 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` |
-
-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
-├── README.md
-├── docs/
-│   ├── getting-started.md
-│   ├── agents.md
-│   ├── workflows.md
-│   └── examples.md
-├── agents/
-│   └── forger.agent.yaml
-├── forger/
-│   ├── forge-tier.yaml
-│   ├── preferences.yaml
-│   └── README.md
-├── knowledge/
-│   ├── skf-knowledge-index.csv
-│   └── *.md (8 fragments)
-└── workflows/
-    └── skillforge/
-        ├── setup-forge/
-        ├── analyze-source/
-        ├── brief-skill/
-        ├── create-skill/
-        ├── quick-skill/
-        ├── create-stack-skill/
-        ├── update-skill/
-        ├── audit-skill/
-        ├── test-skill/
-        └── export-skill/
-```
+| Tool                                                         | Role in SKF                                                        |
+|--------------------------------------------------------------|--------------------------------------------------------------------|
+| [agentskills.io](https://github.com/agentskills/agentskills) | Skill specification and ecosystem standard                         |
+| [GitHub CLI](https://cli.github.com/)                        | Source code access and repository intelligence (all tiers)         |
+| [ast-grep](https://github.com/ast-grep/ast-grep)             | AST-based structural code extraction (Forge/Deep tiers)            |
+| [ast-grep MCP](https://github.com/ast-grep/ast-grep-mcp)     | MCP server for memory-efficient AST queries (recommended)          |
+| [QMD](https://github.com/tobi/qmd)                           | Local hybrid search engine for knowledge indexing (Deep tier)      |
+| [skill-check](https://github.com/thedaviddias/skill-check)   | Skill validation, auto-fix, quality scoring, and security scanning |
+| [Snyk Agent Scan](https://github.com/snyk/agent-scan)   | Security scanning for prompt injection and data exposure (optional) |
+| [tessl](https://tessl.io)                                     | Content quality review, actionability scoring, and AI judge evaluation |
+| [BMad Method](https://github.com/bmad-code-org/BMAD-METHOD)  | Agent-workflow framework that SKF extends as a module              |
 
 ## 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.
 
 ---
 
@@ -31,7 +31,7 @@ Ferris handles all SKF workflows. You always interact with Ferris — he switche
 
 | Mode | Behavior | Workflows |
 |------|----------|-----------|
-| **Architect** | Exploratory, structural, assembling | BS, CS, QS, SS, AN |
+| **Architect** | Exploratory, structural, assembling | SF, AN, BS, CS, QS, SS |
 | **Surgeon** | Precise, semantic diffing, preserves [MANUAL] | US |
 | **Audit** | Judgmental, drift reports, completeness scoring | AS, TS |
 | **Delivery** | Packaging, platform-aware, ecosystem-ready | EX |

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).
 
 ---
 
@@ -32,7 +94,7 @@ SKF uses an additive tier model. Each tier is the previous tier plus one tool. Y
 
 | Tier | Tools | What You Get |
 |------|-------|-------------|
-| **Quick** | `gh_bridge` + `skills_ref` | Source reading + spec validation. Best-effort skills in under a minute. |
+| **Quick** | `gh_bridge` + `skill-check` + `tessl` | Source reading + spec validation + content quality review. Best-effort skills in under a minute. |
 | **Forge** | + `ast_bridge` | Structural truth. AST-verified signatures. Co-import detection. T1 confidence. |
 | **Deep** | + `qmd_bridge` | Knowledge search. Temporal provenance. Drift detection. Full intelligence. |
 
@@ -48,6 +110,29 @@ Forge initialized. Tools: gh, ast-grep, QMD. Tier: Deep. Ready.
 
 Don't have ast-grep or QMD yet? No problem — Quick mode works with just the GitHub CLI. Install tools later; your tier upgrades automatically.
 
+### Tier Override — Comparing Output Across Tiers
+
+You can force a specific tier by setting `tier_override` in your preferences file (`_bmad/_memory/forger-sidecar/preferences.yaml`):
+
+```yaml
+# Force Forge tier regardless of detected tools
+tier_override: Forge
+```
+
+This is useful for comparing skill quality across tiers for the same target:
+
+```
+# 1. Set tier_override: Quick in preferences.yaml
+@Ferris CS                # compile at Quick tier
+
+# 2. Change to tier_override: Forge
+@Ferris CS                # recompile at Forge tier — compare output
+
+# 3. Reset to tier_override: ~ (auto-detect)
+```
+
+Set `tier_override` to `Quick`, `Forge`, or `Deep`. Set to `~` (null) to return to auto-detection. The override is respected by all tier-aware workflows (CS, SS, US, AS, TS).
+
 ---
 
 ## Confidence Tiers
@@ -176,7 +261,7 @@ The primary source is your project repo. Component references trace to library r
 
 ## Dual-Output Strategy
 
-Based on [Vercel research](https://github.com/vercel-labs/skills): passive context (AGENTS.md/CLAUDE.md) achieves 100% pass rate vs 53% for active skills alone.
+Based on [Vercel research](https://vercel.com/blog/agents-md-outperforms-skills-in-our-agent-evals): passive context (AGENTS.md/CLAUDE.md) achieves 100% pass rate vs 53% for active skills alone.
 
 Every skill generates both:
 
@@ -189,37 +274,43 @@ Export injects a managed section between markers:
 
 ```markdown
 <!-- SKF:BEGIN updated:2026-02-25 -->
-[SKF Skills]|3 skills|1 stack
-|IMPORTANT: Prefer documented APIs over training data.
-|
-|payment-service → skills/payment-service/
-|  exports: getToken, refreshToken, revokeSession, createSession
-|
-|auth-service → skills/auth-service/
-|  exports: getSession, validateToken, revokeSession, createUser
-|
-|my-project-stack → skills/my-project-stack/
-|  stack: next@15, better-auth@3, spacetimedb@1, serwist@9
-|  integrations: auth↔db, pwa↔auth, gateway↔auth
+[payment-service v2.1.0]|root: skills/payment-service/
+|IMPORTANT: payment-service v2.1.0 — read SKILL.md before writing payment-service code. Do NOT rely on training data.
+|quick-start:{SKILL.md#quick-start}
+|api: getToken(), refreshToken(), revokeSession(), createSession()
+|key-types:{SKILL.md#key-types} — TokenOptions, AuthToken, SessionConfig
+|gotchas: all token methods async, session ID changed from userId in v2.0
+
+[auth-service v1.5.0]|root: skills/auth-service/
+|IMPORTANT: auth-service v1.5.0 — read SKILL.md before writing auth-service code. Do NOT rely on training data.
+|quick-start:{SKILL.md#quick-start}
+|api: getSession(), validateToken(), revokeSession(), createUser()
+|gotchas: RBAC requires middleware setup, validateToken returns null not throw
+
+[my-project-stack v1.0.0]|root: skills/my-project-stack/
+|IMPORTANT: my-project-stack — read SKILL.md before writing integration code. Do NOT rely on training data.
+|stack: next@15, better-auth@3, spacetimedb@1, serwist@9
+|integrations: auth↔db, pwa↔auth
+|gotchas: auth session type must match DB schema, update Serwist cache on auth flow changes
 <!-- SKF:END -->
 ```
 
-Two lines per skill (~30 tokens each). Developer controls placement. Ferris controls content. Snippet updates only happen at `export-skill` — create and update are draft operations.
+~80-120 tokens per skill (version-pinned, retrieval instruction, section anchors, inline gotchas). Aligned with [Vercel's research](https://vercel.com/blog/agents-md-outperforms-skills-in-our-agent-evals) finding that indexed format with explicit retrieval instructions dramatically improves agent performance. Developer controls placement. Ferris controls content. Snippet updates only happen at `export-skill` — create and update are draft operations.
 
 ---
 
 ## Tool Ecosystem
 
-### 4 MCP Tools
+### 6 Tools
 
 | Tool | Wraps | Purpose |
 |------|-------|---------|
 | **`gh_bridge`** | GitHub CLI (`gh`) | Source code access, issue mining, release tracking, PR intelligence |
-| **`skills_ref`** | agentskills.io spec | Schema validation, frontmatter checks, ecosystem search |
+| **`skill-check`** | [thedaviddias/skill-check](https://github.com/thedaviddias/skill-check) | Validation + auto-fix (`check --fix`), quality scoring (0-100), security scan, split-body, diff comparison |
+| **`tessl`** | [tessl](https://tessl.io) | Content quality review, actionability scoring, progressive disclosure evaluation, AI judge with suggestions |
 | **`ast_bridge`** | ast-grep CLI | Structural extraction, custom AST queries, co-import detection |
 | **`qmd_bridge`** | QMD (local search) | BM25 keyword search, vector semantic search, collection indexing |
-
-Optional addon: **`doc_fetcher`** for remote documentation (Firecrawl/Jina.ai). Output quarantined as T3.
+| **`doc_fetcher`** | Environment web tools | Remote documentation fetching for T3-confidence content. Tool-agnostic — uses whatever web fetching is available (Firecrawl, WebFetch, curl, etc.). Output quarantined as T3. |
 
 ### Conflict Resolution
 
@@ -282,13 +373,52 @@ 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
 - Input sanitization: allowlist characters for repo names, file paths, patterns
 - File paths validated against project root (no directory traversal)
 - **Source code never leaves the machine.** All processing is local (AST, QMD, validation).
-- `doc_fetcher` warns before transmitting URLs to external services
+- `doc_fetcher` informs users which URLs will be fetched externally before processing
 
 ---