@skill-tools/gen

Generate Agent Skills (SKILL.md) from MCP servers, OpenAPI 3.x specifications, or plain text descriptions. Outputs spec-compliant files ready for validation with skill-tools. 

npm install -g @skill-tools/gen

CLI Usage

From MCP server

Connect to any MCP server, introspect its tools, and generate a lean SKILL.md with grouped tool reference and a full references/TOOLS.md.

# From a stdio MCP server
skillgen mcp --command npx --args "-y @modelcontextprotocol/server-github"

# With environment variables
skillgen mcp --command npx --args "-y @modelcontextprotocol/server-github" \
  --env GITHUB_TOKEN=ghp_xxx -o ./skills/ -n github

# From a remote MCP server (HTTP/SSE)
skillgen mcp --url https://mcp.example.com/sse -n my-server

# With options
skillgen mcp --command npx --args "-y @modelcontextprotocol/server-filesystem /tmp" \
  --max-tokens 3000 --timeout 60000 --no-tool-reference

From OpenAPI spec

# Unified mode (one SKILL.md per API)
skillgen openapi ./petstore.json

# Per-endpoint mode (one SKILL.md per operation)
skillgen openapi ./api.yaml --mode per-endpoint --out ./skills/

# With options
skillgen openapi ./spec.json --name my-api --no-examples --max-tokens 3000

From text description

# Basic
skillgen from-text bap-browser "AI-powered browser automation via BAP"

# With instructions
skillgen from-text run-tests "Execute test suites" \
  --instructions "1. Run npm test\n2. Check coverage"

MCP Generation

The skillgen mcp command connects to an MCP server, discovers all available tools via tools/list, clusters them by domain, and generates a two-file skill package:

Tools are automatically clustered by shared domain nouns extracted from tool names. For example, create_issue, get_issue, and list_issues are grouped under “Issues”.

MCP CLI Options

Option Default Description
--command <cmd> — Command to start MCP server (stdio transport)
--args <args...> — Arguments for the command
--env <KEY=VAL...> — Environment variables (repeatable)
--url <url> — Remote MCP server URL (HTTP/SSE)
-n, --name auto-detected Skill name override (kebab-case)
--timeout <ms> 30000 Connection timeout
--no-tool-reference — Skip generating references/TOOLS.md
--max-tokens <n> 4000 Token budget (warns if exceeded)
-d, --description auto-generated Custom description override

The MCP SDK (@modelcontextprotocol/sdk) is an optional peer dependency — only needed when using skillgen mcp. Install it with npm install @modelcontextprotocol/sdk.

Library API

MCP

generateFromMcp(connectionOptions, generateOptions?)

Connect to a live MCP server, introspect tools, and generate SKILL.md files.

import { generateFromMcp } from '@skill-tools/gen';

const result = await generateFromMcp(
  { command: 'npx', args: ['-y', '@modelcontextprotocol/server-github'] },
  { name: 'github', maxTokens: 4000 },
);

if (result.ok) {
  console.log(`${result.toolCount} tools in ${result.groupCount} groups`);
  for (const [path, content] of result.files) {
    console.log(path, content.length);
  }
}

generateFromMcpSpec(spec, options?)

Generate from a pre-parsed McpServerSpec. Useful for testing or when you already have the spec.

introspectMcpServer(options)

Connect to an MCP server and return a structured McpServerSpec without generating files.

parseMcpToolsJson(json, name?)

Parse a JSON string (matching MCP tools/list response) into a McpServerSpec. Useful for testing without a live server.

clusterTools(tools)

Group an array of McpToolSpec objects by shared domain nouns. Returns McpToolGroup[].

renderMcpSkillMd(spec, options?)

Render SKILL.md + TOOLS.md content from an McpServerSpec. Returns a Map<filePath, content>.

OpenAPI

generateFromOpenApi(specPath, options?)

Reads an OpenAPI spec, parses it, and generates SKILL.md files.

import { generateFromOpenApi } from '@skill-tools/gen';

const result = await generateFromOpenApi('./petstore.json', {
  mode: 'unified',
  maxTokens: 4000,
});

if (result.ok) {
  for (const [path, content] of result.files) {
    console.log(path, content.length);
  }
}

generateFromSpec(spec, options?)

Generate from a pre-parsed ApiSpec. Useful for programmatic pipelines.

generateFromText(name, description, instructions?)

Lightweight generator for simple skills without an API spec.

parseOpenApi(content)

Parse an OpenAPI 3.x document (JSON or YAML string) into the intermediate ApiSpec representation.

renderSkillMd(spec, options?)

Render SKILL.md content from an ApiSpec. Returns a Map<filePath, content>.

OpenAPI Generation Options

Option Default Description
name derived from spec title Skill name override (kebab-case)
outDir . Output directory
mode unified unified or per-endpoint
maxTokens 4000 Token budget (warns if exceeded)
includeExamples true Include curl examples
includeErrorHandling true Include error handling section
description derived from spec Custom description override

Supported Input Sources

OpenAPI support includes auth schemes (API key, Bearer, Basic, OAuth2), parameters (path, query, header), and request/response body schema introspection.

Security

Test Coverage

73 tests across 5 suites. Run with npx vitest run from the package directory.

generator.test.ts (10 tests)

renderer.test.ts (16 tests)

openapi.test.ts (12 tests)

mcp.test.ts (18 tests)

mcp-renderer.test.ts (17 tests)