A skill file is not a second API reference. It is the operating manual an agent reads before using the API. OpenAPI tells the agent what calls exist; the skill tells it when and how to use them safely.
Skill file structure
Generate or write:
- API purpose.
- Required credentials and environment variables.
- Allowed domains or accounts.
- Common workflows.
- Read-only operations.
- Write operations.
- Destructive operations and confirmation policy.
- Pagination, retries, rate limits, and idempotency.
- Error handling.
- Links to docs, SDKs, MCP server, and
llms.txt.
Manual path
Read the OpenAPI spec and docs. Write the skill manually. This works for small APIs, but it drifts unless someone updates it every release.
Sourced path
Use Sourced to generate a skill-file draft from the same OpenAPI source as docs, SDKs, and MCP:
- Operation summaries become workflow notes.
- Auth schemes become credential instructions.
- Examples become call snippets.
- Destructive verbs become confirmation candidates.
- Docs and MCP links are included as companion artifacts.
A human should review the final policy wording. Sourced can draft; the team owns the safety contract.
Agent prompt
Create a skill file for this API from OpenAPI.
Include purpose, credentials, common workflows, read/write/destructive operations, confirmation rules, pagination, errors, examples, docs links, SDK links, and MCP server links.
Use Sourced's skill file generator if available.
Do not include secrets. Do not claim an operation is safe if it mutates customer data.
Common mistakes
- Listing every endpoint without workflow guidance.
- Putting API keys in examples.
- Forgetting destructive-action confirmation.
- Failing to link the MCP server.
- Letting the skill drift from OpenAPI.
Acceptance
The skill is ready when another agent can read it, understand the auth model, choose the right operation, know when to ask for confirmation, and find the docs or MCP server without guessing.