Agent Skills
› mohitagw15856/pm-claude-skills
› api-docs-writer
api-docs-writer
GitHub将API规范、Postman集合或端点描述转化为面向开发者的清晰文档。支持Markdown和Confluence格式，包含请求/响应示例、参数说明及错误处理，适用于开发者门户或内部Wiki。
触发场景
需要将API规范转换为开发者文档
整理Postman集合为结构化文档
编写API参考指南或端点说明
安装
npx skills add mohitagw15856/pm-claude-skills --skill api-docs-writer -g -y
SKILL.md
Frontmatter
{
"name": "api-docs-writer",
"description": "Escribe documentación clara de API orientada a desarrolladores. Úsalo cuando necesites documentar un endpoint de API, escribir documentos de referencia de API, crear una guía para desarrolladores o convertir una especificación bruta o colección de Postman en documentación. Produce documentación de endpoints con descripciones, parámetros, ejemplos de solicitud\/respuesta y códigos de error."
}
Skill API Docs Writer
Este skill transforma especificaciones de API brutas, descripciones de endpoints o colecciones de Postman en documentación limpia orientada a desarrolladores, siguiendo convenciones similares a OpenAPI. El resultado está listo para un portal de desarrolladores, README o página de Notion/Confluence.
Entradas Requeridas
Solicita al usuario estos datos si no están disponibles:
- Detalles de API o endpoint (especificación bruta, exportación de Postman o descripción verbal)
- Método de autenticación (clave de API / token Bearer / OAuth 2.0 / Ninguno)
- URL base
- Versión de API (p. ej. v1, v2.3, o "sin versión" — afecta notas de deprecación y headers de versionado)
- Límites de velocidad (solicitudes por segundo/minuto por token o IP, si se conocen — o "desconocido")
- Audiencia (desarrolladores internos / partners externos / público)
- Formato de salida (Markdown para portales de desarrolladores y READMEs / Prosa simple para Confluence o Notion — nota: este skill no produce YAML de OpenAPI)
Formato de Salida
Para cada endpoint, produce lo siguiente:
[MÉTODO] /ruta/al/endpoint
Resumen: [Una línea — qué hace este endpoint]
Descripción: [2–4 oraciones. Cuándo usar este endpoint. Qué devuelve. Comportamiento importante a conocer (paginación, límites de velocidad, procesamiento asíncrono, etc.)]
Autenticación: [Requerida / Opcional — método]
Solicitud
Headers:
| Header | Requerido | Descripción |
|---|---|---|
Authorization |
Sí | Bearer <token> |
Content-Type |
Sí | application/json |
Parámetros de Ruta:
| Parámetro | Tipo | Requerido | Descripción |
|---|---|---|---|
id |
string | Sí | Identificador único del recurso |
Parámetros de Consulta:
| Parámetro | Tipo | Requerido | Predeterminado | Descripción |
|---|---|---|---|---|
limit |
integer | No | 20 | Máximo de resultados por página (1–100) |
cursor |
string | No | — | Cursor de paginación de respuesta anterior |
Cuerpo de la Solicitud:
{
"field_name": "value",
"another_field": 42
}
| Campo | Tipo | Requerido | Descripción |
|---|---|---|---|
field_name |
string | Sí | [Descripción clara de qué hace este campo] |
another_field |
integer | No | [Descripción. Incluye rango válido o valores enum si aplica] |
Respuesta
Respuesta de Éxito: 200 OK
{
"id": "abc123",
"status": "active",
"created_at": "2025-04-01T10:00:00Z"
}
| Campo | Tipo | Descripción |
|---|---|---|
id |
string | Identificador único del recurso creado/recuperado |
status |
string | Estado actual. Enum: active, inactive, pending |
created_at |
string ISO 8601 | Timestamp de creación en UTC |
Códigos de Error
| Código de Estado | Código de Error | Descripción | Cómo Resolver |
|---|---|---|---|
400 |
INVALID_REQUEST |
El cuerpo de solicitud está malformado o falta campos requeridos | Verifica el cuerpo de solicitud contra el schema anterior |
401 |
UNAUTHORIZED |
Token de autenticación faltante o inválido | Verifica tu clave de API o refresca tu token |
404 |
NOT_FOUND |
El recurso solicitado no existe | Verifica el ID en el parámetro de ruta |
429 |
RATE_LIMITED |
Demasiadas solicitudes | Retrocede e intenta de nuevo después del valor del header Retry-After |
500 |
INTERNAL_ERROR |
Error inesperado del servidor | Reinténtalo con backoff exponencial; contacta soporte si persiste |
Ejemplos de Código
Produce ejemplos en al menos 2 lenguajes relevantes para la audiencia (predeterminado: cURL + Python):
cURL:
curl -X POST https://api.example.com/v1/endpoint \
-H "Authorization: Bearer YOUR_TOKEN" \
-H "Content-Type: application/json" \
-d '{"field_name": "value"}'
Python:
import requests
response = requests.post(
"https://api.example.com/v1/endpoint",
headers={"Authorization": "Bearer YOUR_TOKEN"},
json={"field_name": "value"}
)
data = response.json()
Controles de Calidad
- Cada parámetro está documentado (tipo, requerido/opcional, descripción)
- Los campos de respuesta están completamente documentados con tipos
- Se listan todos los códigos de error relevantes con orientación de resolución
- Los códigos de error cubren como mínimo: 400 (solicitud incorrecta), 401/403 (autenticación), 404 (no encontrado), 429 (límite de velocidad), 500 (error del servidor) — o indica explícitamente cuáles no aplican a este endpoint
- Los ejemplos de código usan la URL base actual y un token placeholder realista — ningún ejemplo referencia variables indefinidas o "YOUR_ENDPOINT" fuera del snippet
- El método de autenticación se indica claramente arriba
- Los valores enum se listan donde aplica
- Se documenta la paginación si el endpoint es un endpoint de lista
Anti-Patrones
- No documentes solo el camino feliz — cada endpoint debe tener códigos de error para al menos 400, 401/403, 404, 429 y 500
- No uses valores placeholder como "YOUR_ENDPOINT" o "INSERT_TOKEN" en ejemplos de código — usa placeholders realistas anclados a la URL base actual
- No omitas valores enum para campos con un conjunto fijo de valores aceptados — los enums no documentados causan bugs de integración
- No omitas documentación de paginación en endpoints de lista — los desarrolladores que se la pierdan construirán integraciones que silenciosamente pierdan datos
- No describa qué es un campo sin describir qué hace — "el ID" no es documentación; "el identificador único usado para recuperar o actualizar este recurso" lo es
Ejemplos de Uso
- "Documenta este endpoint de API: [pega especificación o descripción]"
- "Convierte esta colección de Postman en documentos para desarrolladores"
- "Escribe documentación de referencia de API para [endpoint]"
- "Escribe una guía para desarrolladores para nuestra API de [producto]"
版本历史
- a38bc30 当前 2026-07-05 11:07
