Skip to content

sametcelikbicak/rolecraft

BranchesTags

Repository files navigation

RoleCraft

RoleCraft

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

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

Product Hunt

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

RoleCraft demo

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

Benchmark: 434x faster than Vercel
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

  1. Reads SKILL.md from the source and parses metadata (slug, name, owner)
  2. 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
  3. Copies (or symlinks with --symlink) all files alongside SKILL.md to the target directory
  4. Computes a SHA256 content hash and stores it in the lockfile
  5. Updates ~/.agents/.skill-lock.json so agents can discover the skill
  6. Compatible with skills installed by @agentskill.sh/cli, add-skill, or manual installs
  7. Installable as a skill itself via npx skills add sametcelikbicak/rolecraft

→ Full architecture & project structure

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

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
sametcelikbicak Samet ÇELİKBIÇAK Owner & Maintainer
fengjikui 冯基魁 Contributor

License

MIT

About

Zero-dependency CLI to install AI agent skills directly from any source. No marketplace, no registry, no signup — just point it at a local folder or a GitHub repo and it works. Works with opencode, claude-code, cursor, and all spec-compliant agents.

www.npmjs.com/package/rolecraft

Topics

agent cli productivity awesome ai skills skill opencode devtools gemini awesome-list cursor copilot cline ai-agents windsurf aider 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

45 stars

Watchers

0 watching

Forks

8 forks
Report repository

Releases

10 tags

Packages

 
 
 

Contributors

Languages