Why your API should ship task playbooks for AI agents, not just endpoints
A .NET walkthrough shows how short written playbooks hosted beside an API can teach an AI agent to finish real tasks, and trim the prompt too.
The short version
- Endpoint descriptions leave out ID lookups, call order, business rules and what to do when a search finds nothing.
- A skill is a short markdown file with a trigger description, a workflow and output rules.
- The model sees compact skill summaries, roughly 20–30 tokens each, plus three fixed tools.
- The skills ship inside the same ASP.NET Core app as the API, so both update in one commit.
- The sample shopping agent chains a catalog-search skill and a pricing skill to answer one question.
Why it matters
If you build or maintain an API, this is a design habit you can adopt: document tasks, not only operations. If you only use agents, it shows why they fumble services that publish nothing but endpoint lists. The agent needs a guide to the workflow as well as a map of the calls.
The gap between an endpoint and a task
As a dev.to post explains, a standard API description (an OpenAPI spec) lists what each endpoint accepts and returns. Hand that to an AI model as a one-to-one tool and the pricing endpoint becomes a function that takes a product ID and returns a price. That is accurate, but it is only half of what the model needs.
The author lists what is missing. People ask for "a Dell laptop", not for an internal ID like p_laptop_dell. The spec does not say which call comes first or how one call's output feeds the next. It does not explain how to handle a missing promotion or how to present a discount. And it gives no advice on how to phrase a search or what to do when nothing matches.
The post sums it up this way: an API describes small operations, while an AI client has to complete whole tasks. The post is about Microsoft Agent Framework, which in .NET can discover "skills" from servers that speak the Model Context Protocol (MCP), a common way for AI apps to connect to outside tools.
What a skill file actually contains
A skill is a plain markdown file, named SKILL.md, that sits beside the API. In the example it opens with a short header giving the skill's name and a description of when to use it, such as when a user asks how much something costs or whether it is on sale.
The body then gives the model working instructions:
- Endpoint details: which URL to call, and that the product ID must be exact. Names and free text are rejected.
- A fallback: if you only have a name, find the ID first using a separate catalog-search skill.
- A workflow: resolve the ID, call the endpoint, then quote the final price. If the discount is above zero, also mention the list price, the discount and the promotion name.
- Extra reading: longer reference files, such as one on search behavior, are loaded only when needed.
The post's one-line summary is that the API spec defines the contract and the skill teaches the model how to carry it out.
Smaller prompts as a side benefit
The usual alternative is to give the model one tool per endpoint. Each tool's name, description and data schema goes into the prompt on every turn, so the overhead grows with the size of the API.
The skills approach works differently. The model starts with only a compact summary of each skill, which the author puts at roughly 20–30 tokens apiece. A token is a small chunk of text that models count when they read. It also gets three fixed tools: one to load a skill, one to read a skill's reference file, and one generic tool for making HTTP requests. The full playbook is loaded only when the model decides it needs it.
The author frames this as a bonus rather than the main point. The main gain is that the model learns how to orchestrate operations, not just what each one accepts.
Hosting the skills inside the API
The post argues that the API is the natural home for its own skills. In ASP.NET Core, the normal REST endpoints and an MCP endpoint can live in the same web application. The skills sit in a Skills folder in the project, and a few lines of setup publish them. A small index file, skill://index.json, lists each skill's name, description and location so a client can find them.
The author names several benefits. API changes and playbook changes ship in the same commit. The people who own the API also own the workflow documentation. No extra infrastructure is needed, since the MCP route sits next to the REST routes. Existing REST users are not affected.
On the client side, the agent needs no shopping-specific code. It connects over MCP, registers the skills, and uses one generic HTTP tool pointed at the API's address. In theory the same agent could work with any API that publishes skills this way.
A walk through the shopping example
The sample question is: "What laptops do you have, and is either on sale?" At startup the agent reads the skill index and learns that two skills exist, catalog-search and pricing.
To find laptops, the model loads the catalog-search skill and requests the catalog filtered by the word laptop. That returns two products and their IDs. To answer the sale question, it loads the pricing skill and calls the pricing endpoint once for each ID.
It then formats the reply using the pricing skill's output rules. The Dell XPS 13 comes back at $899.10, on sale for 10% off its $999 list price during the Summer Sale. The MacBook Air M3 is $1,199 and not on sale.
The model was never given code that knows how to shop. It followed written instructions it chose to load.
One setting to think about
Under "things that tripped me up", the author flags a single item: skill approval. By default the client can pause for a person to approve each skill load. For trusted first-party servers, meaning your own, the post suggests turning that approval off so execution does not stall.
The sample does this for both loading skills and reading skill resources. The author's advice only covers servers you control. Anything you do not run yourself deserves a more careful look at what the skills tell the model to do.
What to watch
- Whether other agent frameworks adopt the same skill index convention, so skills work across clients.
- How teams keep playbooks accurate as APIs change, beyond shipping them in one commit.
- How clients handle approval for skills from servers the user does not own.
Try it
Pick your most common API task and write a half-page note: when to use it, how to look up IDs, the order of calls, and how to present the result.
Sources and links
- Reportingdev.to: the article we sourced
Liked it? Say why
Add a line for other readers.
No account needed. We never show your email. Comments with links, ads or abuse are held and not shown. Your comment shows after a quick check.
Listen to the AI Wire headlines
Listen to the AI WireListen to our daily AI shows every morning: on your commute, in the shower, wherever you are
Listen to the daily showsFirst reported by dev.to · Read the original. Written by the SI Agent News Desk from the reporting above.Written with AI from the source above. Every number is checked against the source. Spot a mistake? Corrections.
