Uso de agentes de IA para automatizar tareas repetitivas en proyectos

La forma más rápida de dejar de explicarle tu proyecto a un agente de IA una y otra vez es capturar el procedimiento una sola vez como una Claude Code skill — un directorio con un archivo SKILL.md, confirmado en tu repositorio, que el agente lee en lugar de redescubrir cómo ejecutar, inicializar o desplegar tu aplicación.

Cualquiera que haya visto a un agente pasar diez minutos redescubriendo que la aplicación no arranca sin una base de datos inicializada y un archivo de entorno copiado conoce esa sensación. Explicaste esos pasos exactos la semana pasada, y la anterior. Este artículo muestra el patrón concreto: en qué se diferencia una skill de un script npm, dónde vive una skill con alcance de proyecto, y un ejemplo funcional que pone tu aplicación en marcha desde un checkout limpio y la verifica. La tesis es simple: deja de escribir scripts de un solo uso que olvidarás, y entrega una skill de agente con alcance de proyecto que todo tu equipo y el agente comparten.

El costo real de los scripts npm olvidables y la documentación de configuración obsoleta

La parte costosa de un proceso de configuración desactualizado no es el comando roto: es que un humano o el agente vuelve a derivar el procedimiento cada vez. Un package.json acumula entradas crípticas (predev:seed, db:reset:ci, start:tunnel) cuyo orden y precondiciones viven únicamente en la cabeza de un ingeniero. La sección “Getting Started” del README pierde sincronía en el momento en que alguien añade una variable de entorno y olvida documentarla. Los nuevos colaboradores adivinan; el agente de IA también adivina, y ambos adivinan de manera diferente.

Una skill soluciona esto registrando el procedimiento donde el agente ya busca. La documentación oficial de Claude Code define con precisión el momento indicado para crear una: crea una skill cuando sigues pegando las mismas instrucciones, listas de verificación o procedimientos de varios pasos en el chat, o cuando una sección de CLAUDE.md ha crecido hasta convertirse en un procedimiento en lugar de un hecho.

¿Cuál es la diferencia entre un script y una skill?

Usa un script para los pasos que nunca deben variar y una skill para los pasos que requieren interpretación. Un script npm ejecuta comandos fijos en una secuencia predeterminada; una skill utiliza el modelo para leer el contexto, manejar la variabilidad y decidir qué hacer a continuación, y luego delega las partes deterministas de vuelta al código. Los dos son complementos, no competidores.

El equipo de ingeniería de Anthropic defiende mantener el trabajo determinista en el código: ciertas operaciones son más adecuadas para la ejecución de código tradicional, porque ordenar una lista mediante la generación de tokens es más lento y menos confiable que ejecutar un algoritmo de ordenamiento, y muchos flujos de trabajo necesitan la repetibilidad que solo el código proporciona. De manera crucial, un script incluido en la skill es económico en cuanto al contexto: los agentes con un sistema de archivos y herramientas de ejecución de código no necesitan leer la totalidad de una skill en su ventana de contexto, lo que significa que la cantidad de contexto que puede empaquetarse en una skill es efectivamente ilimitada.

¿Qué es una Claude Code skill y dónde vive?

Una Claude Code skill es un directorio que contiene un archivo SKILL.md cuyo frontmatter YAML le indica al agente cuándo usarla. Según la descripción general de Agent Skills, cada skill empaqueta instrucciones, metadatos y recursos opcionales (scripts, plantillas) que Claude usa automáticamente cuando son relevantes. Este es el modelo mental correcto: una skill es un directorio, no un simple archivo de comandos.

La ubicación determina el alcance. Las skills de proyecto se cargan desde .claude/skills/ en tu directorio de inicio y en los directorios padre hasta la raíz del repositorio, de modo que un agente que trabaje en cualquier parte del proyecto verá la skill como disponible, y se carga automáticamente cuando la solicitud coincide con su descripción. Las skills personales viven en ~/.claude/skills/. Para Claude Code específicamente, solo se recomienda description; name es opcional y toma por defecto el nombre del directorio, que también es lo que escribes después de /.

Los componentes básicos son fáciles de confundir, así que elige deliberadamente:

• Skill: un directorio + SKILL.md, con scripts opcionales incluidos. Descubierta automáticamente por su description e invocable con /nombre-de-skill. También funciona en Claude.ai y Claude Desktop, por lo que un equipo puede compartirla más allá de la terminal.
• Slash command: históricamente un único archivo .md en .claude/commands/. Los comandos personalizados se han fusionado con las skills: un archivo en .claude/commands/deploy.md y una skill en .claude/skills/deploy/SKILL.md crean ambos /deploy y funcionan de la misma manera. Ante una colisión de nombres, la skill tiene prioridad.
• Subagent: un archivo .md en .claude/agents/ que se ejecuta en su propia ventana de contexto y devuelve un resultado destilado. Recurre a él cuando una tarea es suficientemente intensiva en lectura como para contaminar tu hilo principal.

Ejemplo práctico: capturar “ejecutar desde un checkout limpio y verificar”

Convierte tu ritual de configuración en una skill confirmada en el repositorio. Crea .claude/skills/run-app/SKILL.md con una description lo suficientemente específica para que el agente la identifique, la salida de comandos en vivo inyectada al inicio, y pasos numerados:

---
name: run-app
description: Get this app running from a clean checkout and verify it boots. Use when setting up the project, onboarding, or checking the app still starts after a change.
allowed-tools: Bash(npm *) Bash(./scripts/verify.sh *)
---

## Environment
```!
node --version
npm --version
```

## Steps
1. Install dependencies with `npm ci`.
2. If `.env` is missing, copy `.env.example` to `.env`; ask before overwriting.
3. Start the app with `npm run dev`.
4. Run `./scripts/verify.sh` and report PASS or FAIL.

Expected output: a single PASS/FAIL line and the local URL the app serves on.

El bloque delimitado ```! utiliza inyección de contexto dinámico: Claude Code ejecuta esos comandos e inserta la salida antes de que el agente lea la skill, de modo que el procedimiento llega fundamentado en tu cadena de herramientas real, no en una suposición. Escribe “get the app running” y el agente carga la skill a partir de su descripción; escribe /run-app para forzarla.

Claude Code también incluye este patrón exacto como una skill integrada. /run-skill-generator pone tu aplicación en marcha desde un entorno limpio, captura lo que funcionó (los comandos de instalación, las variables de entorno, el script de arranque) y lo confirma como una skill por proyecto en .claude/skills/run-<name>/. A partir de entonces, /run, /verify y cualquier otro agente en el repositorio siguen el procedimiento registrado en lugar de redescubrirlo. /run, /verify y /run-skill-generator requieren Claude Code v2.1.145 o posterior.

Haz que las skills sean confiables y luego confírmalas en el repositorio

Mantén cada skill atómica y declara explícitamente la salida esperada: una skill, un trabajo, un resultado claramente definido que puedas revisar en un pull request. Las instrucciones vagas producen deriva; un formato de salida definido mantiene las ejecuciones consistentes y hace que el análisis posterior sea seguro.

Traslada los pasos que no deben variar a un scripts/verify.sh incluido y deja que el cuerpo del SKILL.md se encargue de la interpretación: reportar por qué falló la verificación, detectar una variable de entorno faltante. Esta separación es lo que hace que el flujo de trabajo sea repetible en lugar de probabilístico.

Sé honesto sobre la única limitación real: la invocación automática depende completamente de la description, y no siempre se activa. El primer paso de solución de problemas en la documentación es verificar que la descripción incluya palabras clave que los usuarios dirían de forma natural. Cuando necesitas un disparo manual garantizado (cualquier cosa con efectos secundarios), establece disable-model-invocation: true para que la skill se ejecute solo cuando escribas /nombre.

Luego confirma .claude/skills/ en el control de versiones. Ese único acto cierra el ciclo: el procedimiento se vuelve versionado, revisable y compartido, de modo que el próximo colaborador y la próxima sesión del agente heredan un procedimiento funcional en lugar de reconstruirlo. Las skills están disponibles en Claude.ai, Claude Code y la API, y según la documentación de soporte de Anthropic también están en beta para usuarios de Claude Code y para todos los usuarios de la API que utilizan la herramienta de ejecución de código, por lo que una skill de proyecto confirmada viaja con el repositorio en lugar de vivir en el historial de shell de una sola persona.

Empieza con tu tarea más repetida (el arranque desde un checkout limpio, el changelog de la versión, el seed y reset): escribe su SKILL.md, empaqueta la parte determinista como un script y confírmalo. La próxima vez que alguien (o el agente) necesite ese procedimiento, ya estará registrado.

Preguntas frecuentes

¿Puedo invocar una Claude Code skill manualmente, o solo se activa automáticamente?

Puedes hacer ambas cosas. Por defecto, tanto tú como Claude pueden invocar cualquier skill: escribe /nombre-de-skill para ejecutarla directamente, y Claude puede cargarla automáticamente cuando su descripción coincida con tu solicitud. Las guías más antiguas que afirman que las skills no pueden ejecutarse manualmente están desactualizadas. Si quieres un comportamiento solo manual para una skill con efectos secundarios, establece disable-model-invocation en true para que solo se active cuando escribas su nombre.

¿Qué ocurre cuando un slash command y una skill comparten el mismo nombre?

La skill tiene prioridad. Los comandos personalizados se han fusionado con las skills: un archivo en .claude/commands/deploy.md y una skill en .claude/skills/deploy/SKILL.md crean el mismo comando /deploy y funcionan de manera idéntica. Cuando ambos existen bajo el mismo nombre, Claude Code carga la skill en lugar del archivo de comando, por lo que no es necesario mantener ambos para un mismo comando.

¿Un script incluido en una skill consume tokens de la ventana de contexto?

No. Cuando las instrucciones de una skill hacen referencia a un script ejecutable, Claude lo ejecuta mediante bash y recibe solo la salida; el código del script en sí nunca entra en la ventana de contexto. Por eso empaquetar el trabajo determinista como un script es más económico y confiable que pedirle al modelo que lo razone, y por eso los recursos que una skill puede incluir son efectivamente ilimitados en tamaño.

¿Necesito pagar por un plan para usar las Claude Code skills?

No. Según la documentación de soporte de Anthropic, las skills están disponibles en los planes Free, Pro, Max, Team y Enterprise, y la funcionalidad requiere que la ejecución de código esté habilitada. En Claude Code específicamente, las skills están disponibles en beta, y también funcionan para todos los usuarios de la API que utilizan la herramienta de ejecución de código. Los detalles de disponibilidad cambian con frecuencia, así que confirma con la documentación de soporte actual de Anthropic.