Skip to content
Back to search

bmad-module-skill-forge

Turn code and docs into instructions AI agents can actually follow. Evidence-based skill compilation with progressive capability tiers.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 17 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/armelhbobdad/bmad-module-skill-forge with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/armelhbobdad/bmad-module-skill-forge'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/armelhbobdad--bmad-module-skill-forge/badge.svg)](/listings/armelhbobdad--bmad-module-skill-forge)

HTML

<a href="/listings/armelhbobdad--bmad-module-skill-forge"><img src="/api/listings/armelhbobdad--bmad-module-skill-forge/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

Linux, Windows, and macOS supported ([platform details](https://armelhbobdad.github.io/bmad-module-skill-forge/getting-started/#platform-support)). Requires [Node.js](https://nodejs.org/) >= 22, [Python](https://www.python.org/) >= 3.11, and [uv](https://docs.astral.sh/uv/) (Python package runner).

npx bmad-module-skill-forge install

You'll be asked for a project name, where to save skills and workspace files, which IDEs you use, and whether to install learning material. When the install completes, open your IDE and start Ferris, the SKF agent. Type `/skf-forger` in Claude Code, Cursor and most other IDEs, or `$skf-forger` in Codex. IDEs that load skills on their own, such as GitHub Copilot, start Ferris when you ask for him. The installer prints the exact command for each IDE you picked. Then give Ferris the menu code `SF`; this page writes that step as `@Ferris SF`. Ferris reports the tools it found and your capability tier, which is how much analysis those tools allow. See the [docs](https://armelhbobdad.github.io/bmad-module-skill-forge/getting-started/) for other install methods.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

.claude-plugin/marketplace.json · Manifest · 56 lines
  1. {
  2. "name": "bmad-module-skill-forge",
  3. "owner": {
  4. "name": "Armel"
  5. },
  6. "description": "Turn code and docs into instructions AI agents can actually follow. Evidence-based skill compilation with progressive capability tiers.",
  7. "license": "MIT",
  8. "homepage": "https://github.com/armelhbobdad/bmad-module-skill-forge",
  9. "repository": "https://github.com/armelhbobdad/bmad-module-skill-forge",
  10. "keywords": [
  11. "bmad",
  12. "bmad-method",
  13. "bmad-module",
  14. "agent-skills",
  15. "agentskills",
  16. "agents",
  17. "skills",
  18. "skill-forge",
  19. "compilation",
  20. "forge",
  21. "ast-grep",
  22. "qmd",
  23. "cocoindex",
  24. "cocoindex-code",
  25. "provenance",
  26. "code-analysis"
  27. ],
  28. "plugins": [
  29. {
  30. "name": "skill-forge",
  31. "source": "./",
  32. "description": "Evidence-based agent skills compiler with progressive capability tiers (Quick/Forge/Forge+/Deep).",
  33. "version": "11.1.0",
  34. "author": {
  35. "name": "Armel"
  36. },
  37. "skills": [
  38. "./src/skf-forger",
  39. "./src/skf-setup",
  40. "./src/skf-analyze-source",
  41. "./src/skf-brief-skill",
  42. "./src/skf-create-skill",
  43. "./src/skf-quick-skill",
  44. "./src/skf-create-stack-skill",
  45. "./src/skf-update-skill",
  46. "./src/skf-audit-skill",
  47. "./src/skf-test-skill",
  48. "./src/skf-export-skill",
  49. "./src/skf-rename-skill",
  50. "./src/skf-drop-skill",
  51. "./src/skf-verify-stack",
  52. "./src/skf-refine-architecture"
  53. ]
  54. }
  55. ]
  56. }
README.md · README · 201 lines
  1. <div align="center">
  2. <img src="website/public/img/skf-logo-animated.svg" alt="Skill Forge Logo" width="120" />
  3. # Skill Forge (SKF)
  4. **Turn code and docs into instructions AI agents can actually follow.**
  5. [![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)
  6. [![npm](https://img.shields.io/npm/v/bmad-module-skill-forge)](https://www.npmjs.com/package/bmad-module-skill-forge)
  7. [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
  8. [![BMAD Module](https://img.shields.io/badge/BMAD-module-blue)](https://github.com/bmad-code-org/BMAD-METHOD)
  9. [![Python Version](https://img.shields.io/badge/python-%3E%3D3.11-blue?logo=python&logoColor=white)](https://www.python.org)
  10. [![uv](https://img.shields.io/badge/uv-package%20manager-blueviolet?logo=uv)](https://docs.astral.sh/uv/)
  11. [![Docs](https://img.shields.io/badge/docs-online-green)](https://armelhbobdad.github.io/bmad-module-skill-forge/)
  12. [![Discord](https://img.shields.io/badge/Discord-Join%20Community-7289da?logo=discord&logoColor=white)](https://discord.gg/gk8jAdXWmj)
  13. [![GitHub stars](https://img.shields.io/github/stars/armelhbobdad/bmad-module-skill-forge?style=social)](https://github.com/armelhbobdad/bmad-module-skill-forge/stargazers)
  14. _Skill Forge analyzes your code repositories, documentation, and developer discourse to build verified instruction files for AI agents. Every instruction links back to its upstream: a specific `file:line` at a pinned commit when source is available, or a documentation URL when it isn't._
  15. **If SKF fixes your agent's API guesses, give it a ⭐. It helps others find this tool.**
  16. **If it saved you an afternoon, [grab me a coffee ☕](https://buymeacoffee.com/armelhbobdad). It helps me keep forging.**
  17. </div>
  18. ---
  19. ## The Problem
  20. 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, and it still gets details wrong. You write instructions by hand, and they go stale the moment the code changes.
  21. This isn't an edge case. It's the default experience.
  22. For the full story behind SKF, read [_Hallucination has a line number_](https://medium.com/@armelhbobdad/hallucination-has-a-line-number-32209b4688de) on Medium.
  23. ## Before vs After
  24. **Without SKF**, your agent guesses:
  25. ```python
  26. import cognee
  27. # Agent hallucinates: sync call, wrong parameter name, missing await
  28. results = cognee.search("What does Cognee do?", mode="graph")
  29. ```
  30. **With SKF**, your agent reads the verified skill:
  31. ```python
  32. import cognee
  33. # Agent follows the skill instruction:
  34. # `search(query_text: str, query_type: SearchType = SearchType.HYBRID_COMPLETION, ...) -> list[SearchResult]`
  35. # [AST:cognee/api/v1/search/search.py:L41]
  36. results = await cognee.search(
  37. query_text="What does Cognee do?",
  38. query_type=cognee.SearchType.GRAPH_COMPLETION
  39. )
  40. ```
  41. The skill told the agent the real function name, the real parameters, and that the call is async, all traced to the exact source line. This example is from the real [`oms-cognee`](https://github.com/armelhbobdad/oh-my-skills/blob/main/skills/oms-cognee/1.6.2/oms-cognee/SKILL.md) skill in [**oh-my-skills**](https://github.com/armelhbobdad/oh-my-skills), SKF's reference output. Its provenance map records `search` as an ast-grep match at that line, which is what `[AST:...]` means; an export SKF reads by eye instead is cited `[SRC:...]`. The [**Verifying a Skill**](#verifying-a-skill) section below shows how to walk the citation chain yourself.
  42. ## Install
  43. Linux, Windows, and macOS supported ([platform details](https://armelhbobdad.github.io/bmad-module-skill-forge/getting-started/#platform-support)). Requires [Node.js](https://nodejs.org/) >= 22, [Python](https://www.python.org/) >= 3.11, and [uv](https://docs.astral.sh/uv/) (Python package runner).
  44. ```bash
  45. npx bmad-module-skill-forge install
  46. ```
  47. You'll be asked for a project name, where to save skills and workspace files, which IDEs you use, and whether to install learning material. When the install completes, open your IDE and start Ferris, the SKF agent. Type `/skf-forger` in Claude Code, Cursor and most other IDEs, or `$skf-forger` in Codex. IDEs that load skills on their own, such as GitHub Copilot, start Ferris when you ask for him. The installer prints the exact command for each IDE you picked. Then give Ferris the menu code `SF`; this page writes that step as `@Ferris SF`. Ferris reports the tools it found and your capability tier, which is how much analysis those tools allow. See the [docs](https://armelhbobdad.github.io/bmad-module-skill-forge/getting-started/) for other install methods.
  48. ## Quick Start
  49. 1. **Set up your environment:** `@Ferris SF` _(Setup Forge)_ detects your tools and sets your capability tier
  50. 2. **Zero-ceremony path:** `@Ferris forge-auto <repo-or-doc-url>` _(Forge-Auto)_ turns a repo or doc URL into a verified skill in one command. It scopes, briefs, compiles, tests and exports on its own. The test aims for a 90% score but still passes a skill that scores 80% or more, and records the shortfall in the test report.
  51. 3. **Fast path:** `@Ferris QS <package-name-or-github-url>` _(Quick Skill)_ writes a best-effort skill with no brief and no provenance map. `@Ferris forge-quick <package-name>` also tests and exports it.
  52. 4. **Full quality path:** `@Ferris forge <repo-url> <skill-name>` chains Brief → Create → Test → Export automatically. For maximum control, run the same steps one at a time and start a fresh session before each: `@Ferris BS` _(Brief Skill)_, `@Ferris CS` _(Create Skill)_, `@Ferris TS` _(Test Skill)_, `@Ferris EX` _(Export Skill)_.
  53. For producing **many coordinated skills** across sessions, `@Ferris campaign` _(Campaign)_ orchestrates the whole set with dependency tracking and resume.
  54. > **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.
  55. See the [workflows docs](https://armelhbobdad.github.io/bmad-module-skill-forge/workflows/) for all available workflows, pipeline aliases, and headless mode.
  56. ## Who Is This For?
  57. - **You use AI agents to write code** and they keep guessing API calls wrong
  58. - **You maintain a library** and want to ship official, verified instruction files so AI agents use your API correctly
  59. - **You manage a codebase with many dependencies** and want a consolidated "stack skill" that teaches your agent how all the pieces fit together
  60. - **You use a SaaS API or closed-source tool** with no public code: SKF can generate skills from documentation alone
  61. - **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)
  62. ## How SKF Compares
  63. A skeptical reader is probably already considering one of these alternatives:
  64. | | **Skill Forge** | MCP doc servers | Hand-edited `.cursorrules` | awesome-\* lists |
  65. | -------------------------- | ----------------------------------------- | ----------------- | -------------------------- | ---------------- |
  66. | Reproducible from upstream | AST + pinned commit (or pinned doc URL) | varies; opaque | whatever you wrote | none |
  67. | Version-pinned & immutable | yes, per-version directories | runtime-dependent | rots silently | no |
  68. | Audit trail | `provenance-map.json` + test + evidence | depends on server | none | none |
  69. | Runtime cost | zero (markdown + JSON) | a running process | zero | zero |
  70. | Lifecycle tooling | rename, drop, update, export transactions | varies | file surgery | none |
  71. | Falsifiable | yes, three steps, 60 seconds | rarely | no | no |
  72. 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.**
  73. ## How Skill Forge Fixes This
  74. SKF extracts real function signatures, types, and patterns from code, docs, and developer discourse. Every instruction cites where it came from: the exact file and line for code, or the source document for docs and discussions. On top of that foundation:
  75. 1. **Version-pinned:** skills are stored per-version, so updating to v2.0 doesn't replace your v1.x skill. Compatible with [skills.sh](https://skills.sh) and [npx skills](https://www.npmjs.com/package/skills)
  76. 2. **Lifecycle tooling:** rename a skill, or deprecate or delete one version or the whole skill, without manual file surgery. Destructive operations are transactional.
  77. 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
  78. > **Every skill ships two files: `SKILL.md` (the full instruction set, loaded on trigger) and `context-snippet.md` (an 80–120 token always-on index that the export step injects into `CLAUDE.md` / `AGENTS.md` / `.cursorrules`). Why both?** Per Vercel's agent evals, a docs index in passive context reached a **100% pass rate**, while skills reached **79%** only when the agent was told to use them, and 53% when it decided on its own (see [Skill Model → Dual-Output Strategy](https://armelhbobdad.github.io/bmad-module-skill-forge/skill-model/#dual-output-strategy)).
  79. ## Verifying a Skill
  80. You can falsify any citation in an SKF-compiled skill in under a minute. Quick Skill output is the exception: it keeps no provenance map, so this audit does not apply to it.
  81. 1. **Open the skill's `provenance-map.json`** in the forge workspace (`forge-data/<skill>/<version>/` by default, not the skill folder). Find your symbol under `export_name` and read its `source_file` and `source_line`.
  82. 2. **Open the skill's `metadata.json`** (next to its `SKILL.md`) and read `source_commit` and `source_repo`.
  83. 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.
  84. For docs-only skills, the audit shape is the same: `provenance-map.json` still lists every symbol, but entries cite `[EXT:{url}]` instead of `file:line@SHA`, and step 3 becomes "open the doc URL and confirm the signature matches."
  85. If it doesn't, that's a bug. Open an issue and SKF will republish the skill with a fresh provenance map (a new commit SHA for source skills, a fresh fetch for docs-only). Falsifiability isn't a feature; it's the whole deal.
  86. **Reference output: [oh-my-skills](https://github.com/armelhbobdad/oh-my-skills).** It holds four Deep-tier skills compiled by SKF (cocoindex, cognee, Storybook v10, uitripled), each shipping its full audit trail in-repo. On a strict Skill Forge 10.0.0 test of the version each one ships, run as Test Skill is designed, with its subagents, all four pass: cocoindex, Storybook and uitripled at 100%, cognee at 99%; every report is published, the earlier failing ones included. Every claim walks to an upstream line in under 60 seconds. Serves as both the worked example for this section and a public record of what the pipeline gets right and where its test still falls short.
  87. ## Help SKF Improve
  88. Every workflow ends with a health check. If it finds a problem in SKF's own instructions, it shows you the drafted issues and, only if you approve, files them on GitHub with your account: the bug reports with **[Y]**, every finding with **[A]**. Duplicates are detected, so reporting a known problem again is safe. Friction notes and gaps go to a local queue unless you choose to submit them too. Headless runs queue every finding unless you add `health_check_autosubmit: true` to `_bmad/skf/config.yaml`, which files their bug reports, and an empty `health_check_repo` there turns the health check off. **Please let workflows run to completion**, or [open an issue](https://github.com/armelhbobdad/bmad-module-skill-forge/issues/new/choose) directly. [Full details →](https://armelhbobdad.github.io/bmad-module-skill-forge/workflows/#terminal-step-health-check)
  89. ## Learn More
  90. The docs are organized into three buckets: **Why** (start here), **Try** (do stuff), and **Reference** (look things up):
  91. **Why**
  92. - **[Why Skill Forge?](https://armelhbobdad.github.io/bmad-module-skill-forge/why-skf/)**: What SKF is for, who it suits, and when it is the wrong tool
  93. - **[Verifying a Skill](https://armelhbobdad.github.io/bmad-module-skill-forge/verifying-a-skill/)**: The 60-second audit recipe and scoring formula
  94. **Try**
  95. - **[Getting Started](https://armelhbobdad.github.io/bmad-module-skill-forge/getting-started/)**: Install, first skill, prereqs, and config
  96. - **[Forge-Auto](https://armelhbobdad.github.io/bmad-module-skill-forge/forge-auto/)**: The zero-ceremony path, one command from a repo or doc URL to a verified skill
  97. - **[Campaign](https://armelhbobdad.github.io/bmad-module-skill-forge/campaign/)**: Orchestrate many coordinated skills across sessions with dependency tracking and resume
  98. - **[How It Works](https://armelhbobdad.github.io/bmad-module-skill-forge/how-it-works/)**: Plain-English walkthrough of one skill being built, end to end
  99. - **[Examples](https://armelhbobdad.github.io/bmad-module-skill-forge/examples/)**: Real-world scenarios with full command transcripts
  100. - **[Workflows](https://armelhbobdad.github.io/bmad-module-skill-forge/workflows/)**: All 15 workflows with commands and connection diagrams
  101. **Reference**
  102. - **[Concepts](https://armelhbobdad.github.io/bmad-module-skill-forge/concepts/)**: Seven key terms, including provenance, confidence tiers and drift
  103. - **[Architecture](https://armelhbobdad.github.io/bmad-module-skill-forge/architecture/)**: Runtime flow, 7 tools, workspace artifacts, security, and the design decisions behind them
  104. - **[Skill Model](https://armelhbobdad.github.io/bmad-module-skill-forge/skill-model/)**: Capability tiers, confidence tiers, output format, dual-output strategy, ownership model
  105. - **[Agents](https://armelhbobdad.github.io/bmad-module-skill-forge/agents/)**: Ferris, the single AI agent that runs every SKF workflow
  106. - **[BMAD Synergy](https://armelhbobdad.github.io/bmad-module-skill-forge/bmad-synergy/)**: How SKF pairs with the BMAD Method's four phases and its optional modules: Test Architect (TEA), BMAD Builder (BMB), Game Dev Studio (GDS) and Creative Intelligence Suite (CIS)
  107. - **[Troubleshooting](https://armelhbobdad.github.io/bmad-module-skill-forge/troubleshooting/)**: Common errors (forge setup, skill briefs, tier confidence, run locks, campaigns) and how to resolve them
  108. ## Acknowledgements
  109. SKF builds on these excellent open-source tools:
  110. | Tool | Role in SKF |
  111. | ---------------------------------------------------------------- | ---------------------------------------------------------------------- |
  112. | [agentskills.io](https://github.com/agentskills/agentskills) | Skill specification and ecosystem standard |
  113. | [GitHub CLI](https://cli.github.com/) | Source code access and repository intelligence (all tiers) |
  114. | [ast-grep](https://github.com/ast-grep/ast-grep) | AST-based structural code extraction (Forge/Forge+/Deep tiers) |
  115. | [ast-grep MCP](https://github.com/ast-grep/ast-grep-mcp) | MCP server for memory-efficient AST queries (recommended) |
  116. | [cocoindex-code](https://github.com/cocoindex-io/cocoindex-code) | Semantic code search and file pre-ranking (Forge+; optional on Deep) |
  117. | [QMD](https://github.com/tobi/qmd) | Local hybrid search engine for knowledge indexing (Deep tier) |
  118. | [skill-check](https://github.com/thedaviddias/skill-check) | Skill validation, auto-fix and quality scoring |
  119. | [Snyk Agent Scan](https://github.com/snyk/agent-scan) | Security scanning for prompt injection and data exposure (optional) |
  120. | [tessl](https://tessl.io) | Opt-in Tessl Review: AI-judge scoring of description and content |
  121. | [BMAD Method](https://github.com/bmad-code-org/BMAD-METHOD) | Agent-workflow framework that SKF extends as a module |
  122. ## Contributing
  123. See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
  124. ## Changelog
  125. Past releases are documented in [CHANGELOG.md](CHANGELOG.md).
  126. ## License
  127. MIT License. See [LICENSE](LICENSE) for details.
  128. ---
  129. **Skill Forge (SKF)**: a standalone [BMAD](https://github.com/bmad-code-org/BMAD-METHOD) module for agent skill compilation.
  130. [![Contributors](https://contrib.rocks/image?repo=armelhbobdad/bmad-module-skill-forge)](https://github.com/armelhbobdad/bmad-module-skill-forge/graphs/contributors)
  131. See [CONTRIBUTORS.md](CONTRIBUTORS.md) for contributor information.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.