skillit

skillit

skillit — Compile-time generator of AI agent skills from your codebase.

Inline docs, CLI definitions, config schemas, and examples compile into progressively disclosed SKILL.md files that any LLM can discover. Integrated with TypeDoc, with support for conventional repo docs, and plugins for Docusaurus and VitePress provided for what code can't cover.

MCP Servers (orthogonal workflow)

skillit can also generate skills from any live MCP server, even when the server was not authored with skillit.

This is separate from the TypeDoc/docs extraction flow above: it introspects MCP tools/resources/prompts over stdio or HTTP and emits a progressive-disclosure SKILL.md. You can render:

• native MCP launch instructions (mcp: frontmatter in SKILL.md, which tells MCP-capable agents how to start/connect to the server), or
• CLI-proxy launch instructions for non-MCP harnesses (such as mcpc/fastmcp).

# Inspect any running or launchable MCP server and generate skills
npx skillit mcp extract \
  --command "npx -y @modelcontextprotocol/server-filesystem /tmp" \
  --out ./skills

# Optional: install non-default CLI invocation adapters
npm install --save-dev @skillit/target-mcpc @skillit/target-fastmcp

# Emit CLI-proxy invocation variants for non-MCP agents
npx skillit mcp extract \
  --command "npx -y @modelcontextprotocol/server-filesystem /tmp" \
  --invocation cli:mcpc \
  --invocation cli:fastmcp \
  --out ./skills

For server package authors, skillit mcp bundle can be run in your build to ship pre-generated skills with your MCP package.

See packages/mcp/README.md for install, extract, bundle, config-file batch mode (mcp.json / claude_desktop_config.json), and programmatic API details.

Bootstrap (recommended): /skillit-bootstrap

The primary way to create or improve a skill is the /skillit-bootstrap Claude Code skill (bundled with @skillit/client). It runs the deterministic generate → audit loop and lets the agent enrich your repo's source (JSDoc, README, examples, package.json) until the skill hits its grade target — you never hand-edit a SKILL.md.

# Install the bundled skill into your user skill roots (one time)
mkdir -p ~/.claude/skills ~/.copilot/skills ~/.agents/skills
cp -R node_modules/@skillit/client/skills/skillit-bootstrap ~/.claude/skills/
cp -R node_modules/@skillit/client/skills/skillit-bootstrap ~/.copilot/skills/
cp -R node_modules/@skillit/client/skills/skillit-bootstrap ~/.agents/skills/

# Then, in your agent:
/skillit-bootstrap --source cli --program ./dist/cli.js#program
/skillit-bootstrap --source typedoc

Supported sources this release: cli and typedoc. For config / mcp, use skillit refine (below); slash-command support for those lands in a later phase. The CLI commands (skillit gen, skillit audit --json, skillit refine) remain for headless/CI use.

Init: detect → install

skillit init wires a project up. It detects the project's nature and installs the matching @skillit/* package with your package manager, then points you at skillit gen to produce the skill. It does not generate or refine — those are separate, explicit commands (skillit gen, skillit refine).

# Auto-detects nature and package manager, installs the right @skillit package
npx skillit init

# Force the source kind
npx skillit init --source mcp

# Config source is built in (no install) — init just points at `skillit gen`
npx skillit init --source config --config-type ./src/config.ts#MyConfig

Detection:

• Nature — commander / yargs dep → cli; @modelcontextprotocol/sdk → mcp; otherwise a plain TS library → typedoc. Override with --source.
• Package — cli → @skillit/cli, mcp → @skillit/mcp, typedoc → typedoc-plugin-skillit. The config source is built into the CLI (no install).
• Package manager — pnpm-lock.yaml → pnpm, yarn.lock → yarn, else npm.

If the install step fails, init prints the exact add command and stops.

Gen: deterministic skill generation

skillit gen (re)generates the skill from the current source — no install, no model, no network. It is the deterministic, side-effect-free generate primitive: the same source always yields the same skill. Run it after init, and again whenever you change the documented source (JSDoc, config type, README).

# Generate from the auto-detected source into skills/
npx skillit gen

# CLI source with an explicit commander program entry
npx skillit gen --source cli --program ./dist/cli.js#program

# Config source
npx skillit gen --source config --config-type ./src/config.ts#MyConfig

# Generate into a custom directory (default: skills)
npx skillit gen --out docs/skills

Audit: score + findings as JSON

skillit audit runs the same audit + judge the refine loop uses and prints the result. With --json it emits the full AuditResult + score estimate, plus a resolved on-disk location for each improvement target — the machine-readable read-surface an agent (or CI) can act on without re-deriving anything.

# Human summary (grade + severity counts)
npx skillit audit --source cli

# Full machine-readable report
npx skillit audit --source config --config-type ./src/config.ts#MyConfig --json

Refine: autonomous annotation loop

skillit refine runs an audit → draft → review loop that iteratively improves the useWhen / avoidWhen annotations in your generated skills. On each pass it asks an LLM to evaluate the current guidance, proposes improvements, and applies them — no manual editing required.

Refine is source-aware. It auto-detects the source from the installed @skillit/* package, or you can choose explicitly:

# CLI source — writes guidance back into the *Options interface JSDoc
npx skillit refine --source cli --program ./dist/cli.js#program

# MCP source (see modes below)
npx skillit refine --source mcp --mcp ./mcp.json

For the cli source, refine writes annotations into the JSDoc of your typed *Options interfac