Skillforge
hretheum/skillforge
Motor de skills compostos para agentes — uma engine, múltiplos clientes
Ver no GitHubMotor genérico de skills reutilizáveis para pipelines de agentes, com suporte a seis tipos de skills distintos. Funciona tanto como servidor MCP quanto CLI, permitindo composição de capacidades de IA sem reescrever prompts para diferentes clientes.
Instalação
npx convez-ai hretheum/skillforge1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.
Métricas
Casos de uso
- Criar capabilities reutilizáveis em pipelines de agentes
- Compartilhar skills globais entre projetos sem duplicação
- Integrar skills em Claude Code como slash commands
- Gerar artefatos, instruções e validações parametrizadas por cliente
Veredito

Projeto sólido para times que precisam escalar agents com skills reutilizáveis sem duplicação de código. A separação entre engine genérica e configuração por cliente é bem-pensada, mas requer familiaridade com Node.js e o conceito de MCP servers para aproveitamento total.
README
A tradução para o português deste README ainda está na fila.
skillforge
Composable skills for agent pipelines — one engine, swappable client configs.
Other languages: Polski · Русский
What this is
skillforge is one generic engine that, from a swappable per-client config, produces ready-made skills — reusable capabilities an agent can invoke (for example, "create a component that conforms to this client's design system"). Instead of hand-writing the same prompt for every client, you describe the client once as data; the engine assembles the skill. The engine knows nothing about any specific client — all client knowledge lives in separate config + referenced resources, so the same engine serves many clients with no code changes.
It is an independent work written from scratch from the concept alone (clean-room). The membrane is one-way: the concept crosses, the code never does. No line of anyone else's code, configuration, or confidential data is carried in — only ideas and "how it should work".
Key features
- Generic engine —
src/contains zero client knowledge; swapping the config produces a different set of skills with no engine change. - Six skill kinds —
artifact·instruction·validation·analysis·transformation·sync, each with its own stage subset and governance class. - Dual interface — a CLI (
skillforge …) and an MCP server (Model Context Protocol over stdio) for any MCP-compatible agent or IDE. - Global skill store — installed skills live in
~/.skillforge/skills/, shared across projects. - Three emit profiles —
open-core(default, a strict no-op that returns the SKILL.md unchanged),claude, andcodex(purely additive companions for those runtimes). - Minimal runtime footprint — the only third-party runtime dependency is the MCP SDK; everything else is the Node standard library.
Quick start
"I don't know what git is — and I don't want to"
You just want the skills as /skill-name slash commands in Claude Code. No terminal, no git,
no Node.js:
- Download the skills ZIP from Releases
(asset
skillforge-skills-<version>.zip) - Unpack it and move the skill folders into
~/.claude/skills/(in Finder: Cmd+Shift+G → type~/.claude/skills) - Restart Claude Code — all 266 skills work as slash commands:
/brand-discovery,/brand-voice,/api-design, …
Or, if a single Terminal line is acceptable (uses only tools preinstalled on macOS):
curl -L https://github.com/hretheum/skillforge/releases/download/skills-v0.2.1/skillforge-skills-0.2.1.zip -o /tmp/sf.zip && mkdir -p ~/.claude/skills && unzip -oq /tmp/sf.zip -d ~/.claude/skills
This path installs the skills only — no CLI, no MCP server, nothing executes at install time. If you want the full engine, read on.
"I'm a developer"
Pick one of the two installation options below, then optionally add the MCP server and a skill bundle.
Option A — Global CLI (recommended)
Install once, use from anywhere:
git clone https://github.com/hretheum/skillforge.git
cd skillforge
npm install
npm install -g .
skillforge --help
Option B — Run directly without installing
If you prefer not to install globally, run from the cloned directory:
git clone https://github.com/hretheum/skillforge.git
cd skillforge
npm install
node bin/skillforge.js --help
All examples in this README use
skillforge …. If you chose Option B, replace that withnode bin/skillforge.js ….
Add the MCP server (optional)
The MCP server lets Claude Desktop (and any other MCP-compatible client) call skillforge tools directly from a conversation.
Claude Desktop — add this to claude_desktop_config.json
(on macOS: ~/Library/Application Support/Claude/claude_desktop_config.json):
{
"mcpServers": {
"skillforge": {
"command": "skillforge",
"args": ["mcp"],
"env": {
"SKILLFORGE_STATE_DIR": "/Users/you/Documents/skillforge-state"
}
}
}
}
SKILLFORGE_STATE_DIR is where the MCP server is allowed to read and write files (skill session state,
brand-discovery checkpoints, etc.). Set it to any directory you own. Restart Claude Desktop after saving.
Or let skillforge write the entry for you:
skillforge init
Other MCP clients — start the server on stdio and point your client at it:
skillforge mcp
Install a skill bundle (optional)
Install 266 community skills from the ECC collection into your global skill store with one command:
skillforge skills add ecc
List what's installed:
skillforge skills list
CLI: emit
emit projects a skill's SKILL.md onto a target runtime through a chosen emit profile.
| Flag | Description |
|---|---|
--skill <path> | Path to the SKILL.md to emit (required) |
--profile <name> | Emit profile: open-core (default), claude, codex |
--registry <path> | Registry JSON (default: skillforge.registry.json in the cwd) |
--out <dir> | Output directory (default: current directory) |
-h, --help | Show command help |
# Open-core (default): returns the SKILL.md byte-identical, no companions
skillforge emit --skill skills/create-component/SKILL.md
# Claude profile: emits the SKILL.md plus its Claude companion
skillforge emit --skill skills/create-component/SKILL.md --profile claude
# Codex profile, explicit registry and output directory
skillforge emit --skill skills/create-component/SKILL.md --profile codex \
--registry skillforge.registry.json --out ./dist
CLI: skills
Manage the global skill store at ~/.skillforge/skills/.
# Install a bundle (curated alias, npm package name, or local directory)
skillforge skills add ecc # ECC community bundle (266 skills)
skillforge skills add @skillforge-core/ecc-bundle # same, explicit package name
# List installed skills with versions and source
skillforge skills list
# Persist a config flag (e.g. auto-update on MCP startup)
skillforge skills config auto-update true
# Activate an installed skill as a native slash command in Claude Code
skillforge skills activate brand-voice --target superpowers
# Deactivate (remove from the harness directory)
skillforge skills deactivate brand-voice
Skill kinds
A skill's kind fixes which engine stages run and how its side effects are governed. write and
bidirectional kinds pass through the tool-governance gate; the read-only kinds return a typed result
with no file write.
| Kind | Description | Governance | Example skill |
|---|---|---|---|
artifact | Produces a concrete artifact (a component, a file) via output adapters | write | create-component |
instruction | Emits step-by-step agent directives from client references | none | verdex-create-component |
validation | Returns a typed {pass, violations} verdict — never a file write | none | verdex-disclosure-check |
analysis | Structured read-only reasoning over client resources | none | verdex-analytics |
transformation | Reshapes or converts existing content into a new artifact | write | — |
sync | Two-way reconciliation between a source and a target | bidirectional | sync-example |
Project layout
src/
engine/ runSkill() — the sole public API + the GenericExecutor
registry/ skill-kind descriptors (the six kinds) + catalog
governance/ tool-governance gate, audit trail, secret scan, skill_result
loader/ client-config loading + activation
adapters/ input/output adapter contracts and run edges
skills/ compose steps + the data-driven compose-registry
emit/ export layer: open-core / claude / codex profiles
core/ prompt rendering, session + cache telemetry attributes
mcp/ the stdio MCP server
clients/ per-client configs (data only): one dir per client, e.g. glasshouse, verdex, …
test/ node --test suite
tools/ gates: registry-lint, determinism, secret-scan, cleanroom, …
docs/ the full specification
Documentation
The full specification lives across the docs/ tree — covering the vision, architecture, client model,
adapters, the normalized form, skills, the loader, governance, deployment profiles, security, and cost.
Start with docs/getting-started.md or docs/vision-and-problem.md.
Contributing
Contributions are welcome — bug reports, new skill kinds, adapter implementations, docs fixes.
Before you start:
- Read
docs/vision-and-problem.md— understand what skillforge is and is not before proposing changes. - Read
docs/architecture-overview.md— the map of all sub-documents and the engine's layered structure. - Read
CLAUDE.md— project rules that apply to all work here (clean-room policy, validation directive, doc closure requirement).
Relevant docs by area:
| Area | Document |
|---|---|
| Adding a new skill kind | docs/skill-type-system.md · docs/skill-manifest-and-registry.md |
| Writing a client config | docs/client-model.md · docs/normalized-form.md |
| Input/output adapters | docs/adapters.md |
| Governance and tool gates | docs/tool-governance.md |
| Security model | docs/security.md |
| Loader and activation | docs/loader-and-activation.md |
| Emit profiles | docs/deployment-profiles.md |
| Glossary | docs/glossary.md |
Troubleshooting
Activated skills not visible as slash commands in Claude Code
Before v0.1.1, skills activate wrote flat ~/.claude/skills/<name>.md files. Claude Code requires
skills to be in ~/.claude/skills/<name>/SKILL.md directory format. If you activated skills with an
older version, re-run:
# Remove old flat files
ls ~/.skillforge/skills/ | while read skill; do
rm -f ~/.claude/skills/${skill}.md
done
# Re-activate in the correct format
ls ~/.skillforge/skills/ | while read skill; do
skillforge skills activate "$skill" --target superpowers
done
Skills don't respond to /skill-name in Claude Desktop chat
Claude Desktop's chat / menu only lists Anthropic cloud skills — it does not surface MCP prompts or
tools from connected servers until the model has a reason to use them. To run a store skill in
Desktop chat, mention the server explicitly, e.g.:
use the skillforge mcp skill api-design
The model will then call skillforge_get_skill and follow the skill. In Claude Code (CLI and
desktop app) activated skills work as native /skill-name commands — see
docs/getting-started.md, section 9.
Contributing a skill to ECC (the community bundle):
skillforge ships the ECC bundle. If you want to add a skill to the community collection, open a PR there — skills accepted upstream are automatically included in the next bundle release.
License
Apache 2.0 + Commons Clause. You may use, modify, and distribute skillforge freely for personal and community use. The Commons Clause addendum prohibits selling the software — including paid hosting or consulting/support services whose value derives substantially from skillforge's functionality. Commercial use of that kind requires a separate commercial licence. See LICENSE for the full text.