---
description: Programmatic Node.js API for installing, listing, searching and managing skills from your own scripts and CI pipelines.
---

# Node.js API

rolecraft exposes a programmatic API for use in your own Node.js scripts, tools, and CI pipelines. All API functions return plain objects with no side-effects.

## Usage

```js
import { install, list, search, doctor } from 'rolecraft'

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

// list installed skills
const skills = await list()

// search GitHub for skills
const results = await search('code-review')

// run health check
const health = await doctor()
```

## Available Functions

### `install(source, options?)`

Install a skill with security scan.

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `global` | `boolean` | `false` | Install to `~/.agents/skills/` |
| `project` | `boolean` | `true` | Install to `./.agents/skills/` |
| `scope` | `object` | `{ project: true }` | Target scope object (`{ project, global, [agentFlag]: true, ... }`); overrides `global`/`project` |
| `yes` | `boolean` | `false` | Bypass security prompts |
| `dryRun` | `boolean` | `false` | Preview only |
| `symlink` | `boolean` | `false` | Symlink instead of copy |
| `frozenLockfile` | `boolean` | `false` | Fail if already installed |
| `noMcp` | `boolean` | `false` | Skip MCP server installation |
| `skill` | `string\|string[]` | — | Specific skill slug(s) |

Returns `{ results: [{ name, slug, owner, security, install }], mcpResults?: [...] }`.

### `rollback(slug, options?)`

Restore a skill to its previous version from backup history. History is created automatically on `update` or re-install.

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `list` | `boolean` | `false` | Show history without restoring |
| `dryRun` | `boolean` | `false` | Preview without restoring |

Returns `{ slug, files, targets, prevContentSha }`.

Or with `list: true`: `{ slug, currentVersion, history: [{ version, contentSha, installedAt }] }`.

### `list(cwd?, options?)`

List installed skills.

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `json` | `boolean` | `false` | Return structured data |
| `agent` | `string` | — | Filter skills by agent name (case-insensitive) |

Returns `{ skills: { [slug]: { name, slug, owner, description, source, sourceType, scope, installedAt, contentSha, ... } }, total: number, globals: number, projects: number, agent?: string }`.

### `remove(slug, options?)`

Uninstall a skill.

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `dryRun` | `boolean` | `false` | Preview only |

Returns `{ removed: [...], targets: [...] }`.

### `update(slug, options?)`

Re-install a skill from its original source.

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `dryRun` | `boolean` | `false` | Preview only |

Returns `{ slug, source, updated: boolean }`.

### `check(options?)`

Check installed skills for available updates.

Returns `{ skills: [{ slug, status: 'update_available'|'up_to_date'|'error', current?, latest?, source?, fromRegistry?, oldHash?, newHash?, hash?, reason? }], updatesAvailable: number, total: number }`.

### `verify(options?)`

Verify SHA256 content hashes of installed skills.

Returns `{ verified: [...], failed: [...] }`.

### `ci(options?)`

Re-install all skills and MCP servers from lockfile.

Takes no options. Non-interactive by design — installs everything from the lockfile.

Returns `{ installed: [{ slug, name, scope }], failed: [{ slug, reason }], skillCount, mcpCount, total, allPassed, mcpInstalled: [{ name, agents }], mcpFailed: [{ name, reason }] }`.

### `search(query, options?)`

Search for skills on GitHub or skills.sh.

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `skillsSh` | `boolean` | `false` | Search skills.sh instead of GitHub |
| `interactive` | `boolean` | `false` | Enable TUI picker |

Returns `{ results: [{ full_name, description, stargazers_count, language }], source: 'github'|'skills.sh' }`.

### `doctor(options?)`

Run system health check.

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `json` | `boolean` | `false` | Return structured data |
| `network` | `boolean` | `false` | Include GitHub connectivity test |
| `deep` | `boolean` | `false` | Run conflict detection across all installed skills |

Returns `{ status, checks: [...], summary: { passed, warnings, errors, total }, agents, mcp, skills, conflicts }`.

When `deep: true`, the `conflicts` array contains objects shaped as `{ a, b, sections: [{ heading, a, b }] }` where `a` and `b` are conflicting skill slugs and each section lists up to 3 differing lines from each skill.

### `use(source, options?)`

Preview a skill's files without installing.

Returns `{ name, slug, files: [...], targets: [...] }`.

### `resolve(source)`

Resolve a source string to its metadata. Returns `{ slug, name, files, contentSha, ... }`.

### `resolveSkills(source)`

Resolve a source string and discover all skills within it (including multi-skill repos). Used internally by `install`, `use`, and `setup`.

Returns `[{ slug, name, description, owner, files, sourcePath, sourceType, content }]`.

### `diff(skillA, skillB, options?)`

Section-aware comparison of two SKILL.md files.

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `json` | `boolean` | `false` | Return structured JSON |
| `brief` | `boolean` | `false` | Show only summary of changes |
| `noColor` | `boolean` | `false` | Disable colored output |

Returns `{ a, b, frontmatter, sections: [{ heading, status, added, removed }], stats }`.

### `compose(sources, options?)`

Merge or chain multiple SKILL.md files into one.

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `mode` | `string` | `'merge'` | `'merge'` (dedup lines) or `'chain'` (override) |
| `name` | `string` | — | Output skill name |
| `json` | `boolean` | `false` | Return structured JSON |
| `noColor` | `boolean` | `false` | Disable colored output |

Returns `{ content, stats: { sources, totalInputSections, totalOutputSections, mergedSections, frontmatterFields } }`.

### `test(skillPath, options?)`

Run quality assertions against a SKILL.md file.

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `all` | `boolean` | `false` | Test all installed skills |
| `json` | `boolean` | `false` | Return structured JSON |
| `verbose` | `boolean` | `false` | Show detailed results |
| `noColor` | `boolean` | `false` | Disable colored output |
| `noEmoji` | `boolean` | `false` | Use ASCII fallback for emojis |
| `minScore` | `number` | `0` | Fail if score is below threshold |
| `only` | `string\|string[]` | — | Run specific checks by name |

Returns `{ skill, score, grade, label, assertions: [...], suggestions: [...] }`. With `--all`, returns `{ results: [...], summary: { total, passed, failed, skipped } }`.

### `mcpInstall(source, options?)`

Install an MCP server.

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `name` | `string` | — | Override the server name |
| `yes` | `boolean` | `false` | Skip confirmation and security blocks |
| `dryRun` | `boolean` | `false` | Preview without making changes |

Returns `{ name, source, resolved: { command, args }, results: [{ agent, name, success }], scanResult }`.

### `mcpList(options?)`

List all installed MCP servers.

Returns `{ servers: [{ agent, name, command, args }], total: number }`.

### `mcpUpdate(name, options?)`

Update an MCP server.

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `name` | `string` | — | Server name override |
| `yes` | `boolean` | `false` | Skip confirmation |
| `dryRun` | `boolean` | `false` | Preview without making changes |

Returns `{ name, source, resolved: { command, args }, results: [{ agent, name, success }] }`.

### `mcpRemove(name, options?)`

Remove an MCP server.

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `dryRun` | `boolean` | `false` | Preview only |

Returns `{ name, results: [{ agent, name, success }] }`.

### `mcpCheck(options?)`

Check MCP server health.

Returns `{ servers: [{ agent, name, currentVersion, latestVersion, hasUpdate }], updatesAvailable: number, total: number }`.

### `mcpSearch(query, options?)`

Search for MCP servers on npm or GitHub.

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `npm` | `boolean` | `false` | Search npm registry instead of GitHub |
| `interactive` | `boolean` | `false` | Enable TUI picker |

Returns `{ results: [{ name, description, source, stars }], source: 'npm'|'github', total: number }`.

### `profileSave(name, options?)`

Save current agent configuration as a profile. Returns `{ name, agents: number, profile: { name, description, agents } }`.

### `profileApply(name, options?)`

Apply a saved profile.

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `dryRun` | `boolean` | `false` | Preview only |
| `skipMcp` | `boolean` | `false` | Skip MCP configuration |
| `skipSkills` | `boolean` | `false` | Skip skill installation |
| `yes` | `boolean` | `false` | Non-interactive mode |

Returns `{ agents: [...], mcp: [...], skills: [...] }`.

### `profileDiff(name)`

Compare current config against a saved profile. Returns `{ added: [...], removed: [...], changed: [...] }`.

### `profileList()`

List all saved profiles. Returns `{ profiles: [...] }`.

### `profileShow(name)`

Show profile details. Returns `{ name, agents: {...}, createdAt, updatedAt }`.

### `profileDelete(name)`

Delete a saved profile. Returns `{ deleted: true }`.

### `profileImport(source)`

Import a profile from file or URL. Returns `{ name, agents: number }`.

### `setup(source, options?)`

Detect agents and optionally install a skill to all detected agents.

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `yes` | `boolean` | `false` | Install all skills without prompt |
| `dryRun` | `boolean` | `false` | Preview only |
| `list` | `boolean` | `false` | List available skills without installing |
| `skill` | `string\|string[]` | — | Install specific skills by name |
| `candidates` | `boolean` | `false` | Return the resolved skills without selecting or installing |

Returns `{ agents: [{ flag, label }], installed?: [{ name, slug, owner, files, results, mcpServers }] }`. With `list: true`, returns `{ agents, skills: [{ name, slug, owner, description, files }] }`. With `candidates: true`, returns `{ agents, candidates: [{ name, slug, description }] }` and writes nothing — read the list, then call again with `skill` to install a choice.

### `bundle(sources, options?)`

Install multiple skills from inline sources or a bundle file.

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `dryRun` | `boolean` | `false` | Preview only |
| `noMcp` | `boolean` | `false` | Skip MCP server installation |

Returns `{ installed: number, failed: number, results: [{ source, status, error? }] }`.

### `watch(slug?, cwd?, options?)`

Watch installed local skills for file changes and auto-sync.

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `dryRun` | `boolean` | `false` | Preview only |
| `onEvent` | `(event) => void` | none | Called for setup and sync events (see below) |

Returns `{ watchers: FSWatcher[], skills: string[], installedCount: number, close: () => void }`. Call `close()` to cancel pending syncs and close every watcher; it is safe to call more than once. With `dryRun`, returns `{ dryRun: true, skills: [{ slug, source, path }] }` instead.

Throws a `UserError` with code `WATCH_SKILL_NOT_FOUND` when `slug` is not installed.

`onEvent` receives objects with a `type` field:

| `type` | Extra fields | When |
|--------|--------------|------|
| `start` | `slugs` | Before watchers are set up |
| `skip` | `slug`, `sourceType` | A non-local skill was requested |
| `watching` | `slug`, `path` | A watcher started |
| `error` | `slug`, `path`, `error` | A watcher could not start, or reported an error later |
| `syncing` | `slug`, `filename`, `startedAt` | A change triggered a re-install |
| `synced` | `slug`, `ok`, `startedAt` | The re-install finished (`ok: false` on failure) |

### `convert(source, options?)`

Convert skills bidirectionally between rolecraft's `SKILL.md` format and Cursor/Claude Code's `.mdc` rule format. Programmatic implementation is in [`src/api/convert.js`](https://github.com/rolecraft-sh/rolecraft/blob/main/src/api/convert.js).

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `dryRun` | `boolean` | `false` | Preview conversion plan without writing files or creating directories |
| `output` | `string` | `process.cwd()` | Target output directory (created recursively if missing in write mode) |

#### Return Value

`convert()` always returns an array of result objects (one per converted file), even when passed a single file path:

- **Write mode (`dryRun: false`):** Returns `[{ from: string, to: string, format: 'skill-to-mdc' | 'mdc-to-skill' }]`. Files are written to disk.
- **Dry-run mode (`dryRun: true`):** Returns `[{ dryRun: true, from: string, to: string }]`. Returns the planned destination paths without creating directories or writing any files to disk (`format` is omitted in dry-run mode).

#### Destination Path Resolution

The destination filename is determined by the input format:

- **SKILL.md → .mdc (`skill-to-mdc`):** Destination filename is derived from the skill's frontmatter slug or name (`${slug}.mdc`, falling back to `skill.mdc`). Slashes in slugs are normalized to dashes.
- **.mdc → SKILL.md (`mdc-to-skill`):** Destination filename is always `SKILL.md` inside the specified `output` directory (`path.join(outDir, 'SKILL.md')`).

#### Source Resolution and Format Detection

1. **Directories:** `convert()` checks for `SKILL.md` first. If found, only that skill file is converted to `.mdc`. If no `SKILL.md` exists, it scans for all `*.mdc` files in the directory and converts each one to `SKILL.md`. If neither is found, it throws `No SKILL.md or .mdc files found in <dir>`.
2. **Single Files:** If a file does not use the standard name `SKILL.md` or `.mdc` extension (e.g. `rules.txt`), `convert()` sniffs frontmatter keys: `slug:` detects a skill file, while `alwaysApply:` or `globs:` detects an MDC rule. If neither is found, it throws `Cannot detect format`.
3. **Empty Files:** Throws `Source is empty: <path>`.

#### Example

```js
import { convert } from 'rolecraft'

// Preview conversion plan without writing files
const plan = await convert('./rules/cursor-rule.mdc', {
  dryRun: true,
  output: './converted',
})

console.log(plan)
// [
//   {
//     dryRun: true,
//     from: '/path/to/rules/cursor-rule.mdc',
//     to: '/path/to/converted/SKILL.md',
//   }
// ]

// Execute the actual conversion
const results = await convert('./rules/cursor-rule.mdc', {
  output: './converted',
})

console.log(results)
// [
//   {
//     from: '/path/to/rules/cursor-rule.mdc',
//     to: '/path/to/converted/SKILL.md',
//     format: 'mdc-to-skill',
//   }
// ]
```

### `init(name?)`

Scaffold a new SKILL.md file.

| Param | Type | Description |
|-------|------|-------------|
| `name` | `string` | Skill name or `owner/name` (default: `my-skill`) |

Returns `{ path: string, slug: string, name: string, owner: string }`.

### `upgrade(options?)`

Check for rolecraft updates and upgrade.

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `dryRun` | `boolean` | `false` | Check without upgrading |

Returns `{ current: string, latest: string|null, isUpToDate: boolean|null, upgraded?: boolean, version?: string }`.

### `completions(shell)`

Generate shell completion script.

| Param | Type | Description |
|-------|------|-------------|
| `shell` | `string` | `'bash'`, `'zsh'`, or `'fish'` |

Returns the completion script as a string.

### `agentsXml(writeToFile?)`

Generate a `<skills_system>` XML block listing installed skills.

| Param | Type | Default | Description |
|-------|------|---------|-------------|
| `writeToFile` | `boolean` | `false` | Write or replace XML section in `./AGENTS.md` |

Returns `{ xml: string, written: boolean, path?: string }`.

### `compareVersions(a, b)`

Compare two semver version strings. Returns negative, zero, or positive number.

## See also

- [CLI Reference](reference.md) — every command with all flags on one page.
- [Commands](commands/index.md) — each command grouped by what you are trying to do.
- [Architecture](architecture.md) — how rolecraft is put together under the hood.