Search the docs, videos, blog, apps, teams, skills and release notes.
At a glance
What it is
API documentation expertise covering OpenAPI specification authoring, endpoint documentation patterns, code examples in multiple languages, authentication guides, quickstart tutorials, SDK documentation, error reference guides, versioning strategies, interactive documentation portals, and developer experience optimization.
A skill is a written procedure a bot loads when a job calls for it. This one is a single file, SKILL.md, and the whole file is on this page.
The whole file, exactly as it downloads. Read it before you rely on it.
SKILL.md
518 lines · 1,778 words
API documentation is the primary interface between your API and its consumers. Great API docs reduce support burden, accelerate integration, and build developer trust. This skill covers writing clear, complete, and developer-friendly API documentation from OpenAPI specifications through quickstart guides, code examples, authentication tutorials, and error references.
API documentation expertise covering OpenAPI specification authoring, endpoint documentation patterns, code examples in multiple languages, authentication guides, quickstart tutorials, SDK documentation, error reference guides, versioning strategies, interactive documentation portals, and developer experience optimization.
Nothing. It ships with Murage, which is open source. Your bots run on the AI plan you already have.
Yes. Open it in Settings → Skills to read, edit or duplicate it. Skill Guard scans it again after every edit.
Download the app, connect the AI you already pay for, and tell your Chief of Staff what needs doing. Plan on about ten minutes from install to a working team.
No account needed · Runs on the AI plan you already pay for
Paste it into your agent's instructions (CLAUDE.md, AGENTS.md or a custom GPT), or add it to a bot in Murage.
Ask Ember for the bot, then switch the skill on in its settings.
Step 1
Send your Chief of Staff this message. It proposes the bot and its role first, and creates it when you say go.
Send this to Ember
“Create a bot that uses the API Documentation Writer skill, and show me the plan first.”
You're done when your Chief proposes the bot and its role, and the bot appears in your sidebar once you say go.
Step 2
You're done when you see the bot’s skills and the library.
Step 3
You're done when the skill shows as on for that bot.
Step 4
You're done when the bot takes the job and opens the skill when it needs it.
Prefer to do it yourself? Choose + in the sidebar, then New Bot.Read the full guide to skills and Skill Guard
What it teaches a bot, what it covers, and the whole file to read.
What it covers
Overview
Documentation Architecture
OpenAPI Specification
Code Examples
Quickstart Guide
Error Reference
Writing Quality Checklist
When to Use
Output Format
Example
Edge Cases
API Documentation Site
|
+-- Getting Started
| +-- Quickstart (5-minute integration)
| +-- Authentication Guide
| +-- Rate Limits & Quotas
| +-- Environments (sandbox, production)
|
+-- API Reference (auto-generated from OpenAPI)
| +-- Endpoints grouped by resource
| +-- Request/response schemas
| +-- Code examples per endpoint
| +-- Try-it-out console
|
+-- Guides
| +-- Common Workflows
| +-- Webhooks Integration
| +-- Pagination Patterns
| +-- Error Handling
| +-- Migration Guides (v1 -> v2)
|
+-- SDKs & Libraries
| +-- Installation
| +-- Configuration
| +-- Usage Examples
| +-- Changelog
|
+-- Reference
| +-- Error Codes
| +-- Status Codes
| +-- Glossary
| +-- Changelog / Release Notesopenapi: 3.1.0
info:
title: Orders API
version: 2.1.0
description: |
The Orders API lets you create, get, update, and manage customer orders.
## Authentication
All endpoints require a Bearer token. See [Authentication Guide](/docs/auth).
## Rate Limits
- Standard: 100 requests/minute
- Bulk endpoints: 10 requests/minute
## Versioning
Include `API-Version: 2024-01-15` header. See [Versioning](/docs/versioning).
contact:
name: API Support
email: api-support@company.com
url: [reference URL]
servers:
- url: [reference URL]
description: Production
- url: [reference URL]
description: Sandbox (test data, no real charges)
tags:
- name: Orders
description: |
Create and manage customer orders. Orders progress through states:
`pending` -> `confirmed` -> `shipped` -> `delivered`.
Orders can be `cancelled` before shipping.
paths:
/orders:
post:
operationId: createOrder
summary: Create an order
description: |
Creates a new order for the authenticated customer.
**Important:** The order is created in `pending` status and must be
confirmed within 30 minutes or it will be automatically cancelled.
Requires the `orders:write` scope.
tags: [Orders]
security:
- BearerAuth: [orders:write]
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreateOrderRequest'
examples:
simple_order:
summary: Simple single-item order
value:
items:
- product_id: "prod_abc123"
quantity: 2
shipping_address:
line1: "123 Main St"
city: "San Francisco"
state: "CA"
postal_code: "94102"
country: "US"
multi_item:
summary: Multi-item order with discount
value:
items:
- product_id: "prod_abc123"
quantity: 2
- product_id: "prod_def456"
quantity: 1
discount_code: "SAVE10"
shipping_address:
line1: "456 Oak Ave"
city: "Austin"
state: "TX"
postal_code: "73301"
country: "US"
metadata:
source: "mobile_app"
campaign: "summer_sale"
responses:
'201':
description: Order created successfully
headers:
X-Request-Id:
description: Unique request identifier for support
schema:
type: string
content:
application/json:
schema:
$ref: '#/components/schemas/Order'
examples:
created:
summary: Newly created order
value:
id: "ord_xyz789"
status: "pending"
items:
- product_id: "prod_abc123"
quantity: 2
unit_price: 29.99
total: 59.98
subtotal: 59.98
tax: 5.40
total: 65.38
created_at: "2024-06-15T10:30:00Z"
expires_at: "2024-06-15T11:00:00Z"
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'422':
description: Validation error
content:
application/json:
schema:
$ref: '#/components/schemas/ValidationError'
examples:
invalid_product:
summary: Product not found
value:
error:
code: "INVALID_PRODUCT"
message: "Product 'prod_invalid' does not exist"
field: "items[0].product_id"
out_of_stock:
summary: Product out of stock
value:
error:
code: "OUT_OF_STOCK"
message: "Product 'prod_abc123' has only 1 unit available"
field: "items[0].quantity"
metadata:
available_quantity: 1
components:
schemas:
Order:
type: object
description: Represents a customer order
properties:
id:
type: string
description: Unique order identifier
example: "ord_xyz789"
readOnly: true
status:
type: string
description: |
Current order status. Transitions:
- `pending` -> `confirmed` (after payment)
- `confirmed` -> `shipped` (after fulfillment)
- `shipped` -> `delivered` (after delivery confirmation)
- `pending|confirmed` -> `cancelled` (before shipping)
enum: [pending, confirmed, shipped, delivered, cancelled]# cURL
HTTP client request -X POST [reference URL] \
-H "Authorization: Bearer sk_test_EXAMPLE_KEY_REPLACE_ME" \
-H "Content-Type: application/json" \
-H "API-Version: 2024-01-15" \
-d '{
"items": [
{"product_id": "prod_abc123", "quantity": 2}
],
"shipping_address": {
"line1": "123 Main St",
"city": "San Francisco",
"state": "CA",
"postal_code": "94102",
"country": "US"
}
}'# Python
import company_sdk
client = company_sdk.Client(api_key="sk_test_EXAMPLE_KEY_REPLACE_ME")
order = client.orders.create(
items=[
{"product_id": "prod_abc123", "quantity": 2}
],
shipping_address={
"line1": "123 Main St",
"city": "San Francisco",
"state": "CA",
"postal_code": "94102",
"country": "US",
}
)
print(f"Order created: {order.id}")
print(f"Total: ${order.total}")// Node.js
const Company = require('company-sdk');
const client = new Company('sk_test_EXAMPLE_KEY_REPLACE_ME');
const order = await client.orders.create({
items: [
{ product_id: 'prod_abc123', quantity: 2 }
],
shipping_address: {
line1: '123 Main St',
city: 'San Francisco',
state: 'CA',
postal_code: '94102',
country: 'US',
}
});
console.log(`Order created: ${order.id}`);
console.log(`Total: $${order.total}`);DO:
- Show complete, copy-paste-ready examples
- Include error handling in examples
- Use realistic (but fake) data
- Show the response alongside the request
- Include the SDK version in installation instructions
- Highlight the key parameters with inline comments
DON'T:
- Use real API keys; use clearly-marked test keys (e.g., sk_test_EXAMPLE_KEY_REPLACE_ME)
- Show only the happy path (include error handling)
- Assume SDK is already installed (show installation)
- Use outdated SDK methods
- Skip import/require statements# Quickstart: Create Your First Order
Get up and running with the Orders API in 5 minutes.
## Prerequisites
- A Company account ([sign up free]([reference URL]))
- An API key from [Dashboard > API Keys]([reference URL])
## Step 1: Install the SDK
Choose your language:
**Python** (requires Python 3.8+)
> install via pip: company-sdk
**Node.js** (requires Node 18+)
> install via npm: company-sdk
## Step 2: Make your first API call
[Code example: list products]
**Expected response:**
[Show formatted JSON response]
## Step 3: Create an order
[Code example: create order with error handling]
**Expected response:**
[Show the order object with status: "pending"]
## Step 4: Check order status
[Code example: get order by ID]
## Next Steps
- [Authentication Guide](/docs/auth) - Learn about API keys and OAuth
- [Webhooks](/docs/webhooks) - Get real-time order status updates
- [Full API Reference](/docs/api) - Explore all endpoints
- [Error Handling](/docs/errors) - Handle errors gracefully# Structured error documentation
error_categories:
authentication:
- code: INVALID_API_KEY
http_status: 401
message: "The API key provided is invalid or expired"
causes:
- "API key was deleted or rotated"
- "Using test key against production endpoint"
- "Key has been compromised and revoked"
resolution: "Generate a new API key in Dashboard > API Keys"
- code: INSUFFICIENT_SCOPE
http_status: 403
message: "Your token lacks the required scope for this endpoint"
causes:
- "OAuth token was not granted the needed scope"
resolution: "Request additional scopes during OAuth authorization"
validation:
- code: INVALID_PARAMETER
http_status: 400
message: "A required parameter is missing or invalid"
fields:
field: "The parameter that failed validation"
expected: "What was expected"
received: "What was received"
example:
error:
code: "INVALID_PARAMETER"
message: "quantity must be a positive integer"
field: "items[0].quantity"
expected: "integer > 0"
received: "-1"
rate_limiting:
- code: RATE_LIMIT_EXCEEDED
http_status: 429
message: "Too many requests"
headers:
X-RateLimit-Limit: "Maximum requests per window"
X-RateLimit-Remaining: "Requests remaining in window"
X-RateLimit-Reset: "Unix timestamp when window resets"
Retry-After: "Seconds to wait before retrying"
resolution: |
Implement exponential backoff. Check Retry-After header
for the recommended wait time.
code_example: |
# Python: Automatic retry with backoff
import time
def api_call_with_retry(func, max_retries=3):
for attempt in range(max_retries):
response = func()
if response.status_code != 429:
return response
retry_after = int(response.headers.get('Retry-After', 60))
time.sleep(retry_after)
raise RateLimitError("Max retries exceeded")Completeness:
[ ] Every endpoint has description, parameters, and examples
[ ] All error codes documented with resolution steps
[ ] Authentication fully explained with code
[ ] Rate limits and quotas documented
[ ] Pagination strategy documented
[ ] Webhook events and payloads documented
[ ] Changelog tracks breaking and non-breaking changes
Clarity:
[ ] Quickstart gets developer to "hello world" in < 5 minutes
[ ] Code examples are copy-paste ready
[ ] Examples show error handling, not just happy path
[ ] Jargon is defined in a glossary
[ ] Warnings and important notes are visually distinct
Developer Experience:
[ ] Code examples in at least 3 languages
[ ] Try-it-out console available for each endpoint
[ ] Search works across all documentation
[ ] Code examples include expected response
[ ] Authentication tokens in examples use realistic format
Maintenance:
[ ] OpenAPI spec is source of truth (docs auto-generated)
[ ] Code examples tested in CI
[ ] Docs versioned alongside API versions
[ ] Feedback mechanism on each page
[ ] Analytics tracking which pages have high bounce rateUse this skill when:
Designing or implementing api documentation writer solutions
Reviewing or improving existing api documentation writer approaches
Making architectural or implementation decisions about api documentation writer
Learning api documentation writer patterns and best practices
Troubleshooting api documentation writer-related issues
Do NOT use this skill when:
The question is about a fundamentally different technology domain
A more specific sibling skill covers the exact topic needed
The user needs a complete hands-on tutorial rather than expert guidance
# Api Documentation Writer Analysis
## Context Assessment
[Situation summary and constraints]
## Recommended Approach
[Primary recommendation with rationale]
## Implementation Steps
1. [Step with specific details]
2. [Step with specific details]
3. [Step with specific details]
## Trade-offs and Considerations
- [Key trade-off 1]
- [Key trade-off 2]
## Next Steps
- [Immediate action item]
- [Follow-up action item]Input: "Help me implement api documentation writer for a medium-scale production application"
Output: A structured analysis covering current state assessment, recommended api documentation writer approach with specific patterns, implementation roadmap with milestones, and risk mitigation strategies tailored to the application scale and constraints.
Legacy system integration: When api documentation writer must coexist with legacy approaches, provide a gradual migration path rather than a complete rewrite
Scale mismatch: When the solution complexity exceeds the project scale, recommend a simpler approach and note when to revisit
Team skill gaps: When the team lacks experience with the recommended approach, include learning resources and simpler alternatives
Conflicting requirements: When constraints conflict (e.g., performance vs. maintainability), explicitly state the trade-off and recommend based on stated priorities
SKILL.md
518 lines · 1,778 words
The text of SKILL.md is shown as it downloads, under the Apache-2.0 license, by Ferrox Labs. The license is the one in the file's own frontmatter.
Your new bot
API Documentation Writer bot
Waiting in your sidebar once you say go.
No account needed · Runs on the AI plan you already pay for