Claude Skills Custom Agents: Tu Prompt de Sistema es un Monolito y No lo Sabes

Tu "Custom Instructions" Son una Bomba de Relojería y No lo Sabes

Tienes 47 prompts de sistema repartidos entre 12 proyectos. Cada uno tiene reglas de tono, formato JSON, restricciones de dominio, ejemplos few-shot y un párrafo sobre "sé conciso pero completo".

Funcionan. Hasta que dejan de funcionar.

Cambias una regla de formato en un proyecto. Se te olvida actualizar los otros 11. Un developer junior copia un prompt viejo, lo modifica para su caso, y rompe sin saberlo el comportamiento de otro equipo.

*El problema no es que los prompts de sistema sean malos. Es que los tratáis como documentos cuando deberían ser módulos. *

Claude Skills no son "prompts de sistema con botón de guardar". Son la diferencia entre tener todo el CSS en inline styles y usar clases modulares. Y el 90% de los desarrolladores sigue escribiendo inline styles.

---

El Monolito Invisible: Por Qué tu System Prompt es Deuda Técnica

Mira tu prompt de sistema principal. Probablemente se parece a esto:

Eso no es un prompt. Es un vertedero.

Cada línea vive ahí porque alguien necesitaba esa regla en algún momento. Pero ahora todas conviven en el mismo espacio de direcciones, sin separación de concerns, sin posibilidad de testeo unitario, sin versionado granular.

❌ Monolito: 15 reglas mezcladas en un solo bloque. Cambiar una línea puede romper las otras 14.

✅ Micro-Skills: Cada regla es un módulo independiente. Activas los que necesitas según el contexto.

El coste real no es escribirlo. El coste es mantenerlo cuando tienes 50 prompts en 10 proyectos.

---

Qué Es Realmente un Claude Skill (y Qué No es)

Un Claude Skill tiene tres campos: nombre, descripción e instrucciones. En superficie parece un prompt guardado.

La diferencia está en cómo se comportan en conjunto:

Se activan bajo demanda. No están siempre en el contexto. Solo se cargan cuando el usuario o el sistema las selecciona.
Se pueden componer. Puedes tener 3 Skills activas al mismo tiempo. Se fusionan en el contexto de forma determinista.
Son compartibles. En un workspace de equipo, publicas una Skill y todos la heredan. No necesitas copiar-pegar reglas.
Tienen API. La Projects API permite crear, asignar y versionar Skills programáticamente.

*Una Skill no es un prompt. Es una función de comportamiento que puedes importar. *

---

El Patrón de Micro-Skills Atómicas Componibles

He estado usando este patrón en producción durante los últimos meses. Lo llamo Patrón de Micro-Skills Atómicas Componibles. Funciona así:

1. Extrae Cada Comportamiento en una Skill Atómica

Coge tu system prompt monolítico. Sepáralo por responsabilidad, no por conveniencia.

| Comportamiento | Nombre de Skill | Activación |

|---|---|---|

| Tono profesional cercano | tone-professional-es | Siempre activa |

| Formato markdown con bloques de código | format-markdown | Siempre activa |

| Restricciones GDPR | compliance-gdpr | Solo datos personales |

| Reglas de seguridad en código | code-security-review | Solo código generado |

| Formato JSON estructurado | output-json | Solo API calls |

| Estilo técnico-detallado | style-technical-deep | Solo debugging |

Cada Skill tiene una descripción clara que especifica cuándo debe activarse. Piensa en ello como un docstring.

Ejemplo de Skill atómica:

2. Construye una Matriz de Composición

No todas las Skills se llevan bien juntas. Una Skill que dice "sé conciso" peleará con una que dice "explica en detalle cada línea de código".

Antes de desplegar, mapea las combinaciones:

tone-professional-es + format-markdown + output-json → Compatible. Activar siempre.
tone-professional-es + style-technical-deep + code-security-review → Compatible. Activar en debugging de código.
output-json + format-markdown → Conflicto. JSON no se mezcla con markdown. Definir prioridad.

Crea una matriz en tu repositorio. Literalmente un fichero skill-compatibility-matrix.md.

3. Versiona Cada Skill con SemVer

Las Skills evolucionan. Un cambio en tone-professional-es de v1.0 a v2.0 puede romper combinaciones que dependían del comportamiento anterior.

Define convenciones:

Guarda las definiciones en tu repositorio como ficheros YAML o JSON. Así puedes hacer diff, rollback y revisión de PRs.

Ejemplo en YAML:

4. Implementa una Estrategia de Fallback

Definir una Skill por defecto. Cuando el contexto de entrada no coincide con ninguna Skill específica, que se active la default.

Esto evita el comportamiento indefinido. No dejes que Claude "adivine" qué reglas aplicar.

---

El Caso de Uso Real: Composición en Acción

Pongamos un escenario real. Tienes una aplicación que genera documentación técnica a partir de código fuente.

Antes (monolito):

Después (Skills componibles):

| Skill activada | Propósito |

|---|---|

| tone-professional-es | Idioma y tono |

| format-markdown-docs | Estructura markdown con tablas, listas, bloques |

| code-ts-review | Validación de tipos TypeScript |

| style-exhaustive-structured | Profundidad y organización |

| docs-examples-included | Incluir ejemplos de uso |

Cada Skill es independiente. Puedes testear code-ts-review sola. Puedes reemplazar format-markdown-docs por output-json si cambias el formato de salida. Puedes compartir tone-professional-es con otros equipos que trabajen en español.

El cambio clave: ya no editas un prompt de 200 líneas. Activas o desactivas módulos.

---

Cómo Gestionar Conflictos Entre Skills

Dos Skills pueden tener instrucciones contradictorias. Ejemplo real que me pasó:

code-summarize decía: "Sé conciso, máximo 3 líneas por función"
code-security-audit decía: "Revisa cada línea en busca de vulnerabilidades SQL injection"

Juntas, Claude intentaba resumir y auditar a la vez. Resultado: resúmenes incompletos y auditorías superficiales.

Solución: priorización explícita.

En la descripción de cada Skill, incluye un campo conflict-resolution:

Cuando Claude recibe dos Skills con instrucciones enfrentadas, el orden de carga o la prioridad declarada determinan el comportamiento.

Regla práctica: Skills de seguridad y compliance siempre tienen prioridad sobre Skills de estilo o formato. Documenta este orden en tu skill-compatibility-matrix.md.

---

El Salto a Producción: API y Automatización

Las Skills no son solo para la UI de Claude.ai. La Projects API permite gestionarlas programáticamente.

Patrón de enrutamiento por rol:

Esto transforma tu arquitectura. El enrutamiento de Skills se convierte en una capa de middleware de comportamiento, separada de la lógica de negocio.

Beneficio directo: puedes cambiar el comportamiento de todo un rol editando una Skill, sin tocar una línea de código de la aplicación.

---

El Testing es el Nuevo Frontiera

Las Skills introducen una superficie de testeo nueva: las interacciones entre Skills.

Una Skill que funciona perfectamente sola puede romperse al combinarse con otra. Necesitas:

Tests unitarios por Skill: ¿La Skill output-json produce JSON válido en todos los casos?
Tests de integración por combinación: ¿output-json + tone-professional-es produce JSON en español de España?
Tests de conflicto: Cuando dos Skills tienen instrucciones opuestas, ¿cuál prevalece?

Ejemplo de test de integración:

Incluye estos tests en tu CI. Cuando alguien modifica una Skill, que los tests se ejecuten automáticamente.

---

Resumen: Lo que Cambia Realmente

| Antes | Después |

|---|---|

| Un prompt de 200 líneas | 5 Skills de 5 líneas cada una |

| Editar un campo rompe todo | Editar una Skill no afecta a las otras |

| Cada proyecto tiene su prompt copiado | Una Skill compartida se actualiza para todos |

| No hay versionado | SemVer por Skill |

| No hay tests | Tests unitarios y de integración por combinación |

| Dependencia del developer que escribió el prompt | Gobernanza de equipo sobre Skills publicadas |

*Tu system prompt no es un documento. Es código. Y el código se modulariza, se versiona y se testea. *

Claude Skills no son la evolución de los prompts. Son el fin de los prompts como los conocías. El que entienda esto primero va a construir sistemas de IA que otros no pueden mantener.