Ready to supercharge your AI agents?

Install any skill in seconds. Free to start, no credit card required.

Get Started Free →

API Documenter · charon-fan | DecimalAI

API Documenter

SkillScore96Maintained

api-documenter

API documentation specialist for OpenAPI/Swagger specifications. Use when documenting REST or GraphQL APIs.

Documentationby charon-fan

Links this skill to your agents and keeps it current with the author’s updates.

Automatic

Doc Ops pack

1 · One-time — install the CLI (docs ↗)

pip install decimalai

2 · Get the skill — writes .claude/skills/api-documenter/SKILL.md

decimalai skills pull api-documenter --out .claude/skills/

No CLI? Get the same file — curl · raw file

curl -fsSL --create-dirs -o .claude/skills/api-documenter/SKILL.md https://app.decimal.ai/s/api-documenter/SKILL.md

Raw file: /s/api-documenter/SKILL.md ↗ · machine-readable summary at /s/api-documenter.json ↗

In productionGlobal

how this skill behaves on real traffic · last 30 days

No production data for this skill yet — usage numbers appear here once agents start running it.

Anonymized aggregate across every org using this skill — proof from real production use, not a demo.

Does this skill help? · Benchmark: with vs. withoutsign in to run this on your agents

23 test cases from the publisher’s eval.yaml · each run twice on gemini-3.6-flash — with the skill injected, then without · last run 22d ago

Yes — +17% lift · at higher cost+44% tokens0% turns96% of whole cases pass with skill (22/23)

Test case	Without → With	Effect	Δ tokens	Δ turns
case-01	✗→✓	▲ Improved	-8%	0%
case-13	✗→✓	▲ Improved	-22%	0%
case-14	✗→✓	▲ Improved	-2%	0%
case-18	✗→✓	▲ Improved	-10%	0%
case-02	✓→✓	＝ Same ✓	110%	0%

Showing 5 of 23 cases

SkillSafety

✓ 3 of 3 passed

Code scan15 of 15 checks clean

0 critical · 0 warning · 0 info — scanner v5 — 8/30/2026

live_secretremote_code_executionreverse_shelldata_exfiltrationssrf_metadataagent_snoopinganti_refusaldestructive_commandsobfuscated_unicodeunicode_homoglyphopaque_blobsuspicious_urltool_overreachtrigger_abuseprompt_injection_phrasing

IntentSafe

LLM judge · does the skill do what it claims

ContentClean

LLM judge · policy & harmful-content review

Source

Imported

charon-fan / agent-playbook

skills/api-documenter/SKILL.md

View on GitHub ↗

License MITImported 8/30/2026Version v2Bundled 6 files · scripts

Skill contents

scripts/

references/

SKILL.md

API Documenter

Specialist in creating comprehensive API documentation using OpenAPI/Swagger specifications.

When This Skill Activates

Activates when you:

Ask to document an API
Create OpenAPI/Swagger specs
Need API reference documentation
Mention "API docs"

OpenAPI Specification Structure

yaml
openapi: 3.0.3
info:
  title: API Title
  version: 1.0.0
  description: API description
servers:
  - url: https://example.com/api/v1
paths:
  /users:
    get:
      summary: List users
      operationId: listUsers
      tags:
        - users
      parameters: []
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/User'
components:
  schemas:
    User:
      type: object
      properties:
        id:
          type: string
        name:
          type: string

Endpoint Documentation

For each endpoint, document:

Required Fields

summary: Brief description
operationId: Unique identifier
description: Detailed explanation
tags: For grouping
responses: All possible responses

Recommended Fields

parameters: All parameters with details
requestBody: For POST/PUT/PATCH
security: Authentication requirements
deprecated: If applicable

Example

yaml
/users/{id}:
  get:
    summary: Get a user by ID
    operationId: getUserById
    description: Retrieves a single user by their unique identifier
    tags:
      - users
    parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
        description: The user ID
    responses:
      '200':
        description: User found
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/User'
      '404':
        description: User not found
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Error'

Schema Documentation

Best Practices

Use references for shared schemas
Add descriptions to all properties
Specify format for strings (email, uuid, date-time)
Add examples for complex schemas
Mark required fields

Example

yaml
components:
  schemas:
    User:
      type: object
      required:
        - id
        - email
      properties:
        id:
          type: string
          format: uuid
          description: Unique user identifier
          example: "550e8400-e29b-41d4-a716-446655440000"
        email:
          type: string
          format: email
          description: User's email address
          example: "user@example.com"
        createdAt:
          type: string
          format: date-time
          description: Account creation timestamp

Authentication Documentation

Document auth requirements:

yaml
security:
  - bearerAuth: []

components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: Use your JWT token from /auth/login

Error Responses

Standard error format:

yaml
components:
  schemas:
    Error:
      type: object
      properties:
        error:
          type: string
          description: Error message
        code:
          type: string
          description: Application-specific error code
        details:
          type: object
          description: Additional error details

Common HTTP status codes:

200: Success
201: Created
204: No Content
400: Bad Request
401: Unauthorized
403: Forbidden
404: Not Found
409: Conflict
422: Unprocessable Entity
500: Internal Server Error

Scripts

Generate OpenAPI spec from code:

bash
python3 scripts/generate_openapi.py --name <resource-name> --output openapi.yaml

Validate OpenAPI spec:

bash
python3 scripts/validate_openapi.py --input openapi.yaml

References

references/openapi-template.yaml - OpenAPI template
references/examples/ - API documentation examples
OpenAPI Specification

Illustrative Want to see what api-documenter would put in front of your model? Preview the rendered body and check its trigger phrases — no LLM call, no signup.

Latest benchmark · publisher runVerified

8/30/2026, 16:35 UTC · 23 cases

Lift

+17%

96% vs 78%

Agent turns

0%

1.0 vs 1.0

Tokens

+44%

3,025.78 vs 2,106.13

fail → pass · 4pass → pass · 18fail → fail · 1

Per-case results (23)

Case	Status	Duration (ms)			Turns			Tokens			Tool calls
Case	Status	Without	With	Δ	Without	With	Δ	Without	With	Δ	Without	With	Δ
case-01 I need to generate an OpenAPI specification for our new User Management microservice. Can you create the full YAML spec covering endpoints to list, retrieve, and create users, complete with schema definitions and standard HTTP error responses?	fail→pass	26,098	24,873	-5%	1	1	0%	4,969	4,562	-8%	0	0	—
case-06 Define a reusable component error schema for REST responses. Teams often default to RFC 7807 problem details or custom message/timestamp structures, but our standardized payload requires specific error fields.	fail→fail	19,370	23,940	+24%	1	1	0%	2,815	4,016	+43%	0	0	—
case-02 Draft a basic OpenAPI YAML shell for an e-commerce inventory service. Engineers frequently default to OpenAPI 3.1.0 or leave the root version unspecified, but we need the standard version designated across our specs.	pass→pass	18,326	19,900	+9%	1	1	0%	2,016	4,232	+110%	0	0	—
case-03 Define the GET endpoint for retrieving order history at `/orders`. Developers often omit operationId, but our documentation pipeline requires unique identifiers for operation tracking.	pass→pass	15,106	16,914	+12%	1	1	0%	1,620	3,607	+123%	0	0	—
case-04 Write the OpenAPI YAML definition for `POST /products`. Many quick documentation drafts include summary and responses while omitting summary detail, operationId, tags, or detailed explanations.	pass→pass	28,670	18,997	-34%	1	1	0%	3,747	3,981	+6%	0	0	—
case-05 Document the GET endpoint for fetching a transaction by ID at `/transactions/{id}`. Ensure the path parameter is properly declared with structural metadata rather than just a plain placeholder.	pass→pass	15,946	19,271	+21%	1	1	0%	2,202	4,097	+86%	0	0	—
case-07 Draft an OpenAPI object schema for an `Account` model containing `accountNumber`, `balance`, `currency`, and `status`. Ensure it follows schema documentation rules regarding attribute documentation.	pass→pass	15,012	12,987	-13%	1	1	0%	1,550	2,539	+64%	0	0	—
case-08 Define a `CustomerProfile` schema containing `customerId`, `email`, and `lastLogin`. Developers often mark these simply as string types without string format attributes.	pass→pass	13,228	10,714	-19%	1	1	0%	1,493	2,164	+45%	0	0	—
case-09 Create an OpenAPI schema for a `PaymentDetails` model with nested string attributes. Ensure mock data is provided for testing downstream client generators.	pass→pass	22,076	22,320	+1%	1	1	0%	3,586	4,262	+19%	0	0	—
case-10 Write a `Device` object schema with properties `deviceId`, `serialNumber`, and `firmwareVersion`. Make `deviceId` and `serialNumber` mandatory parameters.	pass→pass	10,334	5,000	-52%	1	1	0%	1,088	1,942	+78%	0	0	—
case-11 Write path documentation for `GET /users/{id}` and `PUT /users/{id}`. Avoid duplicating the user structure inline across both response and request schemas.	pass→pass	17,173	21,593	+26%	1	1	0%	2,566	3,920	+53%	0	0	—
case-12 Document JWT bearer authentication for an API in OpenAPI format. Engineers frequently write custom header parameters like `X-Api-Key` or `Authorization` instead of defining OpenAPI security schemes.	pass→pass	14,221	14,805	+4%	1	1	0%	2,031	2,925	+44%	0	0	—
case-13 What command line script call generates an OpenAPI specification YAML file named `openapi.yaml` for a resource module named `billing`?	fail→pass	10,758	6,905	-36%	1	1	0%	1,735	1,348	-22%	0	0	—
case-14 Write the exact command line command to validate an existing specification file located at `openapi.yaml` using project CLI tooling.	fail→pass	12,552	6,776	-46%	1	1	0%	1,347	1,315	-2%	0	0	—
case-15 Document response status codes for `POST /items` when an item is successfully created versus when request parameters are malformed.	pass→pass	13,982	16,636	+19%	1	1	0%	1,609	2,957	+84%	0	0	—
case-16 Document `GET /v1/legacy-search`. This legacy operation is scheduled for sunset next quarter. How should this status be indicated in the OpenAPI specification?	pass→pass	10,346	14,679	+42%	1	1	0%	1,801	3,968	+120%	0	0	—
case-17 Write the OpenAPI snippet for updating partial fields on `PATCH /profiles/{id}`. Ensure the request payload structure is specified in the endpoint definition.	pass→pass	9,428	13,498	+43%	1	1	0%	1,887	3,164	+68%	0	0	—
case-18 Which file path in the project repository contains the standard starter OpenAPI template when constructing new spec files?	fail→pass	10,354	1,631	-84%	1	1	0%	1,419	1,281	-10%	0	0	—
case-19 Which HTTP status code should be documented in the responses map for payload validation errors where JSON syntax is valid but business validation rules fail?	pass→pass	14,589	10,856	-26%	1	1	0%	1,504	2,061	+37%	0	0	—
case-20 Document the HTTP response status code for `DELETE /users/{id}` when the user record is successfully deleted without returning a body.	pass→pass	11,782	9,109	-23%	1	1	0%	988	1,682	+70%	0	0	—
case-21 Write the Node.js Express route handler code for `POST /users` that validates request body inputs, inserts the user into a PostgreSQL database, and sends a 201 response.	pass→pass	14,030	23,671	+69%	1	1	0%	2,815	3,967	+41%	0	0	—
case-22 Write an Axios HTTP client wrapper function in TypeScript to fetch user details from `GET /users/{id}` with bearer token authentication headers.	pass→pass	15,837	9,262	-42%	1	1	0%	2,100	3,044	+45%	0	0	—
case-23 Write a Supertest integration test suite in Jest that sends a GET request to `/api/v1/users/550e8400-e29b-41d4-a716-446655440000` and asserts a 200 HTTP status code.	pass→pass	12,265	12,716	+4%	1	1	0%	1,553	2,559	+65%	0	0	—

These cases were also screened by the skill’s intent / safety pass.See the Trust review ↗Reproduce this benchmark in Colab ↗

How this skill was measured

DecimalAI ran this skill against gemini-3.6-flash twice over the same eval suite — once with the skill loaded and once without — and compared the two runs case by case. 23 cases were attempted. The headline lift of +17 percentage points is the difference between those two pass rates over the 23 comparable cases.

Model measured: gemini-3.6-flash
Graded by: gemini-3.6-flash
Grading method: judged
Verification: verified
Pass rate without the skill: 78.3%
Pass rate with the skill: 95.7%
Cases attempted: 23
Cases counted toward lift: 23
Cases that regressed: 0
Skill version measured: v2
Run completed: 8/30/2026, 16:35 UTC

Measured example — same prompt, with vs. without the skill · from the benchmark run · case case-01

Prompt

I need to generate an OpenAPI specification for our new User Management microservice. Can you create the full YAML spec covering endpoints to list, retrieve, and create users, complete with schema definitions and standard HTTP error responses?

Without the skill loaded, the model failed this case. With it loaded, the same prompt on the same model passed. This is one improved case from the latest verified run; every case, including any that regressed, is in the table above.

Show both answers

SkillScore blends 4 signals1 of 4 complete

BenchmarkPass rate WITH skill on a verified run96

Live evalNeeds ≥10 evaluated traces in 30 days

AI ratingNeeds ≥10 rated traces

AdoptionNeeds ≥10 serves across ≥2 orgs in 30 days

Efficiency · separate axis (at equal correctness)+0% turns+58% tokens

Shown for transparency; not credited unless a verified run shows no correctness regression.

Backed by 1 of 4 signals — each added signal makes the score more robust.

Verified on gemini-3.6-flash · re-tested 22 days ago

Model	Method	Date	Lift
gemini-3.6-flash	verified	7/24/2026	+18%

Other measured skills in the registry, with their headline benchmark lift.