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

Source: https://voxgig.com/howto/generate-agent-skills-from-an-api-model

- Audience: api-producer
- Level: intermediate
- Languages: typescript, python
- Verified: 2026-11-20
- Published: 2026-11-20

## 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](https://agentskills.io/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](https://agentskills.io/specification) | 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](https://github.com/RicoSuter/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](https://spec.openapis.org/oas/v3.0.3) | 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](https://github.com/voxgig/sdkgen) | 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](https://swagger.io/docs/open-source-tools/swagger-codegen/codegen-v3/generation-selective/) | 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](https://voxgig.com/sdk) 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:

```json title="skill.overlay.json"
{
  "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:

```markdown title="skills/library-api/SKILL.md"
---
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](https://github.com/niieani/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.

```bash
node compare.mjs
```

```text output
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](https://swagger.io/docs/open-source-tools/swagger-codegen/codegen-v3/generation-selective/)
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:

```markdown title="generated/swagger-codegen/docs/DefaultApi.md"
# **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](https://github.com/RicoSuter/NSwag) generates C# and TypeScript clients and no markdown.
Its client keeps each summary as a doc comment on the method:

```ts title="generated/nswag-client.ts"
    /**
     * 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.

```bash
node --test skills.test.mjs
```

```text output
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

- [Install an API skill and check a coding agent uses it](/howto/install-an-api-skill-for-a-coding-agent)

- [Write a skill description that triggers at the right time](/howto/write-a-skill-description-that-triggers)

- [Organize agent skills across many related repositories](/howto/organise-skills-across-a-multi-package-ecosystem)

- [Generate your first SDK with sdkgen](/howto/first-sdk-with-sdkgen)

- [Keep generated files out of a coding agent's edits](/howto/keep-generated-files-out-of-agent-edits)

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

[^1]: The specification's [progressive disclosure](https://agentskills.io/specification) 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.