Claude Skills Custom Agents: Tu Prompt de Sistema es un Monolito y No lo Sabes
Claude Skills custom agents no son prompts reutilizables. Aprende por qué el monolito de system prompt es deuda técnica y cómo las micro-skills atómicas transforman tu arquitectura de IA.
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:
```
Eres un asistente experto en soporte técnico.
Responde en español de España.
Usa un tono profesional pero cercano.
Sé conciso, máximo 3 párrafos.
Formatea las respuestas en markdown.
Cuando des código, usa bloques con lenguaje.
No inventes información técnica.
Si no sabes algo, dilo.
Prioriza la seguridad del usuario.
Sigue las políticas de GDPR para datos personales.
Revisa que el código no tenga vulnerabilidades.
...
```
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:
```
Nombre: tone-professional-es
Descripción: Aplica tono profesional en español de España.
Instrucciones: Responde siempre en español de España.
Usa "vosotros" para plural. Evita anglicismos excepto términos técnicos (API, deploy, framework).
Sé directo pero educado. No uses jerga informal.
```
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:
```
tone-professional-v2.1
format-markdown-v1.0
compliance-gdpr-v3.2
output-json-v2.0
```
Guarda las definiciones en tu repositorio como ficheros YAML o JSON. Así puedes hacer diff, rollback y revisión de PRs.
Ejemplo en YAML:
```yaml
name: output-json
version: 2.0
description: "Formatea todas las respuestas como JSON válido."
instructions: |
Responde exclusivamente en JSON válido.
Usa el schema: { "response": string, "confidence": number, "sources": string[] }
No incluyas markdown ni texto fuera del JSON.
Si no puedes generar JSON, responde con: { "error": "No se pudo generar respuesta JSON" }
activation: "Solo cuando el usuario pide datos estructurados o en llamadas API"
```
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.
```yaml
name: default-fallback
version: 1.0
description: "Comportamiento base cuando no hay Skills específicas activas."
instructions: |
Responde de forma genérica pero útil.
Mantén el tono neutral.
Si el usuario pide algo que requiere una Skill específica, sugiérela.
```
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):
```
Eres un asistente que genera documentación técnica.
Responde en español de España en tono profesional.
Genera markdown válido con bloques de código y tablas.
Sé exhaustivo pero estructurado.
Incluye ejemplos de uso.
No inventes APIs que no existen.
Revisa que los tipos de TypeScript sean correctos.
...
```
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`:
```yaml
name: code-security-audit
version: 1.2
conflict-resolution: "Esta Skill tiene prioridad sobre skills de concisión o resumen. La seguridad va antes que la brevedad."
instructions: |
...
```
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:
```javascript
// Pseudocódigo — asigna Skills según el rol del usuario
const userSkills = {
'customer-support': ['tone-professional-es', 'format-markdown', 'compliance-gdpr'],
'developer': ['tone-professional-es', 'output-json', 'code-security-review'],
'admin': ['tone-professional-es', 'style-technical-deep', 'format-markdown', 'compliance-gdpr']
}
async function handleRequest(user, prompt, context) {
const skills = userSkills[user.role]
// Activa las Skills correspondientes vía API
const response = await claude.messages.create({
model: 'claude-sonnet-4-20250514',
system: skills.map(s => loadSkill(s)).join('\n'),
messages: [{ role: 'user', content: prompt }]
})
return response
}
```
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:
1. Tests unitarios por Skill: ¿La Skill `output-json` produce JSON válido en todos los casos?
2. Tests de integración por combinación: ¿`output-json` + `tone-professional-es` produce JSON en español de España?
3. Tests de conflicto: Cuando dos Skills tienen instrucciones opuestas, ¿cuál prevalece?
Ejemplo de test de integración:
```
Combinación: output-json + tone-professional-es
Entrada: "Dime el número de usuarios activos"
Se espera: { "response": "Hay 1.234 usuarios activos", "confidence": 0.95 }
No se espera: Texto en markdown, inglés, tono informal
```
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.
Lee el artículo completo en brianmenagomez.com
Más sobre mis servicios en brianmenagomez.com
Herramientas: Conversor IAE CNAE · Gestorias cerca de ti · Calculadora IRPF