Skip to content

sametcelikbicak/rolecraft

BranchesTags

Repository files navigation

RoleCraft

RoleCraft

Install AI agent skills as roles & behaviors — from any source.
Zero-dependency CLI · MCP + Skills in one command · 86+ agents · No signup

Awesome skills.sh npm npm downloads Tests CodeQL Dependabot Stars Changelog Contributing MIT Docs Node Security scoring Code of Conduct Support

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 · Features · Commands · Comparison · FAQ · Security · Contribute

RoleCraft demo

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

Benchmark: 434x faster than Vercel
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 · 4 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) — no node_modules surprises.

Skills + MCP in one command

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

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 — ~4 KB, only Node.js built-ins
  • MCP + Skills in one command — install skills and their MCP servers together. Unique.
  • Any source — local folder, GitHub/GitLab/SSH URL, npm package
  • 86+ agents — opencode, claude-code, cursor, copilot, aider, devin, gemini-cli, and more
  • No registry required — no signup, no marketplace, no vendor lock-in
  • Security scoring — static analysis: detects prompt injection, command injection, obfuscated code, credential harvesting. Scores 0–100. Blocks dangerous skills
  • CI-ready — lockfile-based re-install (rolecraft ci), --yes flag, --dry-run
  • Shell completions — bash, zsh, fish auto-completion
  • TUI search — interactive arrow-key skill browser with preview
  • System health check — rolecraft doctor diagnoses agent directories, lockfiles, and skill integrity
  • AGENTS.md XML generation — rolecraft agents-xml generates Claude Code-compatible XML
  • Profile system — save, apply, and share multi-agent configurations

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 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 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
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 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

  1. Parses SKILL.md from source (local, GitHub, GitLab, SSH, npm)
  2. Runs static security scan on all files (prompt injection, command injection, obfuscation, credential harvesting) — scores 0–100
  3. Copies/symlinks files to target agent's skill directory
  4. Records SHA256 content hash in ~/.agents/.skill-lock.json
  5. Compatible with skills from npx skills, @agentskill.sh/cli, or manual installs

→ Full architecture

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/sametcelikbicak/rolecraft.git
cd rolecraft
npm link                   # rolecraft CLI runs from local checkout
npm install                # for docs site (VitePress)
npm run docs:dev           # local docs preview
npm test                   # 678 tests, 0 fails expected

→ Contributing guide

Support

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:

sametcelikbicak
Samet ÇELİKBIÇAK
Owner & Maintainer		 fengjikui
冯基魁
Contributor		 Yurii201811
Yurii201811
Contributor		 gaoharimran29-glitch
Gaohar Imran
Contributor		 ajaynomics
Ajay Krishnan
Contributor		 BenjaminAyivoh1
Benjamin Ayivoh
Contributor

⭐ 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

About

Zero-dependency CLI that installs AI agent skills + MCP servers from any source. 86+ agents. No signup, no telemetry, 4 KB.

sametcelikbicak.github.io/rolecraft/

Topics

agent cli productivity ai skills skill mcp opencode devtools gemini cursor copilot cline ai-agents windsurf aider model-context-protocol claude-code skill-installer skill-tool

Resources

Readme

License

MIT license

Code of conduct

Code of conduct

Contributing

Contributing

Security policy

Security policy
Activity

Stars

75 stars

Watchers

1 watching

Forks

13 forks
Report repository

Releases

11 tags

Packages

 
 
 

Contributors

Languages