README.md
August 19, 2026 · View on GitHub
RoleCraft
The Security-First Skill Manager for AI Agents
Every install runs a security scan · Skills & MCP Servers across 86 Agents (26 Verified)
Zero-dependency CLI · No signup · Offline-first
Works with 86 AI agents. See the full agent table →
Quick Start · Features · Commands · Comparison · FAQ · Security · Contribute
⚡ Zero dependencies · 📦 432.8 kB · 🤖 26 verified agents · 🔌 Skills + MCP · 🔒 Security scoring · 📝 Skill testing · 🔧 Init templates · 🌐 Offline-first
Full benchmark results →
Full feature comparison →
Migrate from Vercel skills →
Quick start
# try without installing
npx rolecraft --help
# or install globally (works with npm, pnpm, yarn, bun)
npm install -g rolecraft
# detect all agents + install a skill to every agent
rolecraft setup user/repo
# install a skill (local, GitHub, GitLab, SSH, npm)
rolecraft install ./my-skill --cursor
# install a skill WITH its MCP servers (declared in SKILL.md)
rolecraft install ./postgres-rules --cursor
# manage MCP servers standalone
rolecraft mcp install npm:@modelcontextprotocol/github --cursor
# manage installed skills
rolecraft list
rolecraft search code-review
rolecraft check
rolecraft remove my-skill
# convert between SKILL.md and .mdc formats
rolecraft convert ./my-skill
rolecraft convert --help
Requirements: Node.js >= 20 · 432.8 kB · zero dependencies · 86 agents · Getting Started → · Full install guide →
Why zero dependencies? Every dependency is a supply-chain risk. rolecraft uses only Node.js built-ins (
fs,path,crypto,https) — nonode_modulessurprises.
Registry (optional community marketplace)
Discover and install skills by short names from the rolecraft Registry (source) — a GitHub-powered, zero-backend index of published skills:
# Search the registry
rolecraft search react --registry
# Install by short slug (auto-resolves to underlying repo)
rolecraft install react-rules
# Publish your skill
rolecraft publish ./my-skill/ --repo user/my-skill
PRs to the registry are auto-validated, then merged by a maintainer. The registry is completely optional; every other feature works without it.
All registry operations are also available via the Node.js API — searchRegistry, registryResolve, registryPublish, registryCheckUpdates, registryInfo, registryList, registryClearCache.
Skills + MCP in one command
rolecraft installs both agent skills and MCP servers in a single command.
A single SKILL.md can declare both a skill and its required MCP servers:
---
name: postgres-rules
mcp_servers:
- name: postgres
source: npm:@modelcontextprotocol/postgres
---
# one command installs the skill AND the MCP server
rolecraft install ./postgres-rules --cursor
No other CLI combines both. npx skills has no MCP support. ags has a separate MCP server for search only. → Full MCP docs
Features
- Zero dependencies — 432.8 kB, only Node.js built-ins
- MCP + Skills in one command — install skills and their MCP servers together
- Any source — local folder, GitHub/GitLab/SSH URL, npm package
- 86 agents — opencode, claude-code, cursor, copilot, aider, and more
- No registry required — works fully without a marketplace; community-driven registry optional
- Security scoring — static analysis on every install: detects prompt injection, command injection, obfuscated code, credential harvesting. Scores 0–100. Blocks dangerous skills (use
--yesto override). 341 malicious skills were found on community hubs in Feb 2026 — rolecraft scans every skill before it touches your machine - CI-ready — lockfile-based re-install (
rolecraft ci),--yesflag,--dry-run - Shell completions — bash, zsh, fish auto-completion
- TUI search — interactive arrow-key skill browser with preview
- System health check —
rolecraft doctordiagnoses agent directories, lockfiles, and skill integrity - AGENTS.md XML generation —
rolecraft agents-xmlgenerates Claude Code-compatible XML - Profile system — save, apply, and share multi-agent configurations
CI/CD Integration
Use the rolecraft GitHub Action (source) to verify and install skills in your CI pipeline:
# .github/workflows/skills.yml
- uses: rolecraft-sh/rolecraft-action@v1
with:
command: ci --yes
See the CI guide for more examples.
Node.js API
rolecraft exposes a programmatic API for use in your own Node.js scripts and tools:
import {
install,
list,
search,
check,
doctor,
verify,
ci,
mcpInstall,
profileSave,
} from "rolecraft";
// install a skill
const result = await install("./my-skill", { global: true });
console.log(result);
// search GitHub for skills
const results = await search("code-review");
console.log(results.results);
// system health check
const health = await doctor();
console.log(health.summary);
// full API reference → [docs/reference.md](docs/reference.md)
All API functions return plain objects (no side-effects). Available exports:
| Function | Description |
|---|---|
install | Install a skill with security scan |
list | List installed skills |
search | Search GitHub or skills.sh |
resolve | Resolve a source string |
remove | Uninstall a skill |
update | Re-install a skill |
check | Check for updates |
verify | Verify skill integrity |
ci | Re-install from lockfile |
doctor | System health check |
use | Preview a skill |
mcpInstall | Install an MCP server |
mcpList | List MCP servers |
mcpUpdate | Update an MCP server |
mcpRemove | Remove an MCP server |
mcpCheck | Check MCP server status |
mcpSearch | Search MCP servers |
profileSave | Save current config |
profileApply | Apply a saved profile |
profileDiff | Diff current vs saved |
profileList | List profiles |
profileShow | Show profile details |
profileDelete | Delete a profile |
profileImport | Import a profile |
test | Test a skill quality with assertions |
Commands overview
| Command | Description | Details |
|---|---|---|
rolecraft init [<name>] | Scaffold a new SKILL.md (--template, --list) | docs |
rolecraft install <source> | Install a skill with security scan (local path, GitHub/GitLab/SSH URL, npm) | docs |
rolecraft publish <source> | Publish a skill to the rolecraft Registry | docs |
rolecraft bundle <sources> | Install multiple skills from inline sources or file | docs |
rolecraft bundle create | Create a new bundle file | docs |
rolecraft search <query> | Search for skills on GitHub (TUI with --interactive) | docs |
rolecraft check | Check installed skills for available updates | docs |
rolecraft use <source> | Preview a skill's files without installing | docs |
rolecraft completions bash|zsh|fish | Generate shell completion scripts | docs |
rolecraft setup [<source>] | Detect agents, optionally install a skill to all | docs |
rolecraft list | Show all installed skills (filter with --agent) | docs |
rolecraft doctor | Run system health check | docs |
rolecraft agents | Show agent capability manifest | docs |
rolecraft agents-xml [--write] | Generate skills XML for AGENTS.md | docs |
rolecraft mcp install/remove/list/search | Install, remove, list, or search MCP servers for AI agents | docs |
rolecraft mcp check/update | Check for MCP server updates or update a server | docs |
rolecraft profile save/apply/list | Save, apply, and share multi-agent configuration profiles | docs |
rolecraft verify | Check installed skill integrity via content hash | docs |
rolecraft watch [<slug>] | Watch skills for changes and auto-sync | docs |
rolecraft ci | Re-install all skills from lockfile (CI mode) | docs |
rolecraft convert <source> | Convert between SKILL.md and .mdc formats | docs |
rolecraft diff <a> <b> | Compare two skills section-by-section | docs |
rolecraft compose <a> <b> [...] | Compose multiple skills into one | docs |
rolecraft upgrade | Upgrade rolecraft to the latest version | docs |
rolecraft test <skill-path> | Test a skill quality with built-in assertions | docs |
rolecraft remove <slug> | Uninstall a skill | docs |
rolecraft update <slug> | Re-install a skill to latest | docs |
rolecraft rollback <slug> | Restore a skill to previous version from backup history | docs |
rolecraft --version | Show version | |
rolecraft --help | Show full command reference | CLI Reference |
Comparison
| Feature | rolecraft | skills (Vercel) | @agentskill.sh/cli |
|---|---|---|---|
| Zero dependencies | ✅ 0 | ✅ (1 dep) | ❌ (2) |
| Local path install | ✅ 1st class | ✅ | ❌ marketplace only |
| GitHub repo install | ✅ | ✅ | ❌ |
| GitLab / SSH git URL | ✅ | ✅ | ❌ |
| npm package source | ✅ | ✅ | ❌ |
| MCP server management | ✅ | ❌ | ❌ |
| Agent targets | 86 | 72 | 15+ |
| Registry / marketplace | ✅ | ✅ (skills.sh) | ⚠️ (registry only) |
| Bundle install + create | ✅ | ❌ | ✅ (skillset only) |
| Interactive TUI search + install | ✅ | ✅ | ❌ |
| Security scoring (0–100) | ✅ | ✅ (Snyk) | ✅ (server + local) |
Non-interactive flag (--yes/-y) | ✅ | ✅ | ❌ |
Skill update check (check) | ✅ | ❌ | ❌ |
| Shell completions (bash/zsh/fish) | ✅ | ❌ | ❌ |
Dry-run preview (--dry-run) | ✅ | ❌ | ❌ |
| Interactive scope prompt | ✅ | ✅ | ❌ |
Content hash verification (verify) | ✅ | ✅ | ❌ |
CI-mode re-install (ci) | ✅ | ✅ | ❌ |
System health check (doctor) | ✅ | ❌ | ❌ |
| Watch mode (auto-sync) | ✅ | ❌ | ❌ |
| AGENTS.md XML generation | ✅ | ❌ | ❌ |
| Self-upgrade command | ✅ | ❌ | ❌ |
| Publish to registry | ✅ | ❌ | ❌ |
| File size | 432.8 kB | ~465 KB | ~84 KB |
Security
Every install is automatically scanned with static analysis that detects:
| Severity | What it catches |
|---|---|
| 🔴 Critical | Prompt injection, obfuscated code (base64 blobs, eval()), command injection (download-and-execute) |
| 🟡 High | Credential harvesting patterns, sensitive file access (~/.ssh, .env) |
| 🟢 Medium/Low | Missing metadata, unusual source patterns |
Scores range 0–100:
- 90+ → SAFE, install proceeds
- 70–89 → REVIEW, prompts for confirmation
- <70 → DANGER, blocked unless
--yes - Any critical issue → DANGER regardless of score (a single critical finding can never be silently skipped)
rolecraft install ./my-skill # auto-scanned
rolecraft install ./my-skill --yes # force install even if DANGER
How agents discover skills
rolecraft knows where each AI agent looks for skills. Use flags like --claude, --cursor, --devin to target specific agents, or --all for every supported agent.
# Install to multiple agents at once
rolecraft install ./my-skill --cursor --devin --copilot --gemini --cody
Architecture
- Parses
SKILL.mdfrom source (local, GitHub, GitLab, SSH, npm) - Runs static security scan on all files (prompt injection, command injection, obfuscation, credential harvesting) — scores 0–100
- Copies/symlinks files to target agent's skill directory
- Records SHA256 content hash in
~/.agents/.skill-lock.json - Compatible with skills from
npx skills,@agentskill.sh/cli, or manual installs
FAQ
Q: Do I need to sign up or log in? A: No. No account, no API key, no marketplace. Point rolecraft at any folder or repo and it works.
Q: Can I use rolecraft with multiple AI agents?
A: Yes. 86 agents supported. Use --cursor, --claude, --devin flags or --all for every agent.
Q: Does rolecraft send telemetry? A: No. Zero data leaves your machine. The security scan runs locally. No phone home.
Q: How is this different from npx skills (Vercel)?
A: rolecraft has zero dependencies, MCP server management, 86 agents (vs 72), doctor, watch, bundle, agents-xml, and shell completions. Full comparison →
Q: Can I use it in CI/CD?
A: Yes. rolecraft ci --yes re-installs all skills from lockfile, non-interactive. Perfect for pipelines.
Q: My skill is blocked as DANGER. What do I do?
A: Review the security report, fix the flagged patterns, or use --yes to force install (not recommended for untrusted skills).
Development
git clone https://github.com/rolecraft-sh/rolecraft.git
cd rolecraft
npm install # sets up the pre-commit hook automatically
npm link # rolecraft CLI runs from local checkout
npm run lint # syntax + Biome (format & unused-variable checks)
npm run lint:fix # auto-fix formatting and unused imports
npm run docs:dev # local docs preview (VitePress)
npm test # 828+ tests, 0 fails expected
A pre-commit hook runs lint automatically on every commit and rejects commits that don't pass. Zero-runtime-dependency policy is preserved — Biome and VitePress are devDependencies only.
Support
- Docs site — full command reference and guides
- GitHub Issues — bug reports, feature requests
- SUPPORT.md — how to get help
- SECURITY.md — responsible disclosure
Contributing
Contributions are welcome! See CONTRIBUTING.md for guidelines on how to get started. Before opening an issue, check our templates for bug reports and feature requests.
Contributors
Thanks to everyone who has contributed to RoleCraft:
All contributions are tracked automatically by GitHub — the list below stays in sync without any manual edits.
⭐ If rolecraft makes your AI agent workflow easier, consider starring the repo.
It helps others discover the project and shows that the community finds it useful.
License
MIT