# Skill Forge (SKF) Documentation (Full)
> Complete documentation for AI consumption
> Generated: 2026-03-08
> Repository: https://github.com/armelhbobdad/bmad-module-skill-forge
# Page Not Found
The page you're looking for doesn't exist.
## What can you do?
- Check the URL for typos
- Go back to the [home page](/)
- Browse the [Getting Started guide](/getting-started/)
- Search for what you need using the search bar above
## Need Help?
If you think this page should exist, please [open an issue](https://github.com/armelhbobdad/bmad-module-skill-forge/issues) on GitHub.
# Agents Reference
SKF includes 1 specialized agent:
---
## Ferris — Skill Architect & Integrity Guardian
**ID:** `_bmad/skf/agents/forger.md`
**Icon:** ⚒️
**Role:**
Sole agent managing the entire skill compilation lifecycle. Ferris extracts, compiles, validates, and packages agent skills from code repositories, documentation, and developer discourse.
**When to Use:**
Ferris handles all SKF workflows. You always interact with Ferris — he switches modes based on which workflow you invoke.
**Key Capabilities:**
- AST analysis via ast-grep for structural truth
- QMD knowledge search for temporal context and evidence
- agentskills.io specification compliance and validation
- GitHub source navigation and package-to-repo resolution
- Cross-knowledge synthesis for stack skills and integration patterns
**Workflow-Driven Modes:**
| Mode | Behavior | Workflows |
|------|----------|-----------|
| **Architect** | Exploratory, structural, assembling | BS, CS, QS, SS, AN |
| **Surgeon** | Precise, semantic diffing, preserves [MANUAL] | US |
| **Audit** | Judgmental, drift reports, completeness scoring | AS, TS |
| **Delivery** | Packaging, platform-aware, ecosystem-ready | EX |
**Communication Style:**
- During work: structured reports with AST citations, no metaphor
- At transitions: forge language, brief and warm
- On completion: quiet craftsman's pride
- On errors: direct and actionable
**Menu:**
```
⚒️ Ferris — Skill Forge
START HERE:
[SF] Setup Forge — Initialize your forge environment
[AN] Analyze Source — Discover what to skill
CREATE:
[BS] Brief Skill — Design a skill scope
[CS] Create Skill — Compile a skill from brief
[QS] Quick Skill — Fast skill, no brief needed
[SS] Stack Skill — Consolidated project stack skill
MAINTAIN:
[US] Update Skill — Regenerate after changes
[AS] Audit Skill — Check for drift
[TS] Test Skill — Verify completeness
DELIVER:
[EX] Export Skill — Package for distribution
[WS] Workflow Status
[FM] Full Menu
```
**Memory:**
Ferris has a sidecar (`_bmad/_memory/forger-sidecar/`) that persists user preferences and tool availability across sessions.
# Architecture
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.
---
## Why Another Tool?
AI agents hallucinate APIs. Not sometimes — constantly. The table below shows why every existing approach fails at scale:
| Approach | Strength | Fatal Flaw |
|----------|----------|------------|
| `npx skills init` | Format compliant | Empty shell. 0% intelligence. |
| LLM Summarization | High semantic context | Hallucination. Guesses parameters. No grounding. |
| RAG / Context stuffing | Good retrieval | Fragmented. Finds snippets, fails to synthesize. |
| Manual Authoring | High initial quality | Drift. Doesn't scale. |
| 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).
---
## Progressive Capability Model
SKF uses an additive tier model. Each tier is the previous tier plus one tool. You never lose capability by adding a tool.
| Tier | Tools | What You Get |
|------|-------|-------------|
| **Quick** | `gh_bridge` + `skills_ref` | Source reading + spec validation. 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. |
Setup detects your installed tools and sets your tier automatically:
```
@Ferris SF
```
```
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.
---
## Confidence Tiers
Every claim in a generated skill carries a confidence tier that traces to its source:
| Tier | Source | Tool | What It Means |
|------|--------|------|---------------|
| **T1** | AST extraction | `ast_bridge` | Current code, structurally verified. Immutable for that version. |
| **T2** | QMD evidence / source reading | `qmd_bridge` / `gh_bridge` | Historical + planned context (issues, PRs, changelogs, docs). |
| **T3** | External documentation | `doc_fetcher` | External, untrusted. Quarantined. |
### Temporal Provenance
Confidence tiers map to temporal scopes:
- **T1-now (instructions):** What ast-grep sees in the checked-out code. This is what your agent executes.
- **T2-past (annotations):** Closed issues, merged PRs, changelogs — why the API looks the way it does.
- **T2-future (annotations):** Open PRs, deprecation warnings, RFCs — what's coming.
Progressive disclosure controls how much context surfaces at each level:
| Output | Content |
|--------|---------|
| `context-snippet.md` | T1-now only — compressed, always-on |
| `SKILL.md` | T1-now + lightweight T2 annotations |
| `references/` | Full temporal context with all tiers |
### Tier Constrains Authority
Your forge tier limits what authority claims a skill can make:
| Forge Tier | AST? | QMD? | Max Authority | Accuracy Guarantee |
|-----------|------|------|---------------|-------------------|
| Quick | No | No | `community` | Best-effort |
| Forge | Yes | No | `official` | Structural (AST-verified) |
| Deep | Yes | Yes | `official` | Full (structural + contextual + temporal) |
---
## Output Architecture
### Per-Skill Output
Every generated skill produces a self-contained directory:
```
skills/{name}/
├── SKILL.md # Active skill (loaded on trigger)
├── context-snippet.md # Passive context (compressed, always-on)
├── metadata.json # Machine-readable provenance
└── references/ # Progressive disclosure
├── {function-a}.md
├── {function-b}.md
└── integrations/ # Stack skills only
├── auth-db.md
└── pwa-auth.md
```
### SKILL.md Format
Skills follow the [agentskills.io specification](https://agentskills.io/specification) with frontmatter:
```yaml
---
name: payment-service
version: 2.1.0
description: Payment processing API skill — 23 verified functions
author: org/payment-team
---
```
Every instruction in the body traces to source:
```
Extracted: `getToken(userId: string, options?: TokenOptions): Promise`
[AST:src/auth/index.ts:L42]. Confidence: T1.
```
### metadata.json — The Birth Certificate
Machine-readable provenance for every skill:
```json
{
"name": "payment-service",
"version": "2.1.0",
"skill_type": "individual",
"source_authority": "official",
"source_repo": "github.com/org/payment-service",
"source_commit": "a1b2c3d",
"forge_tier": "forge",
"spec_version": "1.3",
"generated_at": "2026-02-25T14:30:00Z",
"stats": {
"exports_documented": 23,
"exports_total": 23,
"coverage": 1.0,
"confidence_t1": 20,
"confidence_t2": 3,
"confidence_t3": 0
}
}
```
### Stack Skill Output
Stack skills map how your dependencies interact — shared types, co-import patterns, integration points:
```
skills/{project}-stack/
├── SKILL.md # Integration patterns + project conventions
├── context-snippet.md # Compressed stack index
├── metadata.json # Component versions, integration graph
└── references/
├── nextjs.md # Project-specific subset
├── better-auth.md # Project-specific subset
└── integrations/
├── auth-db.md # Cross-library pattern
└── pwa-auth.md # Cross-library pattern
```
The primary source is your project repo. Component references trace to library repos. `skill_type: "stack"` in metadata.
---
## 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.
Every skill generates both:
1. **SKILL.md** — Active skill loaded on trigger with full instructions
2. **context-snippet.md** — Passive context, compressed index injected into CLAUDE.md
### Managed CLAUDE.md Section
Export injects a managed section between markers:
```markdown
[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
```
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.
---
## Tool Ecosystem
### 4 MCP 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 |
| **`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.
### Conflict Resolution
When tools disagree, higher priority wins for instructions. Lower priority is preserved as annotations:
| Priority | Source | Tool |
|----------|--------|------|
| 1 (highest) | AST extraction | `ast_bridge` |
| 2 | QMD evidence | `qmd_bridge` |
| 3 | Source reading (non-AST) | `gh_bridge` |
| 4 | External documentation | `doc_fetcher` |
### Internal Utility
**`manifest_reader`** detects and parses dependency files across ecosystems:
- **Full support:** `package.json`, `pyproject.toml`, `requirements.txt`, `Cargo.toml`, `go.mod`
- **Basic support:** `build.gradle`, `pom.xml`, `Gemfile`, `composer.json`
---
## Workspace Artifacts
Build artifacts are committable — another developer can reproduce the same skill:
```
forge-data/{skill-name}/
├── skill-brief.yaml # Compilation config
├── provenance-map.json # Source map with AST bindings
├── evidence-report.md # Build audit trail
└── extraction-rules.yaml # Language-specific ast-grep schema
```
`skills/` and `forge-data/` are committed. Agent memory (`_bmad/_memory/forger-sidecar/`) is gitignored.
---
## Ownership Model
| Context | `source_authority` | Distribution |
|---------|-------------------|-------------|
| OSS library (maintainer generates) | `official` | `npx skills publish` to agentskills ecosystem |
| Internal service (team generates) | `internal` | `skills/` in repo, ships with code |
| External dependency (consumer generates) | `community` | Local `skills/`, marked as community |
Provenance maps enable verification: an `official` skill's provenance must trace to the actual source repo owned by the author.
---
## Key Design Decisions
| Decision | Rationale |
|----------|-----------|
| **Solo agent (Ferris), not multi-agent** | One domain (skill compilation) doesn't benefit from handoffs. Shared knowledge base (AST patterns, provenance maps) is the core asset. |
| **Workflows drive modes, not conversation** | Ferris doesn't auto-switch based on question content. Invoke a workflow to change mode. Predictable behavior. |
| **Hub-and-spoke cross-knowledge** | Each skill has one primary source. Cross-repo references use inline summary + pointer + `[XREF:repo:file:line]` provenance tag. |
| **Stack skill = compositional** | SKILL.md is the integration layer. references/ contains per-library + integration pairs. Partial regeneration on dependency updates. |
| **Snippet updates only at export** | Create/update are draft operations. Export publishes to skills/ and CLAUDE.md. No half-baked snippets. |
| **Bundle spec with opt-in update** | Offline-capable. 90-day staleness warning. `setup-forge --update-spec` fetches latest. |
---
## 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
---
## Ecosystem Alignment
SKF produces skills compatible with the [agentskills.io](https://agentskills.io) ecosystem:
- Full [specification](https://agentskills.io/specification) compliance
- Distribution via [`npx skills add/publish`](https://www.npmjs.com/package/skills)
- Compatible with [agentskills/agentskills](https://github.com/agentskills/agentskills) and [vercel-labs/skills](https://github.com/vercel-labs/skills)
# Examples & Use Cases
This section provides practical examples for using SKF: Skill Forge.
---
## Example Workflows
### Quick Skill — 47 Seconds
Developer adds [cognee](https://github.com/topoteretes/cognee) to a Python project for AI memory management. Agent keeps hallucinating method signatures and config options.
```
@Ferris QS https://github.com/topoteretes/cognee
```
Ferris reads the repository, extracts the public API via source reading, validates against spec. Skill appears in `skills/cognee/`. Agent stops hallucinating. Forty-seven seconds. Done.
### Brownfield Platform — 8 Minutes
Alex's team adopts BMAD for 10 microservices (TypeScript, Go, Rust).
```
@Ferris SF # Setup — Deep mode detected
@Ferris AN # Analyze — 10 services mapped
@Ferris CS --batch # Create — batch generation
```
10 individual skills + 1 platform stack skill. BMM architect navigates cross-service flows with verified knowledge.
### Release Prep — Trust Builder
Sarah prepares v3.0.0 with breaking changes.
```
@Ferris AS # Audit — finds 3 renames, 1 removal, 1 addition
@Ferris US # Update — preserves [MANUAL] sections, adds annotations
@Ferris TS # Test — verify completeness
@Ferris EX # Export — package for npm release
```
Ships with npm release. Consumers upgrade — their agents use the correct function names. Zero hallucination tickets.
### Stack Skill — Integration Intelligence
Armel's full-stack project: Next.js + Serwist + SpacetimeDB + better-auth.
```
@Ferris SS
```
Ferris detects 8 significant dependencies, finds 5 co-import integration points. Generates a consolidated stack skill. The agent now knows: "When you modify the auth flow, update the Serwist cache exclusion at `src/sw.ts:L23`." Integration intelligence no other tool provides.
---
## Common Scenarios
### Scenario A: Greenfield + BMM Integration
BMAD user starts a new project. BMM architect suggests skill generation after retrospective.
```
@Ferris BS # Brief — scope the skill
@Ferris CS # Create — compile from brief
@Ferris TS # Test — verify completeness
@Ferris EX # Export — inject into CLAUDE.md
```
Skills accumulate over sprints. Agent gets smarter every iteration.
### Scenario B: Multi-Repo Platform
Alex needs cross-service knowledge for 10 microservices.
One forge project, multiple QMD collections, hub-and-spoke skills with integration patterns.
### Scenario C: External Dependency
Developer needs skills for a library that doesn't have official skills.
```
@Ferris QS better-auth
```
Checks ecosystem first. If no official skill exists: generates from source. `source_authority: community`.
### Scenario D: Docs-Only (SaaS/Closed Source)
No source code available — only documentation.
Generate from docs + QMD-indexed content. T2/T3 confidence only. `source_authority: community`.
---
## Tips & Tricks
### Progressive Capability
Start with Quick mode (no setup required), upgrade to Forge (install ast-grep), then Deep (install QMD). Each tier builds on the previous — you never lose capability.
### Batch Operations
Use `--batch` with `create-skill` and `test-skill` to process multiple skills at once. Progress is checkpointed — use `--continue` to resume if interrupted.
### Stack Skills + Individual Skills
Stack skills focus on integration patterns. Individual skills focus on API surface. Use both together for maximum coverage.
### The Loop
After each sprint's refactor, run `@Ferris US` to regenerate changed components. Export updates CLAUDE.md automatically. Skill generation becomes routine — like running tests.
---
## Troubleshooting
### Common Issues
**"Forge halted: ast-grep not found"**
Install ast-grep to unlock Forge mode:
**"No brief found"**
Run `@Ferris BS` first to create a skill brief, or use `@Ferris QS` for brief-less generation.
**"Ecosystem check: official skill exists"**
An official skill already exists for this package. Consider installing it with `npx skills add` instead of generating your own.
**Quick mode skills have lower confidence**
Quick mode reads source without AST analysis. Install ast-grep to upgrade to Forge mode for structural truth (T1 confidence).
---
## Getting More Help
- Run `/bmad-help` — analyzes your current state and suggests what to do next
(e.g. `/bmad-help my batch creation failed halfway, how do I resume?`)
- Run `@Ferris SF` to check your current tier and tool availability
- Review `forge-config.yaml` for runtime configuration
- Check module configuration in your BMAD settings
# Getting Started with SKF: Skill Forge
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.
---
## Installation
There are three ways to install SKF, depending on your setup.
### 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.
### 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.
### 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.
---
## Prerequisites
| Tool | Required For | Install |
|------------------------------------------------------------------------|--------------------|-----------------------------|
| `gh` (GitHub CLI) | All modes | |
| `ast-grep` (CLI tool for code structural search, lint, and rewriting) | Forge + Deep modes | |
| `qmd` (local hybrid search engine for project files) | Deep mode | |
Don't worry if you don't have all tools — SKF detects what's available and sets your tier automatically.
---
## First Steps
### 1. Setup Your Forge
```
@Ferris SF
```
This detects your tools, sets your capability tier, and initializes the forge environment. You only need to do this once per project.
### 2. Generate Your First Skill
**Fastest path (Quick Skill):**
```
@Ferris QS https://github.com/bmad-code-org/BMAD-METHOD
```
Ferris reads the repository, extracts the public API, and generates a skill in under a minute.
**Full quality path:**
```
@Ferris BS # Brief — scope and design the skill
@Ferris CS # Create — compile from the brief
@Ferris TS # Test — verify completeness
@Ferris EX # Export — package for distribution
```
### 3. Stack Skill (for full projects)
```
@Ferris SS
```
Analyzes your project's dependencies and generates a consolidated stack skill with integration patterns.
---
## Common Use Cases
### My agent keeps hallucinating API calls
Your agent invents function signatures that don't exist. Generate a verified skill so it works from structural truth instead of guessing.
```
@Ferris QS https://github.com/org/library
```
The skill pins every function to its actual source location. Hallucinations stop.
### I'm adopting a new library and need my agent to use it correctly
You added a dependency but your agent doesn't know its API yet. Quick Skill resolves package names across npm, PyPI, and crates.io.
```
@Ferris QS cognee
```
Ferris resolves the package to its GitHub repo, extracts the public API, and generates a skill your agent can reference immediately.
### I want my agent to understand my entire project stack
Individual skills cover single libraries. Stack Skill maps how your dependencies interact — shared types, co-import patterns, integration points.
```
@Ferris SS
```
Ferris detects your manifests, ranks dependencies by significance, and generates a consolidated skill with cross-library integration patterns.
### I'm onboarding a large existing codebase
A brownfield repo with dozens of modules. You need to know what's worth skilling before you start.
```
@Ferris AN
```
Analyze Source scans the project, identifies skillable units, maps exports, and generates recommended briefs you can batch-create with `@Ferris CS --batch`.
### I want the highest accuracy possible
Quick mode reads source files. Forge mode adds AST parsing for structural truth. Deep mode goes further — QMD smart-indexes your project's source code, documentation, and configuration files into per-directory collections (excluding module internals and build artifacts), then uses BM25 keyword search, vector semantic search, and LLM-powered re-ranking to surface context no other tool can find.
```
@Ferris SF # Setup detects your tools and sets tier automatically
```
If `ast-grep` and `qmd` are available, Ferris activates Deep mode. Every skill gets AST-verified signatures (T1) enriched with deep knowledge search (T2) — deprecation warnings, breaking change history, common pitfalls surfaced by hybrid search across your indexed documentation.
### I maintain an OSS library and want official skills
You want maximum quality with full provenance for distribution. Use the full pipeline with Deep mode for the richest output.
```
@Ferris BS # Scope and design the skill
@Ferris CS # Compile — AST extraction + QMD enrichment (Deep)
@Ferris TS # Verify completeness before publishing
@Ferris EX # Package for distribution
```
Export with `source_authority: official`. Consumers get verified skills that update with each release.
### A dependency shipped breaking changes
Your existing skill is now out of date. Audit detects the drift, Update regenerates while preserving your manual additions.
```
@Ferris AS # Find what changed
@Ferris US # Regenerate — [MANUAL] sections survive
@Ferris TS # Verify the update
```
---
## What's Next?
- Check out the [Agents Reference](../agents.md) to learn about Ferris
- Browse the [Workflows Reference](../workflows.md) to see all available commands
- See [Examples](../examples.md) for real-world usage scenarios
---
## Need Help?
If you run into issues:
1. Run `/bmad-help` — analyzes your current state and suggests what to do next
(e.g. `/bmad-help my quick skill has low confidence scores, how do I improve them?`)
2. Run `@Ferris SF` to check your tool availability and tier
3. Check `forge-config.yaml` for your current configuration
## What is Skill Forge?
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.
## Quick Install
**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:
```
@Ferris SF # Setup your forge environment
@Ferris QS # Quick Skill — generate 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 |
## 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
## Support
- **Issues**: [GitHub Issues](https://github.com/armelhbobdad/bmad-module-skill-forge/issues)
# Workflows Reference
SKF includes 10 workflows organized by purpose:
---
## Core Workflows
### Setup Forge (SF)
**Command:** `@Ferris SF`
**Purpose:** Initialize forge environment, detect tools, set capability tier, auto-index project.
**When to Use:** First time using SKF in a project. Run once per project.
**Key Steps:** Detect tools → Determine tier → Create forge-config.yaml → Auto-index (Deep)
**Agent:** Ferris (Architect mode)
---
### Brief Skill (BS)
**Command:** `@Ferris BS`
**Purpose:** Scope and design a skill through guided discovery.
**When to Use:** Before `Create Skill` when you want maximum control over what gets compiled.
**Key Steps:** Gather intent → Analyze target → Define scope → Write skill-brief.yaml
**Agent:** Ferris (Architect mode)
---
### Create Skill (CS)
**Command:** `@Ferris CS`
**Purpose:** Compile a skill from a brief. Supports `--batch` for multiple briefs.
**When to Use:** After Brief Skill, or with an existing skill-brief.yaml.
**Key Steps:** Load brief → Ecosystem check → AST extract → QMD enrich → Compile → Validate → Generate
**Agent:** Ferris (Architect mode)
---
### Update Skill (US)
**Command:** `@Ferris US`
**Purpose:** Smart regeneration preserving `[MANUAL]` sections. Detects individual vs stack internally.
**When to Use:** After source code changes when an existing skill needs updating.
**Key Steps:** Load existing → Detect changes → Re-extract → Merge (preserve MANUAL) → Validate → Write
**Agent:** Ferris (Surgeon mode)
---
## Feature Workflows
### Quick Skill (QS)
**Command:** `@Ferris QS `
**Purpose:** Brief-less fast skill with package-to-repo resolution.
**When to Use:** When you need a skill quickly — no brief needed. Accepts package names or GitHub URLs.
**Key Steps:** Resolve target → Ecosystem check → Quick extract → Compile → Validate → Write
**Agent:** Ferris (Architect mode)
---
### Stack Skill (SS)
**Command:** `@Ferris SS`
**Purpose:** Consolidated project stack skill with integration patterns.
**When to Use:** When you want your agent to understand your entire project stack — not just individual libraries.
**Key Steps:** Detect manifests → Rank dependencies → Scope confirmation → Parallel extract → Detect integrations → Compile stack → Generate references
**Agent:** Ferris (Architect mode)
---
### Analyze Source (AN)
**Command:** `@Ferris AN`
**Purpose:** Decomposition engine — discover what to skill, recommend stack skill.
**When to Use:** Brownfield onboarding of large repos or multi-service projects.
**Key Steps:** Scan project → Identify units → Map exports → Detect integrations → Recommend → Generate briefs
**Agent:** Ferris (Architect mode)
---
### Audit Skill (AS)
**Command:** `@Ferris AS`
**Purpose:** Drift detection between skill and current source.
**When to Use:** To check if a skill has fallen out of date with its source code.
**Key Steps:** Load skill → Re-index source → Structural diff → Semantic diff (Deep) → Classify severity → Report
**Agent:** Ferris (Audit mode)
---
### Test Skill (TS)
**Command:** `@Ferris TS`
**Purpose:** Cognitive completeness verification. Quality gate before export.
**When to Use:** After creating or updating a skill, before exporting.
**Key Steps:** Load skill → Detect mode → Coverage check → Coherence check → Score → Gap report
**Agent:** Ferris (Audit mode)
---
## Utility Workflows
### Export Skill (EX)
**Command:** `@Ferris EX`
**Purpose:** Package for distribution + platform-aware context injection into CLAUDE.md/AGENTS.md.
**When to Use:** When a skill is ready for distribution or CLAUDE.md integration.
**Key Steps:** Load skill → Package → Generate snippet → Update CLAUDE.md → Token report → Summary
**Agent:** Ferris (Delivery mode)
---
## Workflow Connections
```
setup-forge (one-time)
│
┌──────────────┼──────────────┐
│ │ │
analyze-source quick-skill create-stack-skill
│ │ │
brief-skill │ │
│ │ │
create-skill │ │
│ │ │
└──────┬───────┘──────────────┘
│
test-skill (quality gate)
│
┌──────┼──────┐
│ │
export-skill audit-skill
│
update-skill (loops back to test)
```
---
## Build Priority
| Phase | Workflows | Notes |
|-------|-----------|-------|
| 1a (Core Engine) | setup-forge, create-skill, test-skill, export-skill | Must build first |
| 1b (Entry Points) | quick-skill, brief-skill, create-stack-skill | Complete v1.0 |
| 2 (Lifecycle) | audit-skill, update-skill, analyze-source | Post-launch |