Si alguna vez ha heredado documentación incompleta, inconsistente y desactualizada, conoce el problema: los equipos crean documentos con buenas intenciones, pero sin una revisión rigurosa, la claridad se erosiona. Los parámetros de la API quedan indocumentados. Las respuestas de error carecen de orientación. Los ejemplos se rompen silenciosamente. La terminología varía entre archivos.
Las Habilidades de Claude Code resuelven esto sistemáticamente. Estos flujos de trabajo impulsados por IA revisan todo su repositorio de documentación, identifican brechas e inconsistencias y aplican correcciones directamente. Usted describe lo que necesita ser revisado, y Claude genera una auditoría estructurada, aplica mejoras y valida la integridad, todo desde su terminal.
La documentación técnica abarca especificaciones de API, guías de usuario, guías de implementación y notas de lanzamiento. Claude Code automatiza la revisión de todo ello. Para la documentación de API específicamente, combínelo con Apidog para la validación visual y la puntuación de integridad.
Comprendiendo las Habilidades de Claude Code para la Documentación
¿Qué son las Habilidades de Documentación?
Las Habilidades de Claude Code son flujos de trabajo de IA personalizados y reutilizables que amplían las capacidades de documentación de Claude Code. Piense en ellos como auditores de documentación inteligentes que pueden:
- Leer todo su repositorio de documentación y comprender el contexto
- Cotejar las especificaciones con las implementaciones y guías
- Identificar secciones faltantes, lenguaje poco claro e inconsistencias
- Sugerir mejoras específicas con ubicaciones de archivo y números de línea
- Aplicar correcciones directamente a sus archivos y validar los cambios
A diferencia de los linters tradicionales que verifican la sintaxis, las habilidades aprovechan el razonamiento de Claude para comprender problemas semánticos: descripciones vagas, documentación de errores faltante, ejemplos inconsistentes.
Cómo Funcionan las Habilidades
Las habilidades operan a través de varios mecanismos:
1. Comandos Invocables por el Usuario
# Ejecutar una habilidad con un comando de barra
/review-docs --completeness
/check-consistency --terminology
/validate-api-specs
/update-broken-examples
2. Herramientas Permitidas
Las habilidades especifican qué herramientas pueden usar:
Bash: Ejecutar comandos de validaciónRead,Write,Edit: Administrar archivos de documentaciónGlob,Grep: Buscar en la documentaciónWebFetch: Recuperar referencias externasTask: Generar subtareas para revisiones complejas
3. Archivos de Planificación
Las habilidades mantienen el estado utilizando archivos Markdown para rastrear el progreso de la revisión, los problemas identificados y las correcciones aplicadas.
Por Qué las Habilidades Sobresalen en la Revisión de Documentación
La revisión de documentación tradicional es manual e inconsistente. Las habilidades aportan inteligencia y escala:
- Comprensión Holística: Revisa todos los archivos, captura patrones entre archivos
- Estándares Consistentes: Aplica los mismos criterios de calidad a cada archivo
- Sugerencias Contextuales: Comprende por qué algo está mal, no solo que lo está
- Automatización: Puede revisar continuamente a medida que la documentación evoluciona
- Velocidad: Analiza cientos de páginas en minutos versus horas de revisión manual
Capacidades Clave de Revisión de Documentación
1. Análisis de Integridad
Prompt: "Auditar la documentación de la API para verificar su integridad. Verificar cada endpoint en busca de: parámetros, ejemplos de solicitud, todas las respuestas de error y limitación de velocidad."
Claude genera:
Faltante del endpoint POST /users:
- [ ] Descripciones de parámetros del cuerpo de la solicitud
- [ ] Documentación de respuestas de error (400, 401, 409)
- [ ] Información de limitación de velocidad
- [ ] Requisitos de seguridad/autenticación
2. Detección de Consistencia
Prompt: "Revisar /docs/ en busca de consistencia terminológica. Marcar cualquier término que aparezca varias veces con diferentes significados."
Claude identifica:
Terminología inconsistente encontrada:
- "API key" vs "access token" vs "auth token" (usar uno)
- "endpoint" vs "route" vs "method" (usar uno)
- "user object" vs "user resource" (usar uno)
3. Validación de Referencias Cruzadas
Prompt: "Comparar la especificación OpenAPI en /api/openapi.yaml con la documentación en /docs/api/. Marcar cualquier endpoint en el código no documentado o documentado pero no presente en el código."
Claude detecta:
Discrepancias encontradas:
- POST /api/webhooks documentado pero no en openapi.yaml
- PATCH /api/users existe en el código pero falta en la documentación
- El esquema de respuesta cambió pero el ejemplo no se actualizó
4. Evaluación de Claridad
Prompt: "Revisar para mayor claridad. Marcar descripciones vagas, términos indefinidos e instrucciones ambiguas."
Claude identifica:
Problemas de claridad:
- Línea 45: "Configurar los valores apropiados" - ¿qué valores?
- Línea 120: "Objeto de usuario" utilizado sin definición de esquema
- Línea 200: "Campos obligatorios" - ¿cuáles?
5. Validación de Ejemplos
Prompt: "Revisar todos los ejemplos de código. Probarlos contra el esquema actual de la API. Marcar ejemplos rotos o desactualizados."
Claude actualiza:
Ejemplos actualizados:
- Ejemplo de curl: El formato de respuesta cambió, payload actualizado
- Ejemplo de Python: Usando parámetro obsoleto, corregido
- Ejemplo de JavaScript: Faltaba manejo de errores, añadido
Anatomía de las Habilidades de Documentación
Estructura de Directorios
Las habilidades de documentación residen en .claude/skills/ con esta disposición:
.claude/
├── skills/
│ ├── docs-completeness/
│ │ ├── SKILL.md # Manifiesto de la habilidad
│ │ ├── planning.md # Progreso de la revisión
│ │ └── criteria.md # Lista de verificación de calidad
│ ├── api-validation/
│ │ ├── SKILL.md
│ │ └── schemas/ # Esquemas de API
│ └── consistency-check/
│ └── SKILL.md
└── skills.md # Índice de todas las habilidades
El Manifiesto SKILL.md
Cada habilidad de documentación comienza con un preámbulo YAML:
---
name: docs-completeness
version: "1.0.0"
description: Revisa la documentación en busca de integridad y claridad
user-invocable: true
allowed-tools:
- Read
- Write
- Grep
- Glob
- Edit
hooks:
SessionStart:
- matcher: command
command: "echo '[Revisión de Docs] Iniciando auditoría de documentación...'"
Stop:
- matcher: command
command: "echo '[Revisión de Docs] Auditoría completada. Revise los hallazgos anteriores.'"
---
# Habilidad de Integridad de Documentación
Revisa la documentación técnica para verificar su integridad y claridad.
## Uso
```bash
/docs-completeness # Auditoría completa del repositorio
/docs-completeness --api-only # Solo documentación de API
/docs-completeness --section api/endpoints.md # Archivo específico
Instrucciones para Claude
Cuando se invoca:
- Detección de alcance → Determinar archivos objetivo o repositorio completo
- Análisis de integridad → Verificar cada sección con la lista de verificación
- Recopilación de problemas → Recopilar todos los problemas con sus ubicaciones
- Priorización → Ordenar por impacto (faltante vs. poco claro vs. inconsistente)
- Generación de informes → Generar hallazgos estructurados
- Sugerencias de corrección → Ofrecer mejoras específicas
- Validación → Verificar las correcciones antes de aplicarlas
Creando Su Primera Habilidad de Documentación
Sumérjase en la práctica: construiremos una herramienta útil para auditar la documentación de la API en busca de deficiencias, asegurando que sea completa y esté lista para los desarrolladores. Piense en ella como su 'ejecutor' personal de documentación.
Paso 1: Configurar la Carpeta de la Habilidad
Inicialice la estructura con un simple comando: las habilidades de Claude residen en un lugar dedicado para una fácil detección.
Bash
mkdir -p .claude/skills/api-docs-reviewPaso 2: Escribir el Manifiesto de la Habilidad
Crear .claude/skills/api-docs-review/SKILL.md:
---
name: api-docs-review
version: "1.0.0"
description: Revisa la documentación de la API para verificar su integridad
user-invocable: true
allowed-tools:
- Read
- Write
- Grep
- Edit
---
# Habilidad de Revisión de Documentación de API
Audita la documentación de la API para verificar su integridad, claridad y precisión.
## Criterios de Revisión
Cada endpoint debe tener:
**Información Básica**
* Descripción clara de lo que hace el endpoint
* Método HTTP y ruta
* Requisitos de autenticación
**Documentación de Solicitudes**
* Todos los parámetros de ruta con tipos y descripciones
* Todos los parámetros de consulta con valores predeterminados y restricciones
* Esquema del cuerpo de la solicitud (para POST/PUT/PATCH)
* Requisitos de encabezado Content-Type
* Ejemplo de solicitud (curl o específico del lenguaje)
**Documentación de Respuestas**
* Respuesta de éxito (200/201) con esquema y ejemplo
* Todas las respuestas de error (400, 401, 403, 404, 409, 429, 500) con ejemplos
* Información de limitación de velocidad
* Encabezados de respuesta (si son relevantes)
**Adicional**
* Endpoints o guías relacionadas
* Historial de versiones si aplica
* Advertencias de obsolescencia (si está obsoleto)
## Instrucciones
Cuando se invoca:
1. **Escanear archivos de endpoints** en /docs/api/
2. **Verificar cada endpoint** según los criterios de revisión
3. **Registrar elementos faltantes** con referencias específicas de archivo/línea
4. **Identificar problemas de claridad** (descripciones vagas, términos indefinidos)
5. **Señalar problemas de consistencia** (deriva terminológica, diferencias de formato)
6. **Generar lista de verificación** de las correcciones necesarias
7. **Ofrecer aplicar correcciones** con ejemplos
Formato del informe:
ENDPOINT: POST /api/users File: docs/api/users.md Status: 65% Completo
Faltante:
- [ ] Documentación de respuestas de error (400, 401, 409)
- [ ] Información de limitación de velocidad
- [ ] Definición del esquema del cuerpo de la solicitud
Problemas:
- Línea 45: "objeto de usuario" indefinido - añadir enlace al esquema
- Línea 60: Ejemplo obsoleto - el formato de respuesta ha cambiado
Correcciones disponibles: Sí (preguntar para aplicar)
Paso 3: Registrar la Habilidad
Añadir a .claude/skills.md:
# Habilidades de Documentación Disponibles
## Documentación de API
### /api-docs-review
Audita la documentación de la API para verificar su integridad según criterios estándar.
- **Versión**: 1.0.0
- **Uso**: `/api-docs-review [--file PATH] [--endpoint NAME]`
- **Cuándo usar**: Antes del lanzamiento de la API, después de cambios en el código
- **Tiempo**: 5-10 minutos para una API de tamaño medio
Paso 4: Probar la Habilidad
# En Claude Code
/api-docs-review
Claude ahora auditará su documentación de API sistemáticamente.
Patrones Avanzados de Documentación
Patrón 1: Seguimiento de Documentación Versionada
Las habilidades pueden rastrear la calidad de la documentación entre versiones:
## Historial de Versiones
### v2.0.0 [2026-01-22]
Integridad: 95% ✅
- Todos los endpoints documentados
- Respuestas de error completas
- Ejemplos actualizados
- Endpoints /v1 obsoletos marcados
### v1.0.0 [2025-12-01]
Integridad: 70%
- Documentación de errores faltante
- Ejemplos desactualizados
- Sin advertencias de obsolescencia
Claude detecta mejoras con el tiempo.
Patrón 2: Validación de Especificaciones de API Contra el Código
Las habilidades pueden validar que las especificaciones OpenAPI coincidan con la implementación:
## Validación de Especificaciones
Comparar /api/openapi.yaml con el código:
1. **Escanear implementación** para todas las rutas
2. **Verificar especificación OpenAPI** para cada ruta
3. **Marcar endpoints faltantes**
4. **Verificar que los parámetros** coincidan con la implementación
5. **Actualizar ejemplos** para que coincidan con el esquema actual
Resultado: Especificación 100% sincronizada con el código
Automatizando con CI/CD
Pipeline de Validación de Documentación
Configure verificaciones automatizadas en cada actualización de documentación:
# .github/workflows/docs-check.yml
name: Verificación de Documentación
on:
push:
paths:
- 'docs/**'
- 'api/openapi.yaml'
pull_request:
paths:
- 'docs/**'
- 'api/openapi.yaml'
jobs:
validate-docs:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
with:
node-version: '20'
cache: 'npm'
- name: Instalar Apidog CLI
run: npm install -g apidog-cli
- name: Validar Especificación OpenAPI
run: |
apidog lint api/openapi.yaml
apidog check-completeness api/openapi.yaml --min-score 85
- name: Verificar enlaces rotos
run: |
npm install -g markdown-link-check
find docs -name "*.md" -exec markdown-link-check {} \;
- name: Verificar que los ejemplos sean válidos
run: |
# Probar que los ejemplos de curl funcionen
bash scripts/test-curl-examples.sh
- name: Comentar en la PR
if: failure()
uses: actions/github-script@v7
with:
script: |
github.rest.issues.createComment({
issue_number: context.issue.number,
owner: context.repo.owner,
repo: context.repo.repo,
body: '❌ Falló la validación de la documentación. Revise los registros del flujo de trabajo.'
})
Escenario de la Vida Real: Integridad de la Documentación de API
Auditemos un conjunto de documentación de API realista para verificar su integridad y aplicar mejoras.
El Escenario
Tiene documentación de API REST de 6 meses de antigüedad. Está parcialmente completa, pero le falta documentación de errores, es poco clara en algunos puntos y tiene ejemplos desactualizados.
La Auditoría
Prompt para Claude: "Auditar la documentación en /docs/api/. Para cada endpoint, verificar: descripción, parámetros de solicitud, ejemplo de respuesta y todas las respuestas de error. Priorizar las correcciones por impacto."
RESULTADOS DE LA AUDITORÍA
=============
CRÍTICO (Documentación de errores faltante):
├── POST /api/users - Faltan respuestas de error 400, 401, 409
├── POST /api/auth/login - Falta respuesta 429 (límite de velocidad)
└── DELETE /api/resources/{id} - Falta respuesta 403 (prohibido)
ALTO (Problemas de claridad):
├── users.md:45 - "objeto de usuario" indefinido
├── auth.md:60 - "Establecer caducidad con valor apropiado" - demasiado vago
└── resources.md:30 - Falta descripción del formato del cursor de paginación
MEDIO (Ejemplos desactualizados):
├── products.md:120 - El ejemplo de cURL devuelve formato antiguo
├── orders.md:80 - El ejemplo del SDK de Python utiliza un parámetro obsoleto
└── webhooks.md:60 - Al ejemplo de Node.js le falta manejo de errores
CONSISTENCIA:
├── "API key" vs "access token" - 5 instancias inconsistentes
├── Formato del cuerpo de la solicitud - 3 estilos diferentes entre endpoints
└── Esquema de respuesta de error - 2 variaciones en lugar de 1
Correcciones prioritarias: 15 en total
Esfuerzo estimado: 2-3 horas manuales, 15 minutos con Claude Code
Las Mejoras
Aplicando correcciones sistemáticamente:
Antes - POST /api/users (Incompleto):
## Crear Usuario
POST /api/users
Crea un nuevo usuario.
**Parámetros:**
- name: Nombre del usuario
- email: Correo electrónico del usuario
**Respuesta:**
```json
{
"id": "usr_123",
"name": "Alice",
"email": "alice@example.com"
}
**Después - POST /api/users (Completo):**
```markdown
## Crear Usuario
`POST /api/users`
Crea una nueva cuenta de usuario con los detalles proporcionados. El correo electrónico debe ser único.
### Autenticación
Requiere clave API en el encabezado `Authorization`: `Bearer YOUR_API_KEY`
### Parámetros de Solicitud
| Parámetro | Tipo | Requerido | Descripción |
|-----------|------|----------|-------------|
| `name` | string | Sí | Nombre completo (2-100 caracteres) |
| `email` | string | Sí | Correo electrónico válido (debe ser único) |
| `role` | string | No | Rol: `admin`, `developer`, `viewer`. Predeterminado: `viewer` |
### Ejemplo de Solicitud
```bash
curl -X POST https://api.example.com/v1/users \
-H "Authorization: Bearer sk_live_abc123" \
-H "Content-Type: application/json" \
-d '{
"name": "Alice Smith",
"email": "alice@example.com",
"role": "developer"
}'
Respuesta (201 Creado)
{
"id": "usr_abc123",
"name": "Alice Smith",
"email": "alice@example.com",
"role": "developer",
"created_at": "2026-01-22T10:30:00Z"
}
Respuestas de Error
400 Solicitud Incorrecta - Entrada inválida
{
"error": "validation_error",
"message": "Invalid email format",
"field": "email",
"request_id": "req_xyz789"
}
401 No Autorizado - Clave API faltante/inválida
{
"error": "unauthorized",
"message": "Invalid API key",
"request_id": "req_xyz789"
}
409 Conflicto - El correo electrónico ya existe
{
"error": "conflict",
"message": "User with this email already exists",
"request_id": "req_xyz789"
}
429 Demasiadas Solicitudes - Límite de velocidad alcanzado
{
"error": "rate_limited",
"message": "Too many requests. Try again in 60 seconds.",
"retry_after": 60,
"request_id": "req_xyz789"
}
Limitación de Velocidad
100 solicitudes por minuto por clave API. Ver Límites de Velocidad.
**Mejoras aplicadas:**
- Se agregaron requisitos de autenticación
- Se documentaron todos los parámetros con restricciones
- Respuestas de éxito completas + todas las respuestas de error
- Ejemplo de cURL listo para producción
- Información de limitación de velocidad
- Formato consistente
Integrando Claude con Apidog para una Documentación de API Superior
💡 Consejo Profesional: Aproveche Claude para revisiones perspicaces de documentos narrativos, mientras que Apidog asegura que sus especificaciones de API sean sólidas y rellena automáticamente los huecos con ejemplos prácticos.
Sugerencia de Prompt para Claude:"Examine /docs/api/ para la claridad y el compromiso general. A continuación, verifique la integridad del archivo /api/openapi.yaml utilizando Apidog. Resalte cualquier inconsistencia o elemento faltante, para que pueda abordarlos directamente en Apidog antes de continuar."
Bash
# Paso 1: Revisión Inicial de Prosa a través de Claude
> /docs-completeness # Genera sugerencias para un lenguaje y una estructura más claros
# Paso 2: Validación de Especificaciones de API en Apidog
apidog check-completeness api/openapi.yaml # Señala problemas como esquemas incompletos o respuestas faltantes
# Paso 3: Generar Contenido Automáticamente con la IA de Apidog
# (A través de la UI de Apidog: Configuración → IA → Generar automáticamente descripciones, ejemplos y resúmenes)
# Paso 4: Verificación Final de Armonía con Claude
> /consistency-check # Asegura que la documentación y las especificaciones estén perfectamente alineadasEsto crea un flujo de trabajo donde Apidog maneja la validación estructurada de especificaciones y Claude Code se encarga de la calidad de la prosa.
Mejores Prácticas para la Revisión de Documentación
Conozca a Su Audiencia
Adapte la profundidad de la documentación a los lectores:
| Audiencia | Estilo | Ejemplo |
|---|---|---|
| Desarrolladores | Ejemplos de código en varios lenguajes | cURL, Python, JS |
| DevOps | Pasos de despliegue, configuración | Ejemplos de YAML de Kubernetes |
| Equipos de producto | Flujos de trabajo de alto nivel, diagramas | Flujos de características con capturas de pantalla |
| Soporte | Resolución de problemas, problemas comunes | "Error 429 significa..." |
Priorice la Claridad
Escriba en voz activa, estructure para escanear:
❌ Antes: "La solicitud se envía vía POST. La respuesta contendrá al usuario."
✅ Después: "Envíe una solicitud POST para crear un usuario. La API devuelve el nuevo usuario."
Incluya Siempre Ejemplos
Los conceptos abstractos necesitan anclaje. Cada endpoint de API necesita:
# ✅ Listo para copiar y pegar
curl -X GET https://api.example.com/v1/users/usr_123 \
-H "Authorization: Bearer YOUR_API_KEY"
Errores Comunes
| Fallo | Solución |
|---|---|
| Sobrecarga de jerga | Definir términos en el primer uso |
| Ejemplos desactualizados | Probar en CI/CD |
| Documentación de errores faltante | Documentar todos los códigos de error |
| Formato inconsistente | Usar plantillas |
| Enlaces rotos | Verificar en CI/CD |
Conclusión
Las Habilidades de Claude Code transforman la revisión de la documentación técnica de un proceso manual tedioso en un flujo de trabajo inteligente y automatizado. Usted describe lo que necesita ser revisado, y Claude audita todo su repositorio de documentación, identifica brechas e inconsistencias, y aplica correcciones, todo mientras mantiene los estándares de calidad.
Combinado con Apidog para la validación de especificaciones de API, logrará una cobertura completa de la documentación.