How-to › Expose your API to agents

How to generate agent skills for your API from a semantic model#

Write a SKILL.md and reference files from sdkgen's entity model, check them against the next API version, and tell the agent which entity to start from.

Audience
API producer
Level
intermediate
Topic
Write agent skills and instruction files
Languages
TypeScript and Python
Verified

Your API adds PATCH /books/{bookId} and an isbn field, and the SKILL.md your team wrote for version 1 still lists four book operations. A coding agent that reads it never calls the update. The file also gives books, members, and loans equal weight and no starting point, though lending a book and listing loans both begin at a member.

What you get

You will end up with an Agent Skill that your own script writes from sdkgen’s entity model, and a CI check that fails when a skill falls behind that model. This is for you if you publish an API and an SDK for coding agents.

Short answer

sdkgen 4.44.3 builds an entity model of your API and writes README, REFERENCE, and AGENTS.md files, but no SKILL.md. Write the skill from that model with a script you own. List the entities with their operations and relations, put each entity’s calls in a reference file, and name the entity to start from in an overlay. Regenerate on every spec change, and fail CI when a skill omits an operation or field the model has.

You will need

Node 22 or later, an OpenAPI 3 document, an sdkgen project for your API, and Python 3 for the Python examples. Verified 2026-11-20 against Node 22.23.5 and Python 3.13. The format is the Agent Skills specification: a SKILL.md with name and description frontmatter, plus optional files under references/.1 The API here is a Library with books, members, and loans, in two versions written by make-api.mjs.

Approaches compared

ApproachWhen it fitsWhat it costs youWhen to pick something else
Hand-written SKILL.md filesA small API that changes rarely, with someone who owns the fileEvery spec change is a manual edit, and nothing tells you when one was missedThe API changes every release
NSwagC# and TypeScript clients for a .NET API, briefed from method signaturesNo skill or markdown output, so the skill is written or scripted separatelyYou want the skill generated with the client
A raw OpenAPI document with an SDK READMEAgents that read whole files and an API small enough to fit5,241 tokens on every task here, whatever the task needsThe document is large, or each task needs one entity
sdkgen model with a skill scriptAn sdkgen project, and skills that must track each regenerationA script you maintain, and a model that drops operation summariesYou need each operation’s summary in the skill
Swagger Codegen docsA Swagger Codegen client whose markdown docs can sit under references/Docs for every operation at once, with no skill frontmatter or entry pointYou want progressive disclosure built in

Voxgig maintains sdkgen. It is the subject of this page, and its row says when to pick something else.

The hand-written skill is the cheapest per task and the first to go stale. The raw document never goes stale and costs the most to read. Swagger Codegen and NSwag regenerate their output with the client but emit no skill. The sdkgen route regenerates too, at the price of a script and summaries it cannot see.

Write the skill from the model

The scaffold built a TypeScript and a Python SDK from api.json, then regenerated from api.v2.json. For each language, sdkgen 4.44.3 wrote README.md, REFERENCE.md, AGENTS.md, and CLAUDE.md. The AGENTS.md files brief an agent that edits the generated project, not one that calls the API, and no file anywhere in the run is a SKILL.md.

The product page lists Agent Skills among sdkgen’s six output surfaces. Version 4.44.3 has no target, feature, or edition that writes one. The package bundles 23 targets and 20 features, and docgen 0.30.9 ships three editions: summary, github-pages, and presentation. The word “skill” appears in none of the @voxgig/sdkgen, @voxgig/docgen, or @voxgig/create-sdkgen packages.

The compiled Config.js carries each entity’s operations, fields, path parameters, and ancestors. dump-model.cjs saves that model as JSON, and skills.mjs reads it. Both scripts belong to this page, not to sdkgen.

The model knows that a loan sits under a member, but not that most tasks start there. That is the equal-weight problem, so one fact comes from an overlay the script refuses to apply to an entity the model lacks:

{
  "name": "library-api",
  "api": "Library",
  "lead": "member",
  "purpose": "Call the Library API through its TypeScript or Python SDK: members, their loans, and the book catalog.",
  "when": "lends a book, registers a member, lists a member's loans, or reads the catalog.",
  "lead_note": "Lending a book and reading a member's loans both start from a member."
}

The generated SKILL.md puts the lead first, its children next, and a line for each relation:

---
name: library-api
description: Call the Library API through its TypeScript or Python SDK: members, their loans, and the book catalog. Use it when a task lends a book, registers a member, lists a member's loans, or reads the catalog. Start from member.
---

# Library API

Start with **member**. Lending a book and reading a member's loans both start from a member.

- A loan is reached through its member: load or create the member first, then pass `member_id`.

| Entity | Operations | Reference |
| --- | --- | --- |
| member | create, list, load | [references/member.md](references/member.md) |
| loan | create, list | [references/loan.md](references/loan.md) |
| book | create, list, load, update, remove | [references/book.md](references/book.md) |

Each reference file lists the entity’s fields, with the description the model keeps for a field, and one TypeScript and one Python call per operation, with the request it sends. Without the overlay, --flat writes the same entities alphabetically, with no starting point in the description.

Measure what each approach costs and misses

compare.mjs counts what each approach puts in front of the agent for one task, lending a book, with the o200k encoding of gpt-tokenizer. A skill’s frontmatter loads in every session, and its body and references load when it is used. It then checks each skill against version 2 of the model.

node compare.mjs
task: lend a book to a member, o200k tokens
approach                        every session  for the task
OpenAPI document + SDK README               0          5241
Swagger Codegen README + docs               0          4737
hand-written SKILL.md                      25           270
generated skill                            58           764

after api.v2.json adds PATCH /books/{bookId} and a book field, isbn
  hand-written SKILL.md      missing book.update, book field isbn
  generated from model v1    missing book.update, book field isbn
  generated from model v2    nothing missing

The hand-written skill is the smallest, 270 tokens against 764, because a person wrote one line per call. It is also the one that cannot catch up by itself. A generated skill is as stale as the model it came from, so the fix is the regeneration, not the generator. drift.mjs runs the same check alone and exits 1 when anything is missing.

The table does not score an agent finishing tasks. Claude Code was not run, so whether the starting point changes what an agent does first is not measured here.

Brief an agent from NSwag or Swagger Codegen output

Neither generator writes an Agent Skill. Swagger Codegen generates API and model docs with a client unless -DapiDocs=false or -DmodelDocs=false turns them off. Its Python run wrote a README and one markdown file per API and model, with the document’s summaries and field descriptions:

# **create_loan**
> Loan create_loan(body, member_id)

Lend a book to a member

A skill can point at those files from references/. Write the frontmatter and the starting entity by hand, because the docs cover every operation at once.

NSwag generates C# and TypeScript clients and no markdown. Its client keeps each summary as a doc comment on the method:

    /**
     * Lend a book to a member
     * @return OK
     */
    createLoan(body: Loan, memberId: string): Promise<Loan> {

With NSwag, generate the skill from the OpenAPI document itself, or write it by hand against these signatures. Both carry what the sdkgen model drops: Lend a book to a member appears in neither model file.

Check it worked

Ten tests hold the skill to its claims. The committed skill matches what skills.mjs writes and meets the specification’s name and description rules. The isbn reference carries the field description that the model keeps, and the model lacks the operation summaries. The weighted skill leads with member, and the flat one does not. The drift results match the table, and drift.mjs exits 1 on the stale skill. Every TypeScript example runs against the generated SDK and sends its request, and every Python example parses. The last shows a loan without its member failing in the client.

node --test skills.test.mjs
1..10
# tests 10
# suites 0
# pass 10
# fail 0
# cancelled 0
# skipped 0
# todo 0
# duration_ms 452.733336

When it goes wrong

The agent calls client.Loan().create() without member_id, and the client rejects it with URL path has no value for {member_id}. The skill described loans as if they stood alone. Generate from a model that carries the relation, and keep the “reached through” line in SKILL.md, not only in the reference.

A Python example fails with AttributeError: 'LoanEntity' object has no attribute 'data'. The Python SDK reads a record with data_get(), not the TypeScript data(). Generate each language’s example from that language’s SDK, and run or parse every one in the test.

The skill is regenerated and still lists the old operations. The script read a model dumped before the last npm run generate. Dump the model in the same step that regenerates the SDK, as generate.sh does.

When not to do this

Do not script a skill for an API of a handful of operations that changes once a year. The hand-written file here costs about a third of the tokens, and one owner reviewing it at release time is cheaper than a generator.

Do not treat sdkgen’s model as the whole source. It keeps field descriptions but drops each operation’s summary, so a skill built from it alone says what each call sends and not what it is for. Keep the purpose lines in the overlay, or read them from the document.

Do not pick sdkgen for this if your clients come from Swagger Codegen. Its generated docs already track each regeneration, with descriptions included, and a hand-written SKILL.md that links them is the smaller change. Choose NSwag when the agents work in C# against a .NET API and read method signatures with their doc comments.

Last verified

Verified 2026-11-20 against Node 22.23.5, Python 3.13, @voxgig/create-sdkgen 0.31.9, @voxgig/sdkgen 4.44.3, @voxgig/docgen 0.30.9, NSwag 14.8.0, Swagger Codegen 3.0.85 and gpt-tokenizer 4.1.2. Every output block is what the command preceding it printed. Each generator ran once in generate.sh, and its output is committed under generated/. The Python SDK was called once against a stand-in to fix the example’s form, and the test parses those examples without running them. NSwag ran once, and its output is committed. Claude Code was not run.

Footnotes

  1. The specification’s progressive disclosure section budgets about 100 tokens for the name and description of every installed skill, loaded at startup. It asks for a body under 5,000 tokens and a SKILL.md under 500 lines. The generated frontmatter here comes to 58 by the o200k count and the hand-written one to 25, both inside the figure. The figure is per skill, so a session with forty skills installed spends about 4,000 tokens on descriptions before it uses any of them. ↩︎ Back to text

Read this page as markdown · All how-to guides

Generate the client instead of writing it#

Retries, timeouts, pagination and auth are the same problems in every client. Voxgig generates them from your OpenAPI description, in 23 languages, from one model.

Listen to Fireside, the Voxgig podcast

Since 2018, Richard Rodger has talked with developer advocates, event organizers, and the people who build developer-facing companies about the specifics of the work.