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

import { install, list, search, doctor, searchRegistry } 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')

// search the registry for skills
const registryResults = await searchRegistry('react')

// 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/`
`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 { updates: [{ slug, hasUpdate }], current: [...] }.

`verify(options?)`

Verify SHA256 content hashes of installed skills.

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

`ci(options?)`

Re-install all skills and MCP servers from lockfile.

Option	Type	Default	Description
`yes`	`boolean`	`false`	Non-interactive mode
`dryRun`	`boolean`	`false`	Preview only
`frozenLockfile`	`boolean`	`false`	Fail if lockfile changes

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 { server: { name, command, args }, agent, configPath }.

`mcpList(options?)`

List all installed MCP servers.

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

`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 { server: { name, command, args } }.

`mcpRemove(name, options?)`

Remove an MCP server.

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

Returns { removed: true }.

`mcpCheck(options?)`

Check MCP server health.

Returns { servers: [{ name, currentVersion, latestVersion, hasUpdate }], updatesAvailable: 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 }] }.

`profileSave(name, options?)`

Save current agent configuration as a profile. Returns { agents: number }.

`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 }.

`searchRegistry(query)`

Search the registry index by slug, name, or description.

Param	Type	Description
`query`	`string`	Search term

Returns [{ slug, name, description, repo, author, versions, latest }].

`registryResolve(slug)`

Resolve a registry slug to its full skill metadata.

Param	Type	Description
`slug`	`string`	Registry slug (e.g. `"react-rules"`)

Returns { slug, name, description, repo, author, versions, latest }. Throws if not found.

`registryPublish(entry, token?)`

Fork the registry repo, update index.json, and open a PR.

Param	Type	Default	Description
`entry`	`object`	—	`{ slug, name, repo, description?, version? }`
`token`	`string`	`GITHUB_TOKEN` env	GitHub personal access token

Returns { url, number } (PR URL and number).

`registryCheckUpdates(skills)`

Compare installed skills against registry and detect newer versions.

Param	Type	Description
`skills`	`array`	`[{ slug, name, version }]`

Returns [{ slug, name, current, latest }].

`registryInfo(slug)`

Get detailed info about a single registry skill.

Param	Type	Description
`slug`	`string`	Registry slug

Returns the full skill entry. Throws if not found.

`registryList()`

List all skills in the registry. Returns [{ slug, name, description, repo, author, versions, latest }].

`registryClearCache()`

Clear the in-memory registry index cache. Next registry call will re-fetch from GitHub.

`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

Returns { agents: [{ flag, label }], installed?: [{ name, slug, results }] }. With list: true, returns { agents, skills: [{ name, slug, owner, description, files }] }.

`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

Returns { watchers: FSWatcher[], skills: string[] }. The caller is responsible for managing the watcher lifecycle.

`convert(source, options?)`

Convert skills between SKILL.md and .mdc formats.

Option	Type	Default	Description
`dryRun`	`boolean`	`false`	Preview only
`output`	`string`	`process.cwd()`	Output directory

Returns [{ from: string, to: string, format?: 'skill-to-mdc'\|'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.

Uh oh!

FilesExpand file tree

api.md

Latest commit

History

api.md

File metadata and controls

Node.js API

Usage

Available Functions

install(source, options?)

rollback(slug, options?)

list(cwd?, options?)

remove(slug, options?)

update(slug, options?)

check(options?)

verify(options?)

ci(options?)

search(query, options?)

doctor(options?)

use(source, options?)

resolve(source)

resolveSkills(source)

diff(skillA, skillB, options?)

compose(sources, options?)

test(skillPath, options?)

mcpInstall(source, options?)

mcpList(options?)

mcpUpdate(name, options?)

mcpRemove(name, options?)

mcpCheck(options?)

mcpSearch(query, options?)

profileSave(name, options?)

profileApply(name, options?)

profileDiff(name)

profileList()

profileShow(name)

profileDelete(name)

profileImport(source)

searchRegistry(query)

registryResolve(slug)

registryPublish(entry, token?)

registryCheckUpdates(skills)

registryInfo(slug)

registryList()

registryClearCache()

setup(source, options?)

bundle(sources, options?)

watch(slug?, cwd?, options?)

convert(source, options?)

init(name?)

upgrade(options?)

completions(shell)

agentsXml(writeToFile?)

compareVersions(a, b)