Skill Forge (SKF)

Turn code and docs into instructions AI agents can actually follow.

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. If it saved you an afternoon, grab me a coffee ☕ — it helps me keep forging.

The Problem

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.

This isn't an edge case. It's the default experience.

How Skill Forge Fixes This

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. Version-aware — skills are stored per-version, so updating to v2.0 doesn't break your v1.x skill. Compatible with skills.sh and npx skills
4. Manageable lifecycle — rename skills and drop deprecated versions without manual file surgery. Transactional safety for destructive operations.
5. Follows an open standard — skills comply with the agentskills.io spec and work across Claude, Cursor, Copilot, and other AI agents

Why two output files? Every skill SKF produces ships both SKILL.md (the full instruction set, loaded on trigger) and context-snippet.md (an 80–120 token always-on index injected into CLAUDE.md / AGENTS.md / .cursorrules). Per How It Works → Dual-Output Strategy, Vercel research shows passive context achieves a 100% pass rate vs. 79% for active skills loaded alone. Both halves ship in every skill SKF compiles.

Before vs After

Without SKF — your agent guesses:

import cognee

# Agent hallucinates: sync call, wrong parameter name, missing await
results = cognee.search("What does Cognee do?", mode="graph")

With SKF — your agent reads the verified skill:

import cognee

# Agent follows the skill instruction:
# `search(query_text: str, query_type: SearchType = GRAPH_COMPLETION) -> List[SearchResult]`
# [AST:cognee/api/v1/search/search.py:L27]
results = await cognee.search(
    query_text="What does Cognee do?",
    query_type=cognee.SearchType.GRAPH_COMPLETION
)

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 example is from the real oms-cognee skill in oh-my-skills — SKF's reference output. Want to walk the citation chain yourself? The section below shows how.

Verifying a Skill

Every AST citation in an SKF-compiled skill is falsifiable in under a minute:

1. Open the skill's provenance-map.json — find your symbol; read its source_file and source_line.
2. Open the skill's metadata.json — read source_commit and source_repo.
3. Jump to the upstream repo at that commit, open that file, find that line. The signature in SKILL.md should match the one you're reading.

If it doesn't, that's a bug — open an issue and SKF will republish with a new commit SHA and a new provenance map. Falsifiability isn't a feature; it's the whole deal.

Reference output: oh-my-skills — four Deep-tier skills compiled by SKF (cocoindex, cognee, Storybook v10, uitripled), each shipping its full audit trail in-repo. Scores between 99.0% and 99.49%, every claim walk-able to an upstream line in under 60 seconds. Both the worked example for this section and the continuing proof that the pipeline does what it says.

Install

Requires Node.js >= 22, Python >= 3.10, and uv (Python package runner).

npx bmad-module-skill-forge install

You'll be prompted for project name, output folders, and IDE configuration. When the install completes, open your IDE and invoke @Ferris SF to confirm Ferris is reachable — it will report your detected tools and capability tier. See the docs for other install methods.

Quick Start

1. Set up your environment: @Ferris SF (Setup Forge) — detects your tools and sets your capability tier
2. Generate your first skill: @Ferris QS <package-name> (Quick Skill) — creates a verified skill in under a minute
3. Full quality path: @Ferris BS (Brief Skill) → clear session → @Ferris CS (Create Skill) — brief first, then compile for maximum accuracy
4. Pipeline mode: @Ferris forge <your-library> — chains Brief → Create → Test → Export in one command

Tip: Start a fresh conversation before each workflow (or use pipeline mode to chain them automatically). SKF workflows load significant context — clearing between them prevents interference.

See the workflows docs for all available workflows, pipeline aliases, and headless mode.

Help SKF Improve

Every workflow ends with a health-check reflection that can file bugs or friction reports as GitHub issues (with your approval). Reports are auto-deduped by fingerprint, so re-reporting is safe — if the same defect was already filed, your report becomes a 👍 on the canonical issue instead of a duplicate. Please let workflows run to completion so the feedback isn't lost. If you skipped the terminal step, ask Ferris: @Ferris please run the workflow health check for this session — or open an issue directly. Full details: How It Works → Workflow Health Check.

Who Is This For?

• 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
• You need different skills for different use cases from the same target — compile multiple skills with different scopes from one repo or doc set (e.g., a core API skill and a migration guide skill)

How SKF Compares

A skeptical reader is probably already considering one of these alternatives. Here's the grid:

The others aren't bad. They solve different problems. SKF solves exactly one: the claim your agent is reading about a library was true at a specific commit on a specific day, and you can prove it in under a minute.

Learn More

• Getting Started — Installation, prerequisites, and your first skill
• Concepts — Plain-English definitions of all key terms
• How It Works — Architecture, capability tiers, output format, and design decisions
• Workflows — All available workflows with commands and connection diagrams
• Agents — Ferris: the AI agent that runs all SKF workflows
• Examples — Real-world scenarios, tips, and troubleshooting
• BMAD Synergy — How SKF workflows pair with BMAD CORE phases and optional modules

Acknowledgements

SKF builds on these excellent open-source tools:

Contributing

See CONTRIBUTING.md for guidelines.

License

MIT License — see LICENSE for details.

Skill Forge (SKF) — A standalone BMAD module for agent skill compilation.

See CONTRIBUTORS.md for contributor information.