@skill-tools/gen 0.2.0

package/dist/index.d.ts

@@ -0,0 +1,196 @@
+/**
+ * Configuration for generating a SKILL.md file.
+ */
+interface GenerateOptions {
+    /** Skill name (kebab-case, max 64 chars). Auto-derived if not provided. */
+    readonly name?: string;
+    /** Output directory path. Defaults to current working directory. */
+    readonly outDir?: string;
+    /** Generation mode: one skill per endpoint or one unified skill */
+    readonly mode?: 'unified' | 'per-endpoint';
+    /** Maximum token budget for the generated SKILL.md (default: 4000) */
+    readonly maxTokens?: number;
+    /** Include example requests/responses in the output */
+    readonly includeExamples?: boolean;
+    /** Include error handling section */
+    readonly includeErrorHandling?: boolean;
+    /** Custom description override */
+    readonly description?: string;
+}
+/**
+ * Intermediate representation of an API parsed from any source.
+ */
+interface ApiSpec {
+    /** API title */
+    readonly title: string;
+    /** API description/summary */
+    readonly description: string;
+    /** Base URL(s) */
+    readonly servers: readonly string[];
+    /** API version */
+    readonly version: string;
+    /** Parsed endpoints */
+    readonly endpoints: readonly ApiEndpoint[];
+    /** Authentication schemes */
+    readonly auth: readonly AuthScheme[];
+}
+/**
+ * A single API endpoint.
+ */
+interface ApiEndpoint {
+    /** HTTP method (GET, POST, etc.) */
+    readonly method: string;
+    /** URL path (e.g. /users/{id}) */
+    readonly path: string;
+    /** Operation ID (e.g. getUser) */
+    readonly operationId?: string;
+    /** Summary (short description) */
+    readonly summary?: string;
+    /** Detailed description */
+    readonly description?: string;
+    /** Tags for grouping */
+    readonly tags: readonly string[];
+    /** Path + query + header parameters */
+    readonly parameters: readonly ApiParameter[];
+    /** Request body schema */
+    readonly requestBody?: ApiRequestBody;
+    /** Response schemas by status code */
+    readonly responses: readonly ApiResponse[];
+}
+/**
+ * An API parameter (path, query, header, cookie).
+ */
+interface ApiParameter {
+    /** Parameter name */
+    readonly name: string;
+    /** Location: path, query, header, cookie */
+    readonly in: 'path' | 'query' | 'header' | 'cookie';
+    /** Description */
+    readonly description?: string;
+    /** Whether the parameter is required */
+    readonly required: boolean;
+    /** Schema type (string, integer, etc.) */
+    readonly type?: string;
+    /** Example value */
+    readonly example?: unknown;
+}
+/**
+ * Request body definition.
+ */
+interface ApiRequestBody {
+    /** Description */
+    readonly description?: string;
+    /** Content type (e.g. application/json) */
+    readonly contentType: string;
+    /** Whether the body is required */
+    readonly required: boolean;
+    /** Schema properties (flattened) */
+    readonly properties: readonly ApiProperty[];
+    /** Example body */
+    readonly example?: unknown;
+}
+/**
+ * A property in a request/response body.
+ */
+interface ApiProperty {
+    /** Property name */
+    readonly name: string;
+    /** Schema type */
+    readonly type: string;
+    /** Description */
+    readonly description?: string;
+    /** Whether the property is required */
+    readonly required: boolean;
+    /** Example value */
+    readonly example?: unknown;
+}
+/**
+ * An API response definition.
+ */
+interface ApiResponse {
+    /** HTTP status code (e.g. "200", "404") */
+    readonly statusCode: string;
+    /** Description */
+    readonly description?: string;
+    /** Content type */
+    readonly contentType?: string;
+    /** Schema properties (flattened) */
+    readonly properties: readonly ApiProperty[];
+}
+/**
+ * Authentication scheme.
+ */
+interface AuthScheme {
+    /** Scheme type */
+    readonly type: 'apiKey' | 'http' | 'oauth2' | 'openIdConnect';
+    /** Scheme name */
+    readonly name: string;
+    /** Description */
+    readonly description?: string;
+    /** For apiKey: where the key goes */
+    readonly in?: 'header' | 'query' | 'cookie';
+    /** For http: scheme (bearer, basic) */
+    readonly scheme?: string;
+}
+/**
+ * Result of a generation operation.
+ */
+interface GenerateResult {
+    /** Whether generation succeeded */
+    readonly ok: true;
+    /** Generated files (path → content) */
+    readonly files: ReadonlyMap<string, string>;
+    /** Number of endpoints processed */
+    readonly endpointCount: number;
+    /** Estimated token count of generated content */
+    readonly tokenCount: number;
+}
+/**
+ * Error result from generation.
+ */
+interface GenerateError {
+    readonly ok: false;
+    readonly error: string;
+}
+
+/**
+ * Generate SKILL.md files from an OpenAPI specification file.
+ *
+ * @param specPath - Path to an OpenAPI 3.x spec (JSON or YAML)
+ * @param options - Generation options
+ * @returns Generation result with files map, or an error
+ */
+declare function generateFromOpenApi(specPath: string, options?: GenerateOptions): Promise<GenerateResult | GenerateError>;
+/**
+ * Generate SKILL.md files from a pre-parsed ApiSpec.
+ *
+ * @param spec - The API specification
+ * @param options - Generation options
+ * @returns Generation result with files map
+ */
+declare function generateFromSpec(spec: ApiSpec, options?: GenerateOptions): GenerateResult | GenerateError;
+/**
+ * Generate a SKILL.md from a simple text description.
+ *
+ * This is a lightweight alternative for when you don't have an OpenAPI spec.
+ * Produces a basic SKILL.md with the given name and description.
+ */
+declare function generateFromText(name: string, description: string, instructions?: string): GenerateResult;
+
+/**
+ * Parse an OpenAPI 3.x specification (JSON or YAML) into an ApiSpec.
+ *
+ * Supports OpenAPI 3.0.x and 3.1.x. Does not support Swagger 2.0.
+ * Resolves local `$ref` references within the document.
+ */
+declare function parseOpenApi(content: string): ApiSpec;
+
+/**
+ * Render a SKILL.md file from an ApiSpec.
+ *
+ * In "unified" mode, produces a single SKILL.md covering the entire API.
+ * In "per-endpoint" mode, produces one SKILL.md per endpoint.
+ */
+declare function renderSkillMd(spec: ApiSpec, options?: GenerateOptions): Map<string, string>;
+
+export { type ApiEndpoint, type ApiParameter, type ApiProperty, type ApiRequestBody, type ApiResponse, type ApiSpec, type AuthScheme, type GenerateError, type GenerateOptions, type GenerateResult, generateFromOpenApi, generateFromSpec, generateFromText, parseOpenApi, renderSkillMd };

package/dist/index.js

@@ -0,0 +1,15 @@
+import {
+  generateFromOpenApi,
+  generateFromSpec,
+  generateFromText,
+  parseOpenApi,
+  renderSkillMd
+} from "./chunk-EMDMG3H6.js";
+export {
+  generateFromOpenApi,
+  generateFromSpec,
+  generateFromText,
+  parseOpenApi,
+  renderSkillMd
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

package/package.json

@@ -0,0 +1,71 @@
+{
+  "name": "@skill-tools/gen",
+  "version": "0.2.0",
+  "description": "Generate Agent Skills (SKILL.md) from OpenAPI specs, REST APIs, and text descriptions",
+  "type": "module",
+  "license": "Apache-2.0",
+  "author": "Piyush Vyas <pyyush>",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/skill-tools/skill-tools",
+    "directory": "packages/gen"
+  },
+  "homepage": "https://github.com/skill-tools/skill-tools/tree/main/packages/gen",
+  "bugs": {
+    "url": "https://github.com/skill-tools/skill-tools/issues"
+  },
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      },
+      "require": {
+        "types": "./dist/index.d.cts",
+        "default": "./dist/index.cjs"
+      }
+    }
+  },
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "bin": {
+    "skillgen": "./dist/cli.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "keywords": [
+    "agent-skills",
+    "skill-md",
+    "openapi",
+    "code-generation",
+    "ai-agent"
+  ],
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "dependencies": {
+    "commander": "^13.1.0",
+    "yaml": "^2.7.0",
+    "@skill-tools/core": "0.2.0"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "^2.3.14",
+    "@types/node": "^25.2.2",
+    "tsup": "^8.5.1",
+    "typescript": "^5.9.3",
+    "vitest": "^4.0.18"
+  },
+  "scripts": {
+    "build": "tsup",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "typecheck": "tsc --noEmit",
+    "lint": "biome check src/",
+    "lint:fix": "biome check --write src/",
+    "format": "biome format --write src/",
+    "format:check": "biome format src/",
+    "clean": "rm -rf dist"
+  }
+}