[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"skill:01M73C0DBD2Q8H6RGKCG58K3FE":3,"skill-same:01M73C0DBD2Q8H6RGKCG58K3FE":63},{"skillNo":4,"name":5,"nameZh":6,"description":7,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":9,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":15,"categories":16,"keywords":17,"publishedAt":18,"linkOnly":19,"markdownContent":20,"markdownBody":21,"frontMatter":22,"refName":41,"commitSha":42,"skillDirectory":43,"forksCount":44,"repositoryHtmlUrl":45,"repositoryHomepageUrl":6,"ownerHtmlUrl":46,"ownerBlogUrl":6,"ownerDescription":47,"updatedAt":48,"install":49,"resources":62},"01M73C0DBD2Q8H6RGKCG58K3FE","api-documentation",null,"Creates comprehensive API documentation including endpoints, parameters, authentication, request\u002Fresponse schemas, and code examples. Use when: documenting REST APIs, GraphQL interfaces, SDKs, or developer-facing technical specifications.","5throck\u002Fai-workspace-standards","5throck","https:\u002F\u002Favatars.githubusercontent.com\u002Fu\u002F10958964?v=4","01M73BFEH0V0VS483TW4JD49JW","01M73BFEJ5VQZJHJSFTVPAZGDM",25,"AGPL-3.0","https:\u002F\u002Fgithub.com\u002F5throck\u002Fai-workspace-standards\u002Fblob\u002Fmain\u002F.gemini\u002Fskills\u002Fapi-documentation\u002FSKILL.md",[],[],"2026-11-11 15:11:14",false,"---\nname: api-documentation\ndescription: >\n  Creates comprehensive API documentation including endpoints, parameters, authentication,\n  request\u002Fresponse schemas, and code examples. Use when: documenting REST APIs, GraphQL\n  interfaces, SDKs, or developer-facing technical specifications.\nversion: 1.0.2\nscope: common\nstatus: active\nowner: pm\nlast_reviewed: 2026-11-08\nprerequisites: none\ngemini-parity: skip\nmetadata:\n  type: implementation\n  triggers:\n    - api documentation\n    - document api\n    - api reference\n    - developer documentation\n    - rest api docs\n    - graphql docs\n    - sdk documentation\n---\n\n## Context\n\nThis skill provides systematic API documentation capabilities, creating comprehensive developer resources that enable API integration and adoption. It ensures documentation is accurate, complete, and developer-friendly.\n\n## When to Use\n\n**API Documentation**:\n- Trigger: \"Document the API\" or \"Create API reference\"\n- Use Case: Creating comprehensive documentation for REST\u002FGraphQL APIs\n\n**SDK Documentation**:\n- Trigger: \"Document SDK\" or \"Create library documentation\"\n- Use Case: Documenting software development kits and client libraries\n\n**API Updates**:\n- Trigger: \"Update API docs for new endpoint\" or \"Document breaking changes\"\n- Use Case: Keeping documentation current with API changes\n\n**Developer Resources**:\n- Trigger: \"Create developer guide\" or \"Write integration tutorial\"\n- Use Case: Helping developers integrate with APIs successfully\n\n---\n\n## Execution Steps\n\n## Step 1: API Analysis and Structure\n\n**Purpose**: Understand API structure and documentation requirements.\n\n**API Analysis Process**:\n1. **API Type Identification**:\n   - REST API (resources, HTTP methods, status codes)\n   - GraphQL API (schema, queries, mutations)\n   - RPC\u002FGraphQL (procedure calls)\n   - WebSocket API (real-time communication)\n   - SDK\u002FLibrary (classes, methods, parameters)\n\n2. **Endpoint\u002FOperation Inventory**:\n   - List all endpoints or operations\n   - Group by resource or functionality\n   - Identify authentication requirements\n   - Note rate limiting or throttling\n\n3. **Data Model Analysis**:\n   - Request schemas and parameters\n   - Response schemas and formats\n   - Data types and validation rules\n   - Error response formats\n\n4. **Developer Use Cases**:\n   - Common integration scenarios\n   - Typical workflows and sequences\n   - Authentication flows\n   - Error handling examples\n\n**Documentation Structure**:\n```\n1. Overview (getting started, authentication)\n2. Quick Start (simple example)\n3. API Reference (detailed endpoints)\n4. Guides (tutorials, best practices)\n5. SDK Reference (if applicable)\n6. Error Handling (troubleshooting)\n7. Changelog (version history)\n```\n\n---\n\n## Step 2: Getting Started Documentation\n\n**Purpose**: Help developers begin using the API quickly.\n\n**Getting Started Components**:\n1. **Overview Section**:\n   - What the API does\n   - Key features and capabilities\n   - Use cases and benefits\n   - Access requirements (API keys, OAuth)\n\n2. **Authentication Guide**:\n   - Authentication methods (API key, OAuth, JWT)\n   - How to obtain credentials\n   - How to include credentials in requests\n   - Token refresh procedures\n\n3. **Quick Start Example**:\n   - Simple, working example\n   - Minimal required parameters\n   - Expected response\n   - Language-specific examples (Python, JavaScript, cURL)\n\n4. **Setup Instructions**:\n   - Environment setup\n   - Dependency installation\n   - Configuration steps\n   - First request walkthrough\n\n**Quick Start Template**:\n```markdown\n## Quick Start\n\n### 1. Get API Key\nRegister at [url] to get your API key\n\n### 2. Make Your First Request\n\\`\\`\\`bash\ncurl -X GET \"https:\u002F\u002Fapi.example.com\u002Fv1\u002Fusers\" \\\\\n  -H \"Authorization: Bearer YOUR_API_KEY\"\n\\`\\`\\`\n\n### 3. Expected Response\n\\`\\`\\`json\n{\n  \"users\": [...],\n  \"total\": 10\n}\n\\`\\`\\`\n```\n\n---\n\n## Step 3: API Reference Documentation\n\n**Purpose**: Create detailed documentation for each endpoint\u002Foperation.\n\n**Endpoint Documentation Structure**:\n1. **Endpoint Overview**:\n   - HTTP method and path\n   - Description of what it does\n   - Use case example\n   - Rate limiting info\n\n2. **Request Parameters**:\n   - Path parameters (required)\n   - Query parameters (optional)\n   - Request body schema\n   - Headers required\n   - Authentication requirements\n\n3. **Response Documentation**:\n   - Success response schema\n   - Example responses\n   - Status codes and meanings\n   - Pagination info (if applicable)\n\n4. **Error Responses**:\n   - Error response format\n   - Common error codes\n   - Troubleshooting steps\n   - Error examples\n\n**Endpoint Template**:\n```markdown\n## Get Users\n\nRetrieves a list of users with optional filtering.\n\n### Request\n\\`GET \u002Fv1\u002Fusers\\`\n\n### Query Parameters\n| Parameter | Type | Required | Description |\n|-----------|------|----------|-------------|\n| limit | integer | No | Number of results (1-100, default: 20) |\n| offset | integer | No | Pagination offset (default: 0) |\n\n### Response\n\\`\\`\\`json\n{\n  \"users\": [\n    {\n      \"id\": \"user_123\",\n      \"name\": \"John Doe\",\n      \"email\": \"john@example.com\"\n    }\n  ],\n  \"total\": 1,\n  \"limit\": 20,\n  \"offset\": 0\n}\n\\`\\`\\`\n\n### Errors\n| Status | Description |\n|--------|-------------|\n| 400 | Invalid query parameter |\n| 401 | Unauthorized (invalid API key) |\n| 429 | Rate limit exceeded |\n```\n\n---\n\n## Step 4: Request\u002FResponse Schema Documentation\n\n**Purpose**: Document data structures and validation rules.\n\n**Schema Documentation**:\n1. **Request Schemas**:\n   - JSON Schema or TypeScript interfaces\n   - Required vs. optional fields\n   - Validation rules\n   - Constraints and ranges\n   - Example requests\n\n2. **Response Schemas**:\n   - Response object structure\n   - Field descriptions and types\n   - Nullable fields\n   - Enum values\n   - Example responses\n\n3. **Data Types**:\n   - Primitives (string, integer, boolean)\n   - Complex types (arrays, objects)\n   - Date\u002Ftime formats\n   - Enumerations\n   - Custom formats\n\n**Schema Documentation Format**:\n```markdown\n### User Object\n\n| Field | Type | Nullable | Description |\n|-------|------|----------|-------------|\n| id | string | No | Unique user identifier |\n| name | string | No | User's full name |\n| email | string | No | User's email address |\n| created_at | string (ISO 8601) | No | Account creation timestamp |\n| updated_at | string (ISO 8601) | Yes | Last update timestamp |\n\n**Example**\n\\`\\`\\`json\n{\n  \"id\": \"user_123\",\n  \"name\": \"John Doe\",\n  \"email\": \"john@example.com\",\n  \"created_at\": \"2026-05-26T12:00:00Z\"\n}\n\\`\\`\\`\n```\n\n---\n\n## Step 5: Code Examples and SDKs\n\n**Purpose**: Provide working code examples in multiple languages.\n\n**Code Example Guidelines**:\n1. **Language Coverage**:\n   - JavaScript\u002FNode.js (web developers)\n   - Python (data scientists, backend)\n   - Java\u002FTypeScript (enterprise)\n   - cURL (testing\u002Fdebugging)\n   - Popular frameworks (React, Vue, Django)\n\n2. **Example Quality**:\n   - Complete, runnable examples\n   - Include error handling\n   - Show authentication\n   - Display response handling\n   - Add comments explaining key steps\n\n3. **SDK Documentation** (if applicable):\n   - Installation instructions\n   - Class\u002Fmethod documentation\n   - Usage examples\n   - Configuration options\n   - Error handling patterns\n\n**Code Example Template**:\n```python\nimport os\nimport requests\n\nAPI_KEY = os.environ[\"API_KEY\"]  # never hardcode credentials\nBASE_URL = \"https:\u002F\u002Fapi.example.com\u002Fv1\"\n\ndef get_users(limit=20, offset=0):\n    \"\"\"\n    Retrieve a list of users.\n    \n    Args:\n        limit: Number of results (1-100)\n        offset: Pagination offset\n    \n    Returns:\n        List of users\n    \n    Raises:\n        ValueError: If parameters are invalid\n        requests.HTTPError: If API request fails\n    \"\"\"\n    url = f\"{BASE_URL}\u002Fusers\"\n    headers = {\"Authorization\": f\"Bearer {API_KEY}\"}\n    params = {\"limit\": limit, \"offset\": offset}\n    \n    try:\n        response = requests.get(url, headers=headers, params=params)\n        response.raise_for_status()\n        return response.json()\n    except requests.exceptions.HTTPError as e:\n        print(f\"API Error: {e}\")\n        raise\n```\n\n---\n\n## Step 6: Error Handling and Troubleshooting\n\n**Purpose**: Help developers handle errors effectively.\n\n**Error Documentation**:\n1. **HTTP Status Codes**:\n   - Success codes (200, 201, 204)\n   - Client errors (400, 401, 403, 404, 429)\n   - Server errors (500, 502, 503)\n   - Status code meanings and remedies\n\n2. **Error Response Format**:\n   - Error response structure\n   - Error codes and types\n   - Error messages\n   - Debug information\n\n3. **Common Issues**:\n   - Authentication failures\n   - Rate limiting\n   - Invalid parameters\n   - Network errors\n   - Timeout issues\n\n4. **Troubleshooting Guides**:\n   - Step-by-step problem resolution\n   - Debugging tips\n   - Contact support info\n   - Community resources\n\n**Error Documentation Template**:\n```markdown\n## Error Handling\n\n### HTTP Status Codes\n\n| Status | Meaning | Resolution |\n|--------|---------|------------|\n| 400 | Bad Request | Fix request parameters |\n| 401 | Unauthorized | Check API key |\n| 403 | Forbidden | Insufficient permissions |\n| 404 | Not Found | Verify endpoint URL |\n| 429 | Rate Limit | Wait and retry |\n\n### Error Response Format\n\\`\\`\\`json\n{\n  \"error\": {\n    \"code\": \"INVALID_PARAMETER\",\n    \"message\": \"Invalid value for 'limit' parameter\",\n    \"details\": {\n      \"parameter\": \"limit\",\n      \"value\": 999,\n      \"constraint\": \"1-100\"\n    }\n  }\n}\n\\`\\`\\`\n\n### Common Issues\n\n**Issue**: \"401 Unauthorized\"\n**Solution**: Verify API key is correct and not expired\n\n**Issue**: \"429 Rate Limit Exceeded\"\n**Solution**: Implement exponential backoff, wait before retry\n```\n\n---\n\n## Step 7: Versioning and Changelog\n\n**Purpose**: Document API evolution and breaking changes.\n\n**Versioning Strategy**:\n1. **Semantic Versioning**:\n   - MAJOR: Breaking changes\n   - MINOR: New features, backward compatible\n   - PATCH: Bug fixes\n\n2. **URL Versioning**:\n   - Include version in URL path (\u002Fv1\u002F, \u002Fv2\u002F)\n   - Document deprecation timeline\n   - Provide migration guides\n\n3. **Header Versioning**:\n   - Use Accept header for versioning\n   - Document supported versions\n   - Default version behavior\n\n**Changelog Format**:\n```markdown\n## Changelog\n\n### [Version] - [Date]\n\n#### Added\n- New endpoint description\n- New parameter description\n\n#### Changed\n- Modified endpoint behavior\n- Updated response format\n\n#### Deprecated\n- Endpoint deprecation notice\n\n#### Removed\n- Removed endpoint (include migration guide)\n```\n\n---\n\n## Output Format\n\n**For REST API Documentation**:\n- Complete API reference with all endpoints\n- Authentication and security guide\n- Request\u002Fresponse schema documentation\n- Code examples in multiple languages\n- Error handling and troubleshooting guide\n\n**For GraphQL API Documentation**:\n- Schema documentation with types\n- Query and mutation reference\n- Subscription documentation\n- Example queries and mutations\n- Integration guides\n\n**For SDK Documentation**:\n- Installation and setup guide\n- Class\u002Fmethod reference\n- Usage examples and patterns\n- Configuration options\n- Error handling patterns\n\n---\n\n## Best Practices\n\n**Documentation Quality**:\n✅ **Do**:\n- Start with quick start for fast onboarding\n- Provide working code examples\n- Include error handling in examples\n- Keep documentation up-to-date with API changes\n- Use consistent formatting and structure\n- Include pagination and filtering info\n- Document rate limits and throttling\n\n❌ **Don't**:\n- Skip authentication documentation\n- Use placeholder code that doesn't work\n- Forget to document error responses\n- Make examples too complex\n- Ignore edge cases and errors\n- Leave documentation outdated\n- Use jargon without explanation\n\n**Developer Experience**:\n✅ **Do**:\n- Write for busy developers\n- Assume no prior API knowledge\n- Provide copy-paste examples\n- Include common workflows\n- Link to related resources\n- Make content searchable\n- Support multiple languages\n\n❌ **Don't**:\n- Write like academic textbook\n- Assume readers know your API\n- Make examples too simple (unrealistic)\n- Skip error scenarios\n- Leave out important context\n- Make content hard to navigate\n- Focus on one language only\n\n---\n\n## Common Mistakes to Avoid\n\n**Documentation Anti-Patterns**:\n1. **Outdated Docs**: Documentation not synced with API changes\n2. **Missing Examples**: Text-only without working code\n3. **Poor Search**: Hard to find specific endpoints or info\n4. **Inconsistent Structure**: Different formats across sections\n5. **Missing Context**: Not explaining \"why\" or \"when to use\"\n\n**Content Anti-Patterns**:\n1. **Assumptions**: Assuming prior knowledge\n2. **Ambiguity**: Unclear parameter descriptions\n3. **Incomplete Info**: Missing required parameters\n4. **No Error Handling**: Examples without error cases\n5. **Dead Links**: References to non-existent resources\n\n---\n\n## Related Skills\n\n- **documentation-writing**: For general documentation principles\n- **technical-writing**: For technical communication best practices\n- **code-review**: For validating code examples\n- **developer-experience**: For overall developer portal design\n\n---\n\n## API Documentation Tools\n\n**Static Site Generators**:\n- **Docusaurus**: Facebook's React-based doc generator\n- **MkDocs**: Python-based static site generator\n- **VuePress**: Vue-powered documentation generator\n- **GitBook**: Book-style documentation platform\n\n**API Documentation Tools**:\n- **Swagger\u002FOpenAPI**: REST API specification\n- **Postman**: API documentation and testing\n- **Insomnia**: REST client and documentation\n- **Stoplight**: API design and documentation\n\n**Interactive API Explorers**:\n- **Swagger UI**: OpenAPI specification visualization\n- **ReDoc**: Beautiful OpenAPI documentation\n- **GraphQL Playground**: Interactive GraphQL explorer\n- **Postman**: API testing and documentation\n\n**Code Examples Tools**:\n- **Snippets**: Code snippet management\n- **Carbon**: Beautiful code screenshots\n- **APIary**: API design and documentation\n\n---\n\n## Documentation Quality Checklist\n\n**Content Quality**:\n- [ ] Quick start guide exists\n- [ ] All endpoints documented\n- [ ] Request parameters explained\n- [ ] Response schemas documented\n- [ ] Error responses documented\n- [ ] Code examples work correctly\n- [ ] Authentication documented\n- [ ] Rate limits specified\n- [ ] Pagination explained\n- [ ] Versioning strategy clear\n\n**Usability Quality**:\n- [ ] Easy to navigate\n- [ ] Searchable content\n- [ ] Consistent formatting\n- [ ] Mobile-friendly\n- [ ] Print-friendly\n- [ ] Cross-browser compatible\n- [ ] Fast loading\n- [ ] Accessible (WCAG AA)\n\n**Maintainability Quality**:\n- [ ] Version controlled\n- [ ] Easy to update\n- [ ] Clear change log\n- [ ] Deprecation policy defined\n- [ ] Migration guides provided\n- [ ] Feedback mechanism exists\n- [ ] Regularly reviewed and updated\n\n---\n\n## OpenAPI\u002FSwagger Specification\n\n**OpenAPI 3.0 Structure**:\n```yaml\nopenapi: 3.0.0\ninfo:\n  title: API Name\n  version: 1.0.0\n  description: API description\nservers:\n  - url: https:\u002F\u002Fapi.example.com\u002Fv1\n    description: Production server\n\npaths:\n  \u002Fusers:\n    get:\n      summary: Get users\n      description: Retrieve list of users\n      parameters:\n        - name: limit\n          in: query\n          schema:\n            type: integer\n          description: Number of results\n      responses:\n        '200':\n          description: Successful response\n          content:\n            application\u002Fjson:\n              schema:\n                type: object\n                properties:\n                  users:\n                    type: array\n                    items:\n                      $ref: '#\u002Fcomponents\u002Fschemas\u002FUser'\n```\n\n---\n\n## GraphQL Documentation\n\n**GraphQL Documentation Components**:\n1. **Schema Documentation**:\n   - Types (objects, interfaces, enums)\n   - Queries (read operations)\n   - Mutations (write operations)\n   - Subscriptions (real-time)\n\n2. **Operation Documentation**:\n   - Query\u002Fmutation signature\n   - Parameters and arguments\n   - Return type\n   - Usage examples\n\n3. **Example Queries**:\n   - Simple queries\n   - Complex nested queries\n   - Mutations with inputs\n   - Subscriptions setup\n\n**GraphQL Documentation Format**:\n```graphql\n\"\"\"\nUser type definition\n\"\"\"\ntype User {\n  \"\"\"\n  Unique user identifier\n  \"\"\"\n  id: ID!\n  \n  \"\"\"\n  User's full name\n  \"\"\"\n  name: String!\n  \n  \"\"\"\n  User's email address\n  \"\"\"\n  email: String!\n  \n  \"\"\"\n  Timestamp when user was created\n  \"\"\"\n  createdAt: String!\n}\n\n\"\"\"\nQuery users\n\"\"\"\ntype Query {\n  \"\"\"\n  Get list of users\n  \"\"\"\n  users(\n    \"\"\"\n    Number of users to return\n    \"\"\"\n    limit: Int = 20\n    \n    \"\"\"\n    Pagination offset\n    \"\"\"\n    offset: Int = 0\n  ): [User!]!\n}\n```\n","## Context\n\nThis skill provides systematic API documentation capabilities, creating comprehensive developer resources that enable API integration and adoption. It ensures documentation is accurate, complete, and developer-friendly.\n\n## When to Use\n\n**API Documentation**:\n- Trigger: \"Document the API\" or \"Create API reference\"\n- Use Case: Creating comprehensive documentation for REST\u002FGraphQL APIs\n\n**SDK Documentation**:\n- Trigger: \"Document SDK\" or \"Create library documentation\"\n- Use Case: Documenting software development kits and client libraries\n\n**API Updates**:\n- Trigger: \"Update API docs for new endpoint\" or \"Document breaking changes\"\n- Use Case: Keeping documentation current with API changes\n\n**Developer Resources**:\n- Trigger: \"Create developer guide\" or \"Write integration tutorial\"\n- Use Case: Helping developers integrate with APIs successfully\n\n---\n\n## Execution Steps\n\n## Step 1: API Analysis and Structure\n\n**Purpose**: Understand API structure and documentation requirements.\n\n**API Analysis Process**:\n1. **API Type Identification**:\n   - REST API (resources, HTTP methods, status codes)\n   - GraphQL API (schema, queries, mutations)\n   - RPC\u002FGraphQL (procedure calls)\n   - WebSocket API (real-time communication)\n   - SDK\u002FLibrary (classes, methods, parameters)\n\n2. **Endpoint\u002FOperation Inventory**:\n   - List all endpoints or operations\n   - Group by resource or functionality\n   - Identify authentication requirements\n   - Note rate limiting or throttling\n\n3. **Data Model Analysis**:\n   - Request schemas and parameters\n   - Response schemas and formats\n   - Data types and validation rules\n   - Error response formats\n\n4. **Developer Use Cases**:\n   - Common integration scenarios\n   - Typical workflows and sequences\n   - Authentication flows\n   - Error handling examples\n\n**Documentation Structure**:\n```\n1. Overview (getting started, authentication)\n2. Quick Start (simple example)\n3. API Reference (detailed endpoints)\n4. Guides (tutorials, best practices)\n5. SDK Reference (if applicable)\n6. Error Handling (troubleshooting)\n7. Changelog (version history)\n```\n\n---\n\n## Step 2: Getting Started Documentation\n\n**Purpose**: Help developers begin using the API quickly.\n\n**Getting Started Components**:\n1. **Overview Section**:\n   - What the API does\n   - Key features and capabilities\n   - Use cases and benefits\n   - Access requirements (API keys, OAuth)\n\n2. **Authentication Guide**:\n   - Authentication methods (API key, OAuth, JWT)\n   - How to obtain credentials\n   - How to include credentials in requests\n   - Token refresh procedures\n\n3. **Quick Start Example**:\n   - Simple, working example\n   - Minimal required parameters\n   - Expected response\n   - Language-specific examples (Python, JavaScript, cURL)\n\n4. **Setup Instructions**:\n   - Environment setup\n   - Dependency installation\n   - Configuration steps\n   - First request walkthrough\n\n**Quick Start Template**:\n```markdown\n## Quick Start\n\n### 1. Get API Key\nRegister at [url] to get your API key\n\n### 2. Make Your First Request\n\\`\\`\\`bash\ncurl -X GET \"https:\u002F\u002Fapi.example.com\u002Fv1\u002Fusers\" \\\\\n  -H \"Authorization: Bearer YOUR_API_KEY\"\n\\`\\`\\`\n\n### 3. Expected Response\n\\`\\`\\`json\n{\n  \"users\": [...],\n  \"total\": 10\n}\n\\`\\`\\`\n```\n\n---\n\n## Step 3: API Reference Documentation\n\n**Purpose**: Create detailed documentation for each endpoint\u002Foperation.\n\n**Endpoint Documentation Structure**:\n1. **Endpoint Overview**:\n   - HTTP method and path\n   - Description of what it does\n   - Use case example\n   - Rate limiting info\n\n2. **Request Parameters**:\n   - Path parameters (required)\n   - Query parameters (optional)\n   - Request body schema\n   - Headers required\n   - Authentication requirements\n\n3. **Response Documentation**:\n   - Success response schema\n   - Example responses\n   - Status codes and meanings\n   - Pagination info (if applicable)\n\n4. **Error Responses**:\n   - Error response format\n   - Common error codes\n   - Troubleshooting steps\n   - Error examples\n\n**Endpoint Template**:\n```markdown\n## Get Users\n\nRetrieves a list of users with optional filtering.\n\n### Request\n\\`GET \u002Fv1\u002Fusers\\`\n\n### Query Parameters\n| Parameter | Type | Required | Description |\n|-----------|------|----------|-------------|\n| limit | integer | No | Number of results (1-100, default: 20) |\n| offset | integer | No | Pagination offset (default: 0) |\n\n### Response\n\\`\\`\\`json\n{\n  \"users\": [\n    {\n      \"id\": \"user_123\",\n      \"name\": \"John Doe\",\n      \"email\": \"john@example.com\"\n    }\n  ],\n  \"total\": 1,\n  \"limit\": 20,\n  \"offset\": 0\n}\n\\`\\`\\`\n\n### Errors\n| Status | Description |\n|--------|-------------|\n| 400 | Invalid query parameter |\n| 401 | Unauthorized (invalid API key) |\n| 429 | Rate limit exceeded |\n```\n\n---\n\n## Step 4: Request\u002FResponse Schema Documentation\n\n**Purpose**: Document data structures and validation rules.\n\n**Schema Documentation**:\n1. **Request Schemas**:\n   - JSON Schema or TypeScript interfaces\n   - Required vs. optional fields\n   - Validation rules\n   - Constraints and ranges\n   - Example requests\n\n2. **Response Schemas**:\n   - Response object structure\n   - Field descriptions and types\n   - Nullable fields\n   - Enum values\n   - Example responses\n\n3. **Data Types**:\n   - Primitives (string, integer, boolean)\n   - Complex types (arrays, objects)\n   - Date\u002Ftime formats\n   - Enumerations\n   - Custom formats\n\n**Schema Documentation Format**:\n```markdown\n### User Object\n\n| Field | Type | Nullable | Description |\n|-------|------|----------|-------------|\n| id | string | No | Unique user identifier |\n| name | string | No | User's full name |\n| email | string | No | User's email address |\n| created_at | string (ISO 8601) | No | Account creation timestamp |\n| updated_at | string (ISO 8601) | Yes | Last update timestamp |\n\n**Example**\n\\`\\`\\`json\n{\n  \"id\": \"user_123\",\n  \"name\": \"John Doe\",\n  \"email\": \"john@example.com\",\n  \"created_at\": \"2026-05-26T12:00:00Z\"\n}\n\\`\\`\\`\n```\n\n---\n\n## Step 5: Code Examples and SDKs\n\n**Purpose**: Provide working code examples in multiple languages.\n\n**Code Example Guidelines**:\n1. **Language Coverage**:\n   - JavaScript\u002FNode.js (web developers)\n   - Python (data scientists, backend)\n   - Java\u002FTypeScript (enterprise)\n   - cURL (testing\u002Fdebugging)\n   - Popular frameworks (React, Vue, Django)\n\n2. **Example Quality**:\n   - Complete, runnable examples\n   - Include error handling\n   - Show authentication\n   - Display response handling\n   - Add comments explaining key steps\n\n3. **SDK Documentation** (if applicable):\n   - Installation instructions\n   - Class\u002Fmethod documentation\n   - Usage examples\n   - Configuration options\n   - Error handling patterns\n\n**Code Example Template**:\n```python\nimport os\nimport requests\n\nAPI_KEY = os.environ[\"API_KEY\"]  # never hardcode credentials\nBASE_URL = \"https:\u002F\u002Fapi.example.com\u002Fv1\"\n\ndef get_users(limit=20, offset=0):\n    \"\"\"\n    Retrieve a list of users.\n    \n    Args:\n        limit: Number of results (1-100)\n        offset: Pagination offset\n    \n    Returns:\n        List of users\n    \n    Raises:\n        ValueError: If parameters are invalid\n        requests.HTTPError: If API request fails\n    \"\"\"\n    url = f\"{BASE_URL}\u002Fusers\"\n    headers = {\"Authorization\": f\"Bearer {API_KEY}\"}\n    params = {\"limit\": limit, \"offset\": offset}\n    \n    try:\n        response = requests.get(url, headers=headers, params=params)\n        response.raise_for_status()\n        return response.json()\n    except requests.exceptions.HTTPError as e:\n        print(f\"API Error: {e}\")\n        raise\n```\n\n---\n\n## Step 6: Error Handling and Troubleshooting\n\n**Purpose**: Help developers handle errors effectively.\n\n**Error Documentation**:\n1. **HTTP Status Codes**:\n   - Success codes (200, 201, 204)\n   - Client errors (400, 401, 403, 404, 429)\n   - Server errors (500, 502, 503)\n   - Status code meanings and remedies\n\n2. **Error Response Format**:\n   - Error response structure\n   - Error codes and types\n   - Error messages\n   - Debug information\n\n3. **Common Issues**:\n   - Authentication failures\n   - Rate limiting\n   - Invalid parameters\n   - Network errors\n   - Timeout issues\n\n4. **Troubleshooting Guides**:\n   - Step-by-step problem resolution\n   - Debugging tips\n   - Contact support info\n   - Community resources\n\n**Error Documentation Template**:\n```markdown\n## Error Handling\n\n### HTTP Status Codes\n\n| Status | Meaning | Resolution |\n|--------|---------|------------|\n| 400 | Bad Request | Fix request parameters |\n| 401 | Unauthorized | Check API key |\n| 403 | Forbidden | Insufficient permissions |\n| 404 | Not Found | Verify endpoint URL |\n| 429 | Rate Limit | Wait and retry |\n\n### Error Response Format\n\\`\\`\\`json\n{\n  \"error\": {\n    \"code\": \"INVALID_PARAMETER\",\n    \"message\": \"Invalid value for 'limit' parameter\",\n    \"details\": {\n      \"parameter\": \"limit\",\n      \"value\": 999,\n      \"constraint\": \"1-100\"\n    }\n  }\n}\n\\`\\`\\`\n\n### Common Issues\n\n**Issue**: \"401 Unauthorized\"\n**Solution**: Verify API key is correct and not expired\n\n**Issue**: \"429 Rate Limit Exceeded\"\n**Solution**: Implement exponential backoff, wait before retry\n```\n\n---\n\n## Step 7: Versioning and Changelog\n\n**Purpose**: Document API evolution and breaking changes.\n\n**Versioning Strategy**:\n1. **Semantic Versioning**:\n   - MAJOR: Breaking changes\n   - MINOR: New features, backward compatible\n   - PATCH: Bug fixes\n\n2. **URL Versioning**:\n   - Include version in URL path (\u002Fv1\u002F, \u002Fv2\u002F)\n   - Document deprecation timeline\n   - Provide migration guides\n\n3. **Header Versioning**:\n   - Use Accept header for versioning\n   - Document supported versions\n   - Default version behavior\n\n**Changelog Format**:\n```markdown\n## Changelog\n\n### [Version] - [Date]\n\n#### Added\n- New endpoint description\n- New parameter description\n\n#### Changed\n- Modified endpoint behavior\n- Updated response format\n\n#### Deprecated\n- Endpoint deprecation notice\n\n#### Removed\n- Removed endpoint (include migration guide)\n```\n\n---\n\n## Output Format\n\n**For REST API Documentation**:\n- Complete API reference with all endpoints\n- Authentication and security guide\n- Request\u002Fresponse schema documentation\n- Code examples in multiple languages\n- Error handling and troubleshooting guide\n\n**For GraphQL API Documentation**:\n- Schema documentation with types\n- Query and mutation reference\n- Subscription documentation\n- Example queries and mutations\n- Integration guides\n\n**For SDK Documentation**:\n- Installation and setup guide\n- Class\u002Fmethod reference\n- Usage examples and patterns\n- Configuration options\n- Error handling patterns\n\n---\n\n## Best Practices\n\n**Documentation Quality**:\n✅ **Do**:\n- Start with quick start for fast onboarding\n- Provide working code examples\n- Include error handling in examples\n- Keep documentation up-to-date with API changes\n- Use consistent formatting and structure\n- Include pagination and filtering info\n- Document rate limits and throttling\n\n❌ **Don't**:\n- Skip authentication documentation\n- Use placeholder code that doesn't work\n- Forget to document error responses\n- Make examples too complex\n- Ignore edge cases and errors\n- Leave documentation outdated\n- Use jargon without explanation\n\n**Developer Experience**:\n✅ **Do**:\n- Write for busy developers\n- Assume no prior API knowledge\n- Provide copy-paste examples\n- Include common workflows\n- Link to related resources\n- Make content searchable\n- Support multiple languages\n\n❌ **Don't**:\n- Write like academic textbook\n- Assume readers know your API\n- Make examples too simple (unrealistic)\n- Skip error scenarios\n- Leave out important context\n- Make content hard to navigate\n- Focus on one language only\n\n---\n\n## Common Mistakes to Avoid\n\n**Documentation Anti-Patterns**:\n1. **Outdated Docs**: Documentation not synced with API changes\n2. **Missing Examples**: Text-only without working code\n3. **Poor Search**: Hard to find specific endpoints or info\n4. **Inconsistent Structure**: Different formats across sections\n5. **Missing Context**: Not explaining \"why\" or \"when to use\"\n\n**Content Anti-Patterns**:\n1. **Assumptions**: Assuming prior knowledge\n2. **Ambiguity**: Unclear parameter descriptions\n3. **Incomplete Info**: Missing required parameters\n4. **No Error Handling**: Examples without error cases\n5. **Dead Links**: References to non-existent resources\n\n---\n\n## Related Skills\n\n- **documentation-writing**: For general documentation principles\n- **technical-writing**: For technical communication best practices\n- **code-review**: For validating code examples\n- **developer-experience**: For overall developer portal design\n\n---\n\n## API Documentation Tools\n\n**Static Site Generators**:\n- **Docusaurus**: Facebook's React-based doc generator\n- **MkDocs**: Python-based static site generator\n- **VuePress**: Vue-powered documentation generator\n- **GitBook**: Book-style documentation platform\n\n**API Documentation Tools**:\n- **Swagger\u002FOpenAPI**: REST API specification\n- **Postman**: API documentation and testing\n- **Insomnia**: REST client and documentation\n- **Stoplight**: API design and documentation\n\n**Interactive API Explorers**:\n- **Swagger UI**: OpenAPI specification visualization\n- **ReDoc**: Beautiful OpenAPI documentation\n- **GraphQL Playground**: Interactive GraphQL explorer\n- **Postman**: API testing and documentation\n\n**Code Examples Tools**:\n- **Snippets**: Code snippet management\n- **Carbon**: Beautiful code screenshots\n- **APIary**: API design and documentation\n\n---\n\n## Documentation Quality Checklist\n\n**Content Quality**:\n- [ ] Quick start guide exists\n- [ ] All endpoints documented\n- [ ] Request parameters explained\n- [ ] Response schemas documented\n- [ ] Error responses documented\n- [ ] Code examples work correctly\n- [ ] Authentication documented\n- [ ] Rate limits specified\n- [ ] Pagination explained\n- [ ] Versioning strategy clear\n\n**Usability Quality**:\n- [ ] Easy to navigate\n- [ ] Searchable content\n- [ ] Consistent formatting\n- [ ] Mobile-friendly\n- [ ] Print-friendly\n- [ ] Cross-browser compatible\n- [ ] Fast loading\n- [ ] Accessible (WCAG AA)\n\n**Maintainability Quality**:\n- [ ] Version controlled\n- [ ] Easy to update\n- [ ] Clear change log\n- [ ] Deprecation policy defined\n- [ ] Migration guides provided\n- [ ] Feedback mechanism exists\n- [ ] Regularly reviewed and updated\n\n---\n\n## OpenAPI\u002FSwagger Specification\n\n**OpenAPI 3.0 Structure**:\n```yaml\nopenapi: 3.0.0\ninfo:\n  title: API Name\n  version: 1.0.0\n  description: API description\nservers:\n  - url: https:\u002F\u002Fapi.example.com\u002Fv1\n    description: Production server\n\npaths:\n  \u002Fusers:\n    get:\n      summary: Get users\n      description: Retrieve list of users\n      parameters:\n        - name: limit\n          in: query\n          schema:\n            type: integer\n          description: Number of results\n      responses:\n        '200':\n          description: Successful response\n          content:\n            application\u002Fjson:\n              schema:\n                type: object\n                properties:\n                  users:\n                    type: array\n                    items:\n                      $ref: '#\u002Fcomponents\u002Fschemas\u002FUser'\n```\n\n---\n\n## GraphQL Documentation\n\n**GraphQL Documentation Components**:\n1. **Schema Documentation**:\n   - Types (objects, interfaces, enums)\n   - Queries (read operations)\n   - Mutations (write operations)\n   - Subscriptions (real-time)\n\n2. **Operation Documentation**:\n   - Query\u002Fmutation signature\n   - Parameters and arguments\n   - Return type\n   - Usage examples\n\n3. **Example Queries**:\n   - Simple queries\n   - Complex nested queries\n   - Mutations with inputs\n   - Subscriptions setup\n\n**GraphQL Documentation Format**:\n```graphql\n\"\"\"\nUser type definition\n\"\"\"\ntype User {\n  \"\"\"\n  Unique user identifier\n  \"\"\"\n  id: ID!\n  \n  \"\"\"\n  User's full name\n  \"\"\"\n  name: String!\n  \n  \"\"\"\n  User's email address\n  \"\"\"\n  email: String!\n  \n  \"\"\"\n  Timestamp when user was created\n  \"\"\"\n  createdAt: String!\n}\n\n\"\"\"\nQuery users\n\"\"\"\ntype Query {\n  \"\"\"\n  Get list of users\n  \"\"\"\n  users(\n    \"\"\"\n    Number of users to return\n    \"\"\"\n    limit: Int = 20\n    \n    \"\"\"\n    Pagination offset\n    \"\"\"\n    offset: Int = 0\n  ): [User!]!\n}\n```\n",{"name":5,"owner":23,"scope":24,"status":25,"version":26,"metadata":27,"description":37,"gemini-parity":38,"last_reviewed":39,"prerequisites":40},"pm","common","active","1.0.2",{"type":28,"triggers":29},"implementation",[30,31,32,33,34,35,36],"api documentation","document api","api reference","developer documentation","rest api docs","graphql docs","sdk documentation","Creates comprehensive API documentation including endpoints, parameters, authentication, request\u002Fresponse schemas, and code examples. Use when: documenting REST APIs, GraphQL interfaces, SDKs, or developer-facing technical specifications.\n","skip",1794096000000,"none","main","1162ccc568cf90c01b3886d6143cbfd851a37883",".gemini\u002Fskills\u002Fapi-documentation",9,"https:\u002F\u002Fgithub.com\u002F5throck\u002Fai-workspace-standards","https:\u002F\u002Fgithub.com\u002F5throck","Experienced in digital transformation, enterprise IT, startup acceleration, and business strategy. Focused on building practical systems that connect technolo","2026-11-14 21:22:34",{"source":8,"skillName":5,"commands":50,"prompt":60,"zipAvailable":61},[51,54,57],{"tool":52,"command":53},"npx","npx skills add 5throck\u002Fai-workspace-standards --skill api-documentation",{"tool":55,"command":56},"bunx","bunx skills add 5throck\u002Fai-workspace-standards --skill api-documentation",{"tool":58,"command":59},"pnpm","pnpm dlx skills add 5throck\u002Fai-workspace-standards --skill api-documentation","安装技能，技能地址：https:\u002F\u002Fgithub.com\u002F5throck\u002Fai-workspace-standards\u002Fblob\u002Fmain\u002F.gemini\u002Fskills\u002Fapi-documentation\u002FSKILL.md",true,[],[64,72,77,82,87,92],{"skillNo":65,"name":66,"nameZh":6,"description":67,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":9,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":68,"categories":69,"keywords":70,"publishedAt":71},"01M7BBJDYHJMGTJYSC37JVWY8S","i18n-layout","Text layout and encoding guidance: character encoding (UTF-8, legacy Korean code pages, BOM hazards), line endings, RTL\u002Fbidi handling, and script-specific font selection (Hangul focus). Use when: encoding is corrupted or mojibake appears, an RTL locale must render correctly, fonts must be chosen for a script, or CRLF\u002FBOM issues surface.","https:\u002F\u002Fgithub.com\u002F5throck\u002Fai-workspace-standards\u002Fblob\u002Fmain\u002Ftemplates\u002Fco-work\u002Fskills\u002Fi18n-layout\u002FSKILL.md",[],[],"2026-11-15 14:19:17",{"skillNo":73,"name":66,"nameZh":6,"description":67,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":9,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":74,"categories":75,"keywords":76,"publishedAt":71},"01M7BBJ9XHAAS1AVGKZZ841VBZ","https:\u002F\u002Fgithub.com\u002F5throck\u002Fai-workspace-standards\u002Fblob\u002Fmain\u002Ftemplates\u002Fco-work\u002F.hermes\u002Fskills\u002Fi18n-layout\u002FSKILL.md",[],[],{"skillNo":78,"name":66,"nameZh":6,"description":67,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":9,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":79,"categories":80,"keywords":81,"publishedAt":71},"01M7BBJ5C3X8TKFKG5R9P9P49W","https:\u002F\u002Fgithub.com\u002F5throck\u002Fai-workspace-standards\u002Fblob\u002Fmain\u002Ftemplates\u002Fco-work\u002F.gemini\u002Fskills\u002Fi18n-layout\u002FSKILL.md",[],[],{"skillNo":83,"name":66,"nameZh":6,"description":67,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":9,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":84,"categories":85,"keywords":86,"publishedAt":71},"01M7BBJ1B52X0QMJ2QVBMPJB37","https:\u002F\u002Fgithub.com\u002F5throck\u002Fai-workspace-standards\u002Fblob\u002Fmain\u002Ftemplates\u002Fco-work\u002F.codex\u002Fskills\u002Fi18n-layout\u002FSKILL.md",[],[],{"skillNo":88,"name":66,"nameZh":6,"description":67,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":9,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":89,"categories":90,"keywords":91,"publishedAt":71},"01M7BBHX91BW2Q2R276MRX5AW3","https:\u002F\u002Fgithub.com\u002F5throck\u002Fai-workspace-standards\u002Fblob\u002Fmain\u002Ftemplates\u002Fco-work\u002F.claude\u002Fskills\u002Fi18n-layout\u002FSKILL.md",[],[],{"skillNo":93,"name":66,"nameZh":6,"description":67,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":9,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":94,"categories":95,"keywords":96,"publishedAt":71},"01M7BBHQWGXPSFRWN1PRC2NMMV","https:\u002F\u002Fgithub.com\u002F5throck\u002Fai-workspace-standards\u002Fblob\u002Fmain\u002Ftemplates\u002Fco-work\u002F.agents\u002Fskills\u002Fi18n-layout\u002FSKILL.md",[],[]]