RoleCraft

Install AI agent skills as roles & behaviors — from any source.
Zero-dependency CLI. Skills + MCP servers. No marketplace. No signup.

Works with 82+ AI agents: opencode · claude-code · cursor · windsurf · devin · codex · copilot · aider · cline · gemini-cli · cody · continue · warp · codeium · fabric · goose · tabnine · supermaven · pr-pilot · loom · roo · trae · hermes · kiro · augment · kilo · openhands · junie · factory · command-code · cortex · mistral-vibe · qwen-code · openclaw · codebuddy · mux · pi · autohand-code · rovo · firebender · bob · aider-desk · and more

Quick Start · Who Is This For? · Features · Commands · FAQ · Security · Contribute

⚡ Zero dependencies · 📦 4 KB · 🤖 82+ agents · 🔌 Skills + MCP · 🔒 No telemetry · 🌐 Offline-first · 🔧 Any source

Full benchmark results →    Full feature comparison →    Migrate from Vercel skills →

Who is this for?

| If you... | rolecraft helps you... | |-----------|----------------------| | Use AI coding agents (Claude, Cursor, Copilot, etc.) | Install reusable skills so your agent stops re-learning your project every session | | Maintain team conventions | Share a single skill repo across your whole team — no copy/paste | | Run CI/CD pipelines | Lockfile-based rolecraft ci re-installs skills deterministically | | Build agent skills | Scaffold, test, and distribute skills to 82+ agents from one source | | Care about security | Built-in 0–100 security scoring blocks prompt injection, command injection, and credential harvesting on install |

Quick start

# try without installing
npx rolecraft --help
or install globally (works with npm, pnpm, yarn, bun)
npm install -g rolecraft
create a skill
rolecraft init my-skill
install it
rolecraft install ./my-skill                      # local folder
rolecraft install user/repo                       # GitHub repo
rolecraft install https://gitlab.com/org/project  # GitLab repo
rolecraft install git@github.com:user/repo.git    # SSH URL
rolecraft install npm:some-package                # npm package
rolecraft install npm:@scope/package@1.0.0        # npm with version
rolecraft install ./my-skill --cursor             # specific agent only
install a skill with its MCP servers (declared in SKILL.md)
rolecraft install ./my-postgres-rules --cursor
or manage MCP servers standalone
rolecraft mcp install npm:@modelcontextprotocol/github --cursor
or install the rolecraft skill (teaches AI agents to use rolecraft)
npx skills add sametcelikbicak/rolecraft
manage
rolecraft list
rolecraft search code-review
rolecraft check
rolecraft remove my-skill

Requirements: Node.js >= 20 · No other dependencies · 82+ agents supported · Full install guide →

Why zero dependencies? Every dependency is a risk — supply-chain attacks, breaking changes, bloated node_modules. rolecraft uses only Node.js built-in modules (fs, path, crypto, https). The entire CLI is ~4 KB. No npm install surprises.

Features

• Zero dependencies — ~4 KB, no bloat
• Any source — local folder, GitHub/GitLab/Bitbucket repo, SSH git URL, npm package
• MCP + Skills in one command — install skills and their MCP servers together. No other CLI tool combines both.
• 82+ agents — opencode, claude-code, cursor, copilot, aider, devin, gemini-cli, and more
• skills.sh compatible — installable via npx skills add sametcelikbicak/rolecraft
• No registry required — no signup, no marketplace, no vendor lock-in
• Security scoring — static analysis on install: detects prompt injection, command injection, obfuscated code, credential harvesting, and sensitive file access. Scores 0–100. Blocks dangerous skills unless --yes
• Non-interactive mode — --yes / -y flag for automation/CI pipelines
• Update checking — rolecraft check to see which skills have updates
• Shell completions — bash, zsh, fish auto-completion
• TUI search — interactive arrow-key skill browser with preview
• Content hash verification — detect tampered or outdated skills
• CI-ready — lockfile-based re-install for pipelines
• Dry-run mode — preview before installing
• System health check — rolecraft doctor diagnoses Node.js, agent directories, lockfiles, and skill integrity
• AGENTS.md XML generation — rolecraft agents-xml generates Claude Code-compatible <skills_system> XML for agent discovery

Skills + MCP in one command

rolecraft is the only CLI that installs both agent skills and MCP servers together.

When a SKILL.md declares MCP servers in its frontmatter:

---
name: postgres-rules
mcp_servers:
  - name: postgres
    source: npm:@modelcontextprotocol/postgres
---

rolecraft install ./postgres-rules --cursor installs the skill and the MCP server — one command, no separate tools.

You can also manage MCP servers standalone:

rolecraft mcp install npm:@modelcontextprotocol/github --cursor
rolecraft mcp list
rolecraft mcp remove postgres

→ Full MCP documentation

Commands overview

| Command | Description | Details | | --------------------------------------- | --------------------------------------------------------------------------- | ------------------------------------ | | rolecraft init [<name>] | Scaffold a new SKILL.md | docs | | rolecraft install <source> | Install a skill with security scan (local path, GitHub/GitLab/SSH URL, npm) | 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 | docs | | rolecraft doctor | Run system health check | docs | | rolecraft agents-xml [--write] | Generate skills XML for AGENTS.md | docs | | rolecraft mcp install/remove/list | Install, remove, and list MCP servers for AI agents | 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 upgrade | Upgrade rolecraft to the latest version | docs | | rolecraft remove <slug> | Uninstall a skill | docs | | rolecraft update <slug> | Re-install a skill to latest | docs | | rolecraft --version | Show version | |

Why rolecraft?

→ Full feature 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 | 82 | 72 | 15+ | | Skills.sh listed | ✅ | ✅ | ⚠️ (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 | ✅ | ❌ | ❌ | | File size | ~4 KB | ~465 KB | ~84 KB |

See full table →

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

rolecraft install ./my-skill              # auto-scanned rolecraft install ./my-skill --yes        # force install even if DANGER

→ Full security documentation

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.

→ Full agent path table

# Install to multiple agents at once
rolecraft install ./my-skill --cursor --devin --copilot --gemini --cody

Architecture

• Reads SKILL.md from the source and parses metadata (slug, name, owner)
• Runs a security scan on all skill files — checks for prompt injection, command injection, obfuscated code, credential harvesting, and sensitive file access. Scores 0–100. Blocks dangerous skills unless --yes
• Copies (or symlinks with --symlink) all files alongside SKILL.md to the target directory
• Computes a SHA256 content hash and stores it in the lockfile
• Updates ~/.agents/.skill-lock.json so agents can discover the skill
• Compatible with skills installed by @agentskill.sh/cli, add-skill, or manual installs
• Installable as a skill itself via npx skills add sametcelikbicak/rolecraft

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. 82+ 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, 82 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

Clone the repo and test locally without publishing to npm:

git clone https://github.com/sametcelikbicak/rolecraft.git
cd rolecraft
link globally
npm link
now rolecraft runs from your local checkout
rolecraft --help
for the docs site (VitePress)
npm install
npm run docs:dev        # local preview at http://localhost:5173/rolecraft/
npm run docs:build      # production build to docs/.vitepress/dist/
unlink when done
npm unlink -g rolecraft

All commands work the same as the installed version. No npm publish needed.

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:

| Avatar | Name | Role | | ----------------------------------------------------------------------------------------------- | ------------------------------------------------------ | ------------------------------------------------------------------- | | | Samet ÇELİKBIÇAK | Owner & Maintainer | | | 冯基魁 | Contributor |

License

MIT