@skill-tools/gen

Generate Agent Skills (SKILL.md) from 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 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 deploy-vercel "Deploy apps to Vercel"

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

Library API

generateFromOpenApi(specPath, options?)

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

import { generateFromOpenApi } from 'skillgen';

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

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 Specs

Security