Quick Start
# Try without installing
npx rolecraft --help
# Install globally (npm, pnpm, yarn, bun)
npm install -g rolecraft
# or with Homebrew
brew tap sametcelikbicak/tap https://github.com/sametcelikbicak/homebrew-tap
brew trust sametcelikbicak/tap
brew install rolecraft
# Install a skill (local, GitHub, GitLab, SSH, npm)
rolecraft install ./my-skill --cursor
# Install a skill WITH its MCP servers
rolecraft install ./postgres-rules --cursor
# Detect all agents and install a skill to every one
rolecraft setup user/repo
Requirements: Node.js >= 22
Homebrew: the formula installs the CLI only — Node.js >= 22 must be in
PATH(nvm, asdf or a system install). The formula version always matches the released version.
Why zero dependencies? Every dependency is a supply-chain risk. rolecraft uses only Node.js built-ins (
fs,path,crypto,https) — nonode_modulessurprises.
Full install guide → · Getting Started →
Features
- Zero dependencies — only Node.js built-ins, nothing to audit
- Any source — local folder, GitHub/GitLab/SSH URL, npm package
- 90 agents — opencode, claude-code, cursor, copilot, aider, oh-my-pi, and more
- No registry required — works fully without a marketplace
- Security scoring — static analysis before every install: prompt injection, command injection, obfuscated code, credential harvesting. Scores 0–100. It is a regex linter, not a policy engine — what it does not catch
- CI-ready — lockfile-based re-install (
rolecraft ci),--yesflag,--dry-run - MCP + Skills — install skills and their MCP servers in a single command
- Shell completions — bash, zsh, fish auto-completion
- Profile system — save, apply, and share multi-agent configurations
Full feature list → · Comparison vs skills (Vercel) →
Security
A skill is statically analysed before it is written into an agent's skill directory. The scan looks for prompt injection, command injection, obfuscated code and credential harvesting, and scores 0–100:
- 90+ → SAFE, install proceeds
- 70–89 → REVIEW, prompts for confirmation
- <70 → DANGER, blocked unless
--yes - any critical finding → DANGER regardless of score
The scan runs on every install path: install, bundle, update, setup, search --interactive, watch auto-sync, ci and profile apply. It does not run under --dry-run, and setup does not scan the MCP servers a skill declares.
rolecraft install ./my-skill # scanned before install
rolecraft install ./my-skill --yes # force install even if DANGER
The scanner matches file contents against patterns. It does not interpret what a skill means, so a natural-language instruction that avoids every pattern will score 100. Read what this does not catch before relying on a score as an approval.
Known limitations
Stated here so nothing below has to be discovered by surprise:
rolecraft civerifies content, it does not pin sources. It re-resolves everysourcein the lockfile and compares content hashes. Sources that move by design — an npmdist-tags.latest, a git branch head — are not pinned, so two runs can legitimately differ. There is no--frozenmode.- A security score is not a trust decision. It reports whether a dangerous pattern was found in the resolved files. It says nothing about whether the upstream source is trustworthy, and it does not read natural-language instructions.
--dry-rundoes not scan, so it cannot tell you whether an install would be refused.rolecraft setupdoes not scan MCP servers declared inside a skill.installdoes.- MCP servers installed from
uvx:,pipx:,go:,deno:,cargo:or a local path are not scanned — their contents are never fetched, so they report as SAFE.
Commands
→ Full CLI Reference · All commands →
Node.js API
rolecraft exposes a programmatic API for your own scripts and tools:
import { install, list, search, doctor } from 'rolecraft'
const result = await install('./my-skill', { global: true })
const skills = await list()
const results = await search('code-review')
const health = await doctor()
All API functions return plain objects (no side-effects).
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 checks
npm test # full suite, 0 fails expected
A pre-commit hook runs lint automatically on every commit. 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.
⭐ 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
