DEV Community

Cover image for Cómo Crear Skills de Código de Claude Automáticamente con Skill Creator
Roobia
Roobia

Posted on • Originally published at apidog.com

Cómo Crear Skills de Código de Claude Automáticamente con Skill Creator

TL;DR

Las Habilidades de Código de Claude son capacidades personalizadas que extienden la funcionalidad de Claude para flujos de trabajo específicos. El sistema Creador de Habilidades automatiza la creación de habilidades a través de un proceso estructurado: define el propósito de tu habilidad, redacta el archivo SKILL.md, crea casos de prueba, ejecuta evaluaciones con puntos de referencia cuantitativos y mejora iterativamente basándote en la retroalimentación.

Prueba Apidog hoy

Esta guía te muestra el proceso completo: anatomía de una habilidad, workflow de creación, evaluación y optimización para disparo fiable. Incluye ejemplos prácticos del repositorio oficial de habilidades de Anthropic.

💡
Si trabajas con habilidades relacionadas con API, Apidog se integra naturalmente. Prueba endpoints, valida respuestas y genera documentación, todo en un solo flujo de trabajo.

¿Qué son las Habilidades de Código de Claude?

Las Habilidades de Código de Claude son conjuntos de instrucciones especializadas que amplían las capacidades de Claude para dominios o flujos de trabajo concretos. Piensa en ellas como plugins personalizados en archivos markdown.

Arquitectura del sistema

Las habilidades siguen un sistema de carga de tres niveles:

  1. Metadatos (~100 palabras): nombre y descripción siempre disponibles en contexto.
  2. Cuerpo de SKILL.md (<500 líneas): instrucciones principales, cargadas al activar la habilidad.
  3. Recursos empaquetados (sin límite): scripts, referencias, activos bajo demanda. 
skill-name/
├── SKILL.md (obligatorio)
│   ├── YAML frontmatter (name, description)
│   └── Instrucciones Markdown
└── Recursos
    ├── scripts/    - Código ejecutable para tareas repetidas
    ├── references/ - Documentación cargada según necesidad
    └── assets/     - Plantillas, íconos, fuentes
Enter fullscreen mode Exit fullscreen mode

Activación de habilidades

Las habilidades se listan en available_skills de Claude con nombre y descripción. Claude decide si consulta una habilidad según su descripción.

Nota: Las habilidades solo se activan para tareas que Claude no puede manejar directamente. Flujos de trabajo complejos y de varios pasos se activan cuando la descripción coincide.

Ejemplos reales (Anthropic)

Habilidad Propósito Características Clave
skill-creator Crear nuevas habilidades Casos de prueba, benchmark, optimización de descripciones
mcp-builder Construir servidores MCP Plantillas Python/Node, evaluación, mejores prácticas
docx Generar documentos Word Scripts python-docx, plantillas, guía de estilo
pdf Extraer/manipular PDF Formularios, extracción de texto, docs de referencia
frontend-design Construir interfaces web Componentes, patrones Tailwind, comprobaciones de accesibilidad

Flujo de trabajo para crear habilidades

El ciclo estándar para crear una habilidad es:

  1. Capturar la intención: ¿Qué debe hacer la habilidad?
  2. Redactar SKILL.md: Escribe el archivo principal.
  3. Crear casos de prueba: Indica prompts realistas.
  4. Ejecutar evaluaciones: Corre con y sin habilidad.
  5. Revisar resultados: Feedback + métricas.
  6. Iterar: Mejora según hallazgos.
  7. Optimizar descripción: Maximiza la precisión de disparo.
  8. Empaquetar: Distribuye como archivo .skill.

A continuación, cada paso:

Paso 1: Capturar la intención

Define claramente el objetivo de la habilidad. Si ya haces este flujo, extrae el patrón de tus conversaciones previas.

Preguntas clave:

  1. ¿Qué debe permitir la habilidad? Sé específico.
  2. ¿Cuándo se debe activar? Frases, contextos.
  3. ¿Formato de salida? Archivos, código, informes, etc.
  4. ¿Requiere casos de prueba? Si la salida es verificable (código, datos), sí.

Ejemplo: Habilidad de prueba de API

Intent: Ayudar a developers a probar APIs REST sistemáticamente
Trigger: Cuando el usuario menciona pruebas de API, endpoints, REST, GraphQL, o validar respuestas
Output: Reportes de pruebas con estado pass/fail, comandos curl, comparación de respuestas
Test cases: Sí - la salida es verificable objetivamente
Enter fullscreen mode Exit fullscreen mode

Paso 2: Escribir el archivo SKILL.md

Cada habilidad parte de un SKILL.md con metadatos YAML e instrucciones Markdown.

Ejemplo básico:

---
name: api-tester
description: How to test REST APIs systematically. Use when users mention API testing, endpoints, REST, GraphQL, or want to validate API responses. Make sure to suggest this skill whenever testing is involved.
compatibility: Requires curl or HTTP client tools
---

# API Tester Skill

## Core Workflow

When testing an API, follow these steps:

1. **Understand the endpoint** - Read the spec or ask for the schema
2. **Design test cases** - Happy path, edge cases, error conditions
3. **Execute tests** - Use curl or Apidog for requests
4. **Validate responses** - Check status codes, headers, body structure
5. **Report results** - Summarize pass/fail with evidence

## Test Case Template

For each endpoint, test:

- Valid authentication with correct payload
- Valid authentication with missing required fields
- Invalid authentication (401 expected)
- Rate limiting behavior
- Response time under load

## Output Format

Always structure reports like this:

# API Test Report

## Summary
- Tests run: X
- Passed: Y
- Failed: Z

## Failed Tests

### Test Name
**Expected:** 200 OK
**Actual:** 400 Bad Request
**Response:** {...}

## Recommendations
...
Enter fullscreen mode Exit fullscreen mode

Buenas prácticas:

  • Mantén SKILL.md < 500 líneas. Documentación detallada en references/.
  • Explica el porqué de cada paso, no solo reglas.
  • Usa imperativos ("Valida siempre el código de estado primero").
  • Incluye ejemplos de entrada/salida.

Ejemplo estructura:

api-tester/
├── SKILL.md
└── references/
    ├── authentication.md
    ├── rate-limiting.md
    └── response-codes.md
Enter fullscreen mode Exit fullscreen mode

Paso 3: Crear casos de prueba

Crea entre 2 y 3 prompts realistas y específicos. Guarda los casos en evals/evals.json:

{
  "skill_name": "api-tester",
  "evals": [
    {
      "id": 1,
      "prompt": "Test the /users endpoint on api.example.com - it needs a Bearer token and returns a list of users with id, name, email fields",
      "expected_output": "Test report with at least 5 test cases including auth failure, success, and pagination tests",
      "files": []
    },
    {
      "id": 2,
      "prompt": "I need to verify our new POST /orders endpoint handles invalid quantities correctly",
      "expected_output": "Test cases that send negative, zero, and non-numeric quantities with appropriate error responses",
      "files": ["openapi.yaml"]
    }
  ]
}
Enter fullscreen mode Exit fullscreen mode

Características de un buen prompt de prueba:

  • URL específica
  • Escenario concreto
  • Comportamiento esperado
  • Contexto real

Comparte los prompts con el usuario antes de ejecutar.

Paso 4: Ejecutar evaluaciones

Usa Skill Creator para ejecutar cada caso de prueba dos veces: con y sin la habilidad.

Estructura de workspace:

api-tester-workspace/
├── iteration-1/
│   ├── eval-0-auth-failure/
│   │   ├── with_skill/outputs/
│   │   ├── without_skill/outputs/
│   │   └── eval_metadata.json
│   ├── benchmark.json
│   └── benchmark.md
├── iteration-2/
└── feedback.json
Enter fullscreen mode Exit fullscreen mode

Ejemplo de ejecución:

  • Con habilidad: 
  Execute this task:
  - Skill path: /path/to/api-tester
  - Task: Test the /users endpoint on api.example.com
  - Input files: none
  - Save outputs to: api-tester-workspace/iteration-1/eval-0/with_skill/outputs/
Enter fullscreen mode Exit fullscreen mode
  • Sin habilidad: 
  Execute this task:
  - Skill path: (none)
  - Task: Test the /users endpoint on api.example.com
  - Input files: none
  - Save outputs to: api-tester-workspace/iteration-1/eval-0/without_skill/outputs/
Enter fullscreen mode Exit fullscreen mode

Captura datos de tiempo:

Guarda el resultado en timing.json por cada ejecución.

{
  "total_tokens": 84852,
  "duration_ms": 23332,
  "total_duration_seconds": 23.3
}
Enter fullscreen mode Exit fullscreen mode

Paso 5: Redactar afirmaciones

Mientras se completan las ejecuciones, redacta afirmaciones cuantitativas (checks objetivos) para calificar el resultado.

Ejemplo:

{
  "assertions": [
    {
      "name": "includes_auth_failure_test",
      "description": "Test report includes at least one authentication failure test case",
      "type": "contains",
      "value": "401"
    },
    {
      "name": "includes_success_test",
      "description": "Test report includes at least one successful request test",
      "type": "contains",
      "value": "200"
    },
    {
      "name": "includes_curl_commands",
      "description": "Each test case includes executable curl commands",
      "type": "regex",
      "value": "curl -"
    },
    {
      "name": "includes_response_validation",
      "description": "Report validates response structure against schema",
      "type": "contains",
      "value": "schema"
    }
  ]
}
Enter fullscreen mode Exit fullscreen mode

Actualiza eval_metadata.json y evals/evals.json con las afirmaciones.

Paso 6: Calificar y agregar

Al finalizar las ejecuciones:

  • Genera un subagente calificador que evalúa cada afirmación contra la salida.
  • Guarda los resultados en grading.json: 
{
  "eval_id": 0,
  "grading": [
    {
      "text": "includes_auth_failure_test",
      "passed": true,
      "evidence": "Found 401 status code in test case 3"
    },
    {
      "text": "includes_curl_commands",
      "passed": true,
      "evidence": "Found 'curl -X POST' in test case 1"
    }
  ]
}
Enter fullscreen mode Exit fullscreen mode

Usa los campos exactos: text, passed, evidence.

Agrega benchmark:

Desde el directorio skill-creator:

python -m scripts.aggregate_benchmark api-tester-workspace/iteration-1 --skill-name api-tester
Enter fullscreen mode Exit fullscreen mode

Lee los resultados, busca afirmaciones poco discriminantes, variabilidad alta o coste excesivo de tokens/tiempo.

Paso 7: Lanzar el visor de evaluación

El visor muestra outputs y métricas en navegador.

Generar visor:

nohup python /path/to/skill-creator/eval-viewer/generate_review.py \
  api-tester-workspace/iteration-1 \
  --skill-name "api-tester" \
  --benchmark api-tester-workspace/iteration-1/benchmark.json \
  > /dev/null 2>&1 &
VIEWER_PID=$!
Enter fullscreen mode Exit fullscreen mode

Para iteraciones siguientes:

--previous-workspace api-tester-workspace/iteration-1
Enter fullscreen mode Exit fullscreen mode

Entornos sin navegador:

Usa --static para HTML estático:

--static /path/to/output/review.html
Enter fullscreen mode Exit fullscreen mode

El feedback se descarga como feedback.json al enviar revisiones.

Paso 8: Leer retroalimentación e iterar

Cuando el usuario termina, lee feedback.json:

{
  "reviews": [
    {
      "run_id": "eval-0-with_skill",
      "feedback": "the chart is missing axis labels",
      "timestamp": "2026-03-23T10:30:00Z"
    }
  ],
  "status": "complete"
}
Enter fullscreen mode Exit fullscreen mode

Enfócate en mejorar los casos con feedback concreto.

Bucle de iteración:

  1. Mejora la habilidad.
  2. Re-ejecuta casos en iteration-<N+1>/.
  3. Lanza visor con --previous-workspace.
  4. Espera feedback.
  5. Repite hasta que todo esté OK o no haya mejoras.

Al terminar:

kill $VIEWER_PID 2>/dev/null
Enter fullscreen mode Exit fullscreen mode

Paso 9: Optimizar la descripción

El campo description en SKILL.md es clave para la activación.

Generar queries de evaluación:

Crea 20 queries, mezcla de true/false triggers.

[
  {
    "query": "ok so my boss just sent me this xlsx file (its in my downloads, called something like 'Q4 sales final FINAL v2.xlsx') and she wants me to add a column that shows the profit margin as a percentage. The revenue is in column C and costs are in column D i think",
    "should_trigger": true
  },
  ...
]
Enter fullscreen mode Exit fullscreen mode

Revisa y edita con el usuario:

Usa plantilla HTML para que el usuario ajuste queries y exporte el set final.

Ejecuta bucle de optimización:

python -m scripts.run_loop \
  --eval-set /path/to/trigger-eval.json \
  --skill-path /path/to/api-tester \
  --model claude-sonnet-4-6 \
  --max-iterations 5 \
  --verbose
Enter fullscreen mode Exit fullscreen mode

Toma la best_description y actualiza el SKILL.md.

Antes:

description: How to test REST APIs systematically
Enter fullscreen mode Exit fullscreen mode

Después:

description: How to test REST APIs systematically. Use when users mention API testing, endpoints, REST, GraphQL, or want to validate API responses. Make sure to suggest this skill whenever testing is involved, even if they don't explicitly mention 'testing'.
Enter fullscreen mode Exit fullscreen mode

Paso 10: Empaquetar y distribuir

Empaqueta la habilidad:

python -m scripts.package_skill /path/to/api-tester
Enter fullscreen mode Exit fullscreen mode

Esto genera un .skill para instalar.

Instalación:

Coloca el .skill en el directorio de habilidades o usa el comando de instalación de Claude Code.

Errores comunes al crear habilidades

1. Descripción vaga

Malo:

description: A skill for working with APIs
Enter fullscreen mode Exit fullscreen mode

Bueno:

description: How to test REST APIs systematically. Use when users mention API testing, endpoints, REST, GraphQL, or want to validate API responses. Make sure to suggest this skill whenever testing is involved, even if they don't explicitly mention 'testing'.
Enter fullscreen mode Exit fullscreen mode

2. Instrucciones demasiado restrictivas

Malo:

ALWAYS use this exact format. NEVER deviate. MUST include these sections.
Enter fullscreen mode Exit fullscreen mode

Bueno:

Use this format because it ensures stakeholders can quickly find the information they need. If your audience has different needs, adapt the structure accordingly.
Enter fullscreen mode Exit fullscreen mode

3. Omitir casos de prueba

Incluso para habilidades subjetivas, ejecuta 2-3 ejemplos para verificar calidad.

4. Ignorar datos de tiempo

No optimizar tiempos vuelve las habilidades insostenibles. Captura y ajusta.

5. No agrupar scripts repetidos

Si cada ejecución genera scripts auxiliares similares, agrúpalos en scripts/.

Ejemplos de habilidades del mundo real

Habilidad MCP Builder

Para construir servidores MCP (Model Context Protocol).

Características:

  • Plantillas Python y Node.js
  • Framework de evaluación MCP
  • Documentos de mejores prácticas

Estructura:

mcp-builder/
├── SKILL.md
├── reference/
│   ├── mcp_best_practices.md
│   ├── python_mcp_server.md
│   └── node_mcp_server.md
└── evaluation/
    └── evaluation.md
Enter fullscreen mode Exit fullscreen mode

Habilidad Docx

Generación programática de documentos Word.

  • Scripts python-docx empaquetados
  • Sistema de plantillas
  • Guía de estilo

Workflow:

  1. Entender requisitos
  2. Seleccionar/crear plantilla
  3. Generar con script python-docx
  4. Validar estructura

Habilidad Frontend Design

Construcción de interfaces web modernas.

  • Componentes reutilizables
  • Patrones Tailwind CSS
  • Checks de accesibilidad

Documentación detallada en references/.

Probando tu habilidad con Apidog

Si tu habilidad es de API, Apidog se integra perfectamente.

Apidog

Ejemplo: Integración en habilidad de prueba de API 

## Ejecución de Pruebas de API

Usa Apidog para pruebas sistemáticas:

1. Importa la especificación OpenAPI en Apidog
2. Genera casos de prueba a partir de la especificación
3. Ejecuta pruebas y exporta los resultados como JSON
4. Valida las respuestas contra los esquemas esperados

Para afirmaciones personalizadas, utiliza la función de scripting de Apidog.
Enter fullscreen mode Exit fullscreen mode

Agrupar scripts de Apidog 

api-tester/
├── SKILL.md
└── scripts/
    ├── run-apidog-tests.py
    └── generate-report.py
Enter fullscreen mode Exit fullscreen mode

Así evitas duplicar lógica en futuras ejecuciones.

Conclusión

Las Habilidades de Código de Claude amplían Claude para tus flujos de trabajo específicos. El proceso recomendado:

  1. Captura la intención
  2. Redacta SKILL.md con instrucciones claras y ejemplos
  3. Crea casos de prueba realistas
  4. Ejecuta evaluaciones paralelas
  5. Revisa resultados (feedback + benchmark)
  6. Itera según los hallazgos
  7. Optimiza la descripción
  8. Empaqueta y distribuye el .skill

Preguntas Frecuentes

¿Cuánto tiempo lleva crear una habilidad?

Simples: 15-30 minutos. Complejas (con scripts y referencias): 2-3 horas, incluyendo iteraciones.

¿Necesito casos de prueba para todas las habilidades?

No. Solo para salidas verificables objetivamente (código, datos). Habilidades subjetivas se evalúan cualitativamente.

¿Qué hago si mi habilidad no se activa de forma fiable?

Optimiza la descripción. Incluye frases/contexts específicos. Ejecuta el bucle de optimización con 20 queries.

¿Cómo comparto habilidades con mi equipo?

Empaqueta con python -m scripts.package_skill <path>, distribuye el .skill y colócalo en el directorio de habilidades.

¿Pueden las habilidades llamar a APIs externas?

Sí. Empaqueta scripts API y usa variables de entorno para claves.

¿Límite de tamaño para habilidades?

No estricto, pero SKILL.md < 500 líneas. Detalles en archivos separados.

¿Cómo actualizo una habilidad existente?

Copia la habilidad a una ubicación editable, modifica, reempaqueta y conserva el nombre. No añadas sufijos de versión salvo variantes distintas.

Top comments (0)