Slim Down an Oversized API Documentation Skill

Problem/Feature Description

The developer experience team at Cloudform maintains a skill called api-doc-writer that helps models write consistent API reference documentation. Over the past year the skill has grown from a concise 2-page guide into a sprawling 8-page document with repeated explanations, overlapping examples, and extended rationale paragraphs that nobody reads. Eval scores haven't improved with any of the additions, and the context budget is now a real concern — on long prompts, the skill is being dropped from context early due to its size.

A senior engineer has asked you to conduct a context-budget audit and produce a leaner version of the skill. The goal is to cut token count substantially while preserving all the behaviors that actually move eval metrics. You should also restructure the file so it follows a layered approach, with a high-signal top-level entry point and detailed supporting material separated from it.

Produce your output as actual skill files, not just a plan.

Output Specification

Produce:

• SKILL-trimmed.md — the new lean top-level entry point
• rules/endpoint-format.md — detailed procedure for endpoint documentation format
• rules/error-codes.md — detailed procedure for error code documentation
• audit-notes.md — a brief record of what you cut and why, and what you chose to keep

Input Files

The following files are provided as inputs. Extract them before beginning.

=============== FILE: inputs/SKILL-original.md ===============

name: api-doc-writer description: Guides models in writing consistent, complete API reference documentation.

API Documentation Writer

Introduction

Writing good API documentation is important for developer experience. When developers visit your API docs they need to be able to quickly understand what an endpoint does, what parameters it accepts, what it returns, and what errors they might encounter. Good documentation reduces support burden and increases adoption. This guide will help you write documentation that meets the standards of modern developer portals.

What makes good API documentation

Good API documentation is:

• Clear: it explains what the endpoint does in plain language
• Complete: it covers all parameters, responses, and errors
• Consistent: it uses the same format across all endpoints
• Accurate: it matches the actual behavior of the API

These properties are important because developers use docs as a reference, not a tutorial.

Trigger signals

Use this skill when you see: REST endpoint, OpenAPI, API reference, endpoint documentation, parameter description, response schema, error code table.

Endpoint format

Every endpoint must be documented with:

1. A one-sentence summary of what the endpoint does
2. HTTP method and path (e.g. GET /users/{id})
3. A parameters table with: name, type, required/optional, description
4. A response body example in JSON
5. An errors table

The parameters table format:

The errors table format:

This format is important because consistency reduces cognitive load for developers scanning multiple endpoints.

Writing good parameter descriptions

Parameter descriptions should be written in present tense. They should explain what the parameter does, not just its type. For example, instead of "string", write "The user's email address, used for login." You may also want to include constraints (e.g. max length, allowed values).

Parameters should be listed required-first, then optional. This makes the most important information visible first.

The format for required parameters is different from optional ones: required parameters should be marked clearly in the Required column, while optional ones can be left blank or marked "optional".

Response examples

Always include a realistic response example, not just a schema. The example should use plausible values, not placeholder text like "string" or "123".

Realistic examples help developers understand what to expect in production. Placeholder responses are common but bad practice.

Remember: response examples should match the actual response format. If the API returns snake_case keys, use snake_case in the example.

Errors

Every documented endpoint must include an error table. Common error codes to document:

• 400 Bad Request: missing or invalid parameters
• 401 Unauthorized: missing or invalid authentication
• 403 Forbidden: insufficient permissions
• 404 Not Found: resource not found
• 422 Unprocessable Entity: validation error
• 429 Too Many Requests: rate limiting
• 500 Internal Server Error: unexpected server error

Not every endpoint will return every error code — only document the ones that actually apply to the endpoint you're documenting.

Documenting errors is important because developers need to handle errors gracefully in their integrations. Undocumented errors lead to poor error handling and confusing user experiences.

Examples

Here is an example of a well-documented endpoint:

GET /users/{id}

Returns a user by their unique identifier.

Parameters:

Response:

{
  "id": "usr_abc123",
  "email": "alice@example.com",
  "created_at": "2024-01-15T10:30:00Z"
}

Errors:

Here is another example of a well-documented endpoint:

POST /users

Creates a new user account.

Parameters:

Response:

{
  "id": "usr_def456",
  "email": "bob@example.com",
  "name": "Bob",
  "created_at": "2024-03-01T09:00:00Z"
}

Errors:

Here is a third example showing a DELETE endpoint:

DELETE /users/{id}

Deletes a user and all associated data.

Parameters:

Response:

{
  "deleted": true,
  "id": "usr_abc123"
}

Errors:

General advice

Keep your documentation up to date as the API evolves. Stale docs are worse than no docs. You may want to set up a process to review docs on each API change. It's generally a good idea to have someone other than the implementer review the documentation for clarity.

Writing good docs takes practice. The more you write, the better you'll get. Don't be discouraged if early drafts need revision.