RoleCraft

What is RoleCraft about?

RoleCraft provides a unified CLI for handling AI agent skills and Model Context Protocol (MCP) servers. It works with more than 86 agents, supports local folders, GitHub/GitLab/SSH URLs, and npm packages, and runs without any runtime dependencies.

How to use RoleCraft?

# Try the CLI without installing
npx rolecraft --help

# Install globally (npm, pnpm, yarn, bun)
npm install -g rolecraft

# Detect agents and install a skill to every supported agent
rolecraft setup user/repo

# Install a skill (local path, GitHub repo, npm package, etc.)
rolecraft install ./my-skill --cursor

# Install a skill together with its MCP servers declared in SKILL.md
rolecraft install ./postgres-rules --cursor

# Manage MCP servers directly
rolecraft mcp install npm:@modelcontextprotocol/github --cursor

# List, search, check updates, or remove skills
rolecraft list
rolecraft search code-review
rolecraft check
rolecraft remove my-skill

# Convert skill definitions
rolecraft convert ./my-skill

All commands support non‑interactive flags (--yes, --dry‑run) for CI/CD pipelines.

Key features of RoleCraft

• Zero‑dependency runtime (≈ 87 KB) – only Node.js built‑ins are used.
• MCP + skill installation in a single command.
• Broad agent support – 86+ agents including Claude‑Code, Cursor, Copilot, Aider, etc.
• Multiple source types – local directories, GitHub/GitLab/SSH URLs, npm packages.
• Optional community registry – discover, install, and publish skills without a mandatory marketplace.
• Security scoring – static analysis with a 0‑100 risk score; dangerous skills are blocked unless forced.
• CI‑ready – lockfile‑based reinstall (rolecraft ci), dry‑run, and --yes for automation.
• Shell completions for bash, zsh, and fish.
• Interactive TUI search with preview.
• System health check (rolecraft doctor).
• Agents.xml generation for AGENTS.md compatibility.
• Profile system for saving and sharing multi‑agent configurations.
• GitHub Action for seamless integration into pipelines.

Use cases of RoleCraft

• Developer workflow – quickly bootstrap, test, and deploy custom skills for multiple AI assistants.
• CI/CD validation – enforce security scans and deterministic installs in automated pipelines.
• Skill marketplace – publish reusable skill packages to the optional RoleCraft registry.
• MCP server management – install, update, and audit context‑providing services needed by agents.
• Cross‑agent experimentation – apply the same skill across Claude‑Code, Cursor, Copilot, etc., with a single command.

FAQ from RoleCraft

• Do I need to sign up or provide an API key? No. RoleCraft works entirely offline and does not require any account.
• Will any data be sent outside my machine? No telemetry is collected; all scans run locally.
• Can I use it with multiple agents simultaneously? Yes. Use agent‑specific flags (--cursor, --claude, …) or --all.
• What if a skill is flagged as dangerous? Review the security report; you can override the block with --yes but it is discouraged for untrusted code.
• Is a registry mandatory? No. All functionality works without the optional community registry.
• How does RoleCraft differ from npx skills (Vercel)? RoleCraft adds zero‑dependency runtime, built‑in MCP management, a health‑check command, XML generation, richer completions, and broader agent coverage.
• Can I run RoleCraft in CI pipelines? Absolutely. Use rolecraft ci --yes to reinstall from the lockfile in a non‑interactive mode.

---

---

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 · 87.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.

---

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 — 87.4 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: detects prompt injection, command injection, obfuscated code, credential harvesting. Scores 0–100. Blocks dangerous skills (use --yes to override)
• 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

---

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 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/search	Install, remove, list, or search 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 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	87	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	87.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/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.

→ Contributing guide

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:

---

⭐ 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