rolecraft install

Install a skill from a local path, GitHub repository, npm package, or registry slug.

Supports single-skill and multi-skill repositories. If a source contains multiple SKILL.md files (e.g. under skills/), you will be prompted to select which ones to install.

Usage

rolecraft install <source> [flags]

Source types

Local path

Any directory containing SKILL.md:

rolecraft install ./my-skill
rolecraft install ~/projects/my-skill
rolecraft install /absolute/path/to/skill

GitHub repo

Shorthand owner/repo:

rolecraft install rolecraft-sh/skills
rolecraft install mattpocock/skills

The CLI clones with --depth 1, discovers all SKILL.md files (including those under skills/, .agents/skills/, etc.), and lets you choose.

Registry slug

The rolecraft Registry provides short, versioned names for published skills:

rolecraft install my-skill

If my-skill isn't a local path, GitHub ref, git URL, or npm ref, rolecraft looks it up in the registry and resolves it to the underlying repo URL. See registry.md for details.

npm package

Install any npm package that contains a SKILL.md:

rolecraft install npm:lodash
rolecraft install npm:@scope/package
rolecraft install npm:package@1.0.0
rolecraft install npm:@scope/package@latest

The CLI fetches package metadata from the npm registry, downloads and extracts the tarball, finds SKILL.md recursively, installs it, and cleans up.

Selection flags

Flag	Description
--list	List available skills from the source without installing
--skill <names>	Install specific skills by name (comma-separated or repeated flag)

The --skill flag accepts skill names in two formats:

# Comma-separated
rolecraft install source --skill "grill-me,tdd"

# Repeated flag
rolecraft install source --skill grill-me --skill tdd

# Mixed
rolecraft install source --skill grill-me,tdd --skill ask-matt

Skill names are matched against the skill name or slug (case-insensitive).

Without these flags and with more than one skill found, you will be prompted interactively to select which skills to install.

Scope flags

Flag	Target directory
--project	./.agents/skills/ (default)
--global	~/.agents/skills/
--all	all known agent directories
--agents	~/.agents/skills/ (opencode)
--claude	~/.claude/skills/
--cursor	~/.cursor/skills/
--windsurf	~/.codeium/windsurf/skills/
--devin	./.devin/skills/
--codex	~/.agents/skills/
--copilot	./.github/skills/
(79 more agent flags — see docs/agents.md)

Mode flags

Flag	Description
--symlink	Symlink instead of copy
--copy	Force copy (default)
--dry-run	Preview without copying files
--frozen-lockfile	Fail if skill is already installed
--yes, -y	Non-interactive: accept all defaults and skip prompts
--no-mcp	Skip MCP server installation from skill

Examples

# Install from local folder (default: project scope)
rolecraft install ./my-skill

# Install from GitHub (monorepo)
rolecraft install rolecraft-sh/skills

# Install from a multi-skill repo (interactive selection)
rolecraft install mattpocock/skills

# List skills in a repo without installing
rolecraft install mattpocock/skills --list

# Install specific skills by name (comma-separated)
rolecraft install mattpocock/skills --skill "grill-me,tdd"

# Install specific skills (repeated flag)
rolecraft install mattpocock/skills --skill grill-me --skill tdd

# Install from npm
rolecraft install npm:some-skill-package
rolecraft install npm:@org/skill-package@1.0.0

# Install for specific agents
rolecraft install ./my-skill --claude --cursor

# Combine multiple agents
rolecraft install ./my-skill --claude --cursor --devin

# Global install
rolecraft install ./my-skill --global

# Symlink instead of copy
rolecraft install ./my-skill --symlink

# Preview only
rolecraft install ./my-skill --dry-run

# Fail if already installed
rolecraft install ./my-skill --frozen-lockfile

Multi-skill repositories

When a source contains multiple SKILL.md files (e.g., mattpocock/skills has 15+ skills under skills/engineering/ and skills/productivity/), the CLI:

1. Discovers all skills by scanning skills/, .agents/skills/, and other known container directories, plus a recursive fallback search (max depth 3).
2. If --list is passed, prints all available skills and exits.
3. If --skill is passed, installs only the matching skills.
4. If --yes is passed, installs all skills without prompting.
5. Otherwise, shows an interactive numbered list to select skills.

Each skill is installed to its own subdirectory (slug-based name) under the target agent's skills directory.

Interactive selection example

$ rolecraft install mattpocock/skills

Resolving skills...
Found 15 skill(s)

  1. ask-matt
      slug: ask-matt
  2. domain-modeling
      slug: domain-modeling
  3. diagnosing-bugs
      slug: diagnosing-bugs
  4. grill-me
      slug: grill-me
  5. grill-with-docs
      slug: grill-with-docs
  6. grilling
      slug: grilling
  ...

Enter numbers (space-separated) to select, "all" for all, or press Enter to confirm selection: 4 5

   grill-me selected
   grill-with-docs selected

--list output example

$ rolecraft install mattpocock/skills --list

Found 15 skill(s)

  ask-matt
    Slug:       ask-matt
    Owner:      mattpocock
    Description: Ask which skill or flow fits your situation
    Files:      SKILL.md

  grill-me
    Slug:       grill-me
    Owner:      mattpocock
    Description: Get relentlessly interviewed about a plan or design
    Files:      SKILL.md

  ...

--skill usage example

# Install specific skills (comma-separated)
rolecraft install mattpocock/skills --skill "grill-me,tdd"

# Install specific skills (repeated flag)
rolecraft install mattpocock/skills --skill grill-me --skill tdd

# Install a single skill
rolecraft install mattpocock/skills --skill diagnose-bugs

# Non-interactive: install all skills with --yes
rolecraft install mattpocock/skills --yes --global

Node.js API

This command is also available as a programmatic function. See the Node.js API documentation for detailed usage.

import { install } from 'rolecraft'
const result = await install('./my-skill', { global: true })