skill-creator: generate reusable CLI skills from OpenAPI, GraphQL and MCP sources

The problem skill-creator solves: pasted API docs do not persist

An agent that needs to call a REST API usually gets the same treatment every session: someone pastes a chunk of the OpenAPI document into the chat, the agent guesses at query parameters, and the guess is thrown away when the context window rolls over. skill-creator attacks that by turning the source into files on disk. The README frames it as giving an agent a link and getting back "a ready-to-use Agent Skill with wrapper scripts, references, and usage notes." The output is a directory with a SKILL.md, a scripts/ entry, and a reference copy of the spec.

The audience is narrow but real. It is for teams that already run an agent with a skill or prompt-command system (the README lists pi, claude-code, codex, cursor, opencode, gemini-cli, github-copilot, cline and windsurf) and that call the same handful of APIs often enough to want a stable command surface. If you call an API once, the install cost is not worth it. The value shows up on the third or tenth call, when the agent runs ./scripts/youtube commands list instead of re-reading a spec.

How generation works: research, generate, smoke test, track

The flow has two halves. The first is an agent-side prompt command. Installing the package writes a prompt file and a companion skill into the agent's config directory, and from then on /skill-creator takes a URL or a stdio command as its argument. The agent researches the source, then calls the package's own generate subcommand. That subcommand is the second half: a plain CLI that reads the OpenAPI document, GraphQL schema or MCP tool list and emits the skill directory.

The repository layout backs this up. There is src/ for the CLI and generation logic, prompts/ for the agent-facing command text, skills/ for the companion improvement skill, and e2e/ with a shell runner. Dependencies point the same direction: @apidevtools/json-schema-ref-parser for resolving $ref chains in OpenAPI, the @graphql-tools loaders for SDL and introspection, and @modelcontextprotocol/sdk for talking to MCP servers over HTTP or stdio. Discovery is filtered by --include, --exclude and --methods, so a large spec does not have to become a large CLI.

Remote specs, introspection results and MCP tool lists are cached under ~/.cache/skill-creator by default, with --cache-key, --cache-ttl and --refresh controlling reuse and SKILL_CREATOR_CACHE_DIR overriding the location. That cache is the reason a generated wrapper starts quickly on the second run. It is also the reason a stale tool list can produce a command that no longer exists upstream.

Installing skill-creator and generating your first skill

The package requires Node.js ^22.22.2 || ^24.15.0 || >=26.0.0, and the README notes Node 26 is used in CI. There is no global install step: everything runs through npx. The install command takes an agent name and a scope, and writes the prompt command plus the companion improvement skill.

npx @asnd/skill-creator command install --agent pi --scope global

After that the README says the following two paths exist: ~/.pi/agent/prompts/skill-creator.md and ~/.pi/agent/skills/skill-creator-improvement/. Swap --scope project to keep both inside the repository instead of the home directory, and add --no-improvement-skill if you only want the prompt command. The README lists claude-code, codex, cursor, opencode, gemini-cli, github-copilot, cline and windsurf as other supported agent values, for example --agent claude-code.

With the command installed, the normal path is to invoke it in the agent with a source URL. The README's example is a bare link:

/skill-creator https://example.com/openapi.json

The agent asks for any missing install details, runs the generator, refines SKILL.md, and smoke tests the wrapper. You should end up with a directory shaped like the one in the README, with SKILL.md, scripts/<name> and a dated copy of the spec under references/.

You can skip the agent entirely and drive the generator from a shell or CI job. The README gives this OpenAPI form:

npx @asnd/skill-creator generate \
  --template openapi \
  --name youtube \
  --spec https://example.com/openapi.json \
  --agent pi \
  --scope project

GraphQL and MCP use --template graphql with --graphql and --graphql-schema, or --template mcp-http with --mcp. Once a skill exists, the wrapper script is the interface. The README shows four subcommands: commands list, commands search, commands help <command>, and run --pretty <command> <flags>. Generated scripts call npx -y @asnd/skill-creator internally, so whoever runs the wrapper does not need the package installed globally. That also means every invocation resolves the package from the network unless it is already in the npx cache.

The improvement loop and its lock file boundary

Generated skills are recorded in ~/.skill-creator/lock.json. The companion skill-creator-improvement skill reads that file and only patches skills listed in it, which is a deliberate guard: it will not touch a hand-written skill that happens to live in the same directory. When an agent hits a reusable gotcha, a custom field, a corrected command pattern or a faster workflow, the improvement skill edits the ## Gotchas section of the generated SKILL.md.

The README also notes that the improvement skill's own description is refreshed after generation to include every tracked skill name, so the agent is more likely to activate it after using those skills. That is a small but sensible piece of prompt engineering: activation is name-driven, so the description has to contain the names.

The boundary is worth stating plainly. Improvement only happens during real use, by an agent, and it writes into SKILL.md rather than into the generator. If you regenerate the skill from the same spec, the README does not document whether accumulated Gotchas survive. Treat the generated directory as something to commit and review, not as a cache you can delete.

Where skill-creator is the wrong tool

The generator is only as good as the source document. An OpenAPI file with vague operation IDs, or a GraphQL endpoint that refuses introspection and has no published SDL, gives the agent little to work with. The README's own escape hatch is telling: --graphql-schema accepts a file or URL so you can supply SDL or introspection JSON instead of relying on endpoint introspection. If you have neither, the tool has nothing to read.

Authentication is handled by --auth-header values of the form 'Header:env:NAME' or 'Header:file:/path/token'. That covers static header secrets. It does not cover OAuth flows, token refresh, request signing, or short-lived credentials, and the README documents no mechanism for any of them. An API that needs a refreshed bearer token every hour is a poor fit for a generated wrapper.

Caching cuts both ways. Remote specs and MCP tool lists are cached under ~/.cache/skill-creator, and the README does not document automatic invalidation when an upstream API changes. A generated command can therefore point at an endpoint that was renamed, and the failure surfaces at call time rather than at generation time. Finally, this is a generator, not a gateway. Nothing in the README suggests it enforces rate limits, retries, or access policy on the calls a wrapper makes. If you need those guarantees, a proxy in front of the API is the right layer.

Alternatives: spec-to-CLI generators and MCP clients

The closest comparison is a static spec-to-CLI generator such as OpenAPI Generator. That family compiles a client library or CLI from a spec once, at build time, in a language you choose, and you commit the generated code. skill-creator instead generates at runtime, in TypeScript, and its output is a thin wrapper that re-reads the spec through npx on each invocation. The trade-off is concrete: a compiled client is fast and versioned but needs a rebuild when the spec changes; skill-creator needs no build step and picks up spec changes through its cache, but it pays a Node startup and a network or cache lookup on every call.

The other comparison is using an MCP client directly. If your agent already speaks MCP, pointing it at the server gives you the tools without an intermediate CLI. skill-creator's --mcp and --mcp-stdio flags exist precisely because that is not always enough: a generated wrapper gives you a stable command name, filtering through --include and --exclude, output shaping with --pretty, --raw and --head N, and a SKILL.md that documents the gotchas. You are trading a live protocol connection for a checked-in artifact. That is the right trade when the same call pattern repeats across sessions, and the wrong one when the server's tool list changes often.

Maintenance, licence and upgrade cost

The repository is not archived, and the last push was on 2026-06-03, which is more than three months before today. The most recent release is v0.2.0, dated 2026-06-03, following v0.1.11 and v0.1.10 on 2026-05-29. The 0.x version number is the honest signal here: the CLI surface, the lock file format and the generated directory layout can all change between minor releases, and the README does not document a migration path or a deprecation policy for generated skills. Pinning the version in your own scripts is the practical response, though the README's examples use npx without a version pin.

The licence is MIT, declared in package.json and shipped as LICENSE at the repository root. That permits commercial use and modification, and it comes with no warranty. It says nothing about the APIs you point the tool at: if you generate a skill from a vendor's OpenAPI document, the vendor's terms govern your use of that API, and the generated references/ directory contains a copy of their spec. Nothing here is legal advice; check the source API's terms before you commit a spec copy into a repository.

Upgrade cost is mostly re-generation. Because the wrapper delegates to npx -y @asnd/skill-creator at call time, consumers pick up whatever version resolves unless you pin it, which means a breaking change in the runtime CLI reaches your generated scripts without a commit on your side.

Editorial conclusion

Adopt skill-creator if your team repeatedly points agents at the same OpenAPI, GraphQL or MCP source and you want a checked-in wrapper plus a SKILL.md instead of pasted docs. Skip it if the API is still changing weekly, if you cannot run Node 22.22.2 or newer, or if you need a runtime proxy that enforces policy rather than a generator that emits files. Before committing, run the generate command against your own spec, read the produced SKILL.md, and confirm the wrapper script's commands list matches the endpoints you actually intend to expose.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. README
4. Releases
5. sandiiarov/skill-creator on GitHub