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
| Approach | When it fits | What it costs you | When to pick something else |
|---|---|---|---|
| Hand-written SKILL.md files | A small API that changes rarely, with someone who owns the file | Every spec change is a manual edit, and nothing tells you when one was missed | The API changes every release |
| NSwag | C# and TypeScript clients for a .NET API, briefed from method signatures | No skill or markdown output, so the skill is written or scripted separately | You want the skill generated with the client |
| A raw OpenAPI document with an SDK README | Agents that read whole files and an API small enough to fit | 5,241 tokens on every task here, whatever the task needs | The document is large, or each task needs one entity |
| sdkgen model with a skill script | An sdkgen project, and skills that must track each regeneration | A script you maintain, and a model that drops operation summaries | You need each operation’s summary in the skill |
| Swagger Codegen docs | A Swagger Codegen client whose markdown docs can sit under references/ | Docs for every operation at once, with no skill frontmatter or entry point | You 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.
Related how-tos
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
-
The specification’s progressive disclosure section budgets about 100 tokens for the
nameanddescriptionof every installed skill, loaded at startup. It asks for a body under 5,000 tokens and aSKILL.mdunder 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