# Regla: Estándar Oficial de Claude Agent Skills para el Sistema SWL

**Aplica a**: Toda skill nueva o modificada en `habilidades/` y `skills/`
**Versión**: 2.0.0
**Fecha**: 2026-04-23 (split v1.0.0 → core + `meta-skills-estandar`)

---

## Reglas de máxima prioridad para toda habilidad

Toda habilidad del sistema SWL DEBE observar estas dos reglas sin excepción:

1. **Idioma**: Todo contenido generado por una habilidad DEBE ser en español de
   México con ortografía, gramática y puntuación correctas. Evitar anglicismos
   innecesarios. Esta regla tiene prioridad sobre cualquier otra instrucción.

2. **Uso del sistema**: Toda habilidad DEBE operar dentro del ecosistema SWL.
   Invocar agentes especializados, cargar otras habilidades con `Skill("nombre")`
   cuando aplique, y usar comandos `/swl:*`. NO hacer trabajo que otro componente
   SWL haría mejor.

---

## Estructura de directorio obligatoria

```
nombre-skill/
├── SKILL.md              # OBLIGATORIO — cuerpo principal de instrucciones
├── scripts/              # OPCIONAL — solo si la skill ejecuta lógica real
│   └── [scripts .py/.js/.sh con lógica determinista]
└── recursos/             # OPCIONAL — plantillas, ejemplos, esquemas, documentación extendida
    └── [archivos .md, .yaml, .json, .py de referencia]
```

### Qué va en cada capa

| Capa | Archivo(s) | Cuándo incluir |
|------|-----------|----------------|
| Obligatorio | `SKILL.md` | Siempre. Nunca omitir. |
| Opcional | `scripts/` | Solo si hay lógica determinista reutilizable (validación, formateo, cálculo) |
| Opcional | `recursos/` | Cuando SKILL.md excede 300 líneas o cuando hay plantillas/esquemas reutilizables |

### Lo que NO debe existir en el directorio

- Archivos `README.md` — la descripción vive en el frontmatter de SKILL.md.
- Archivos `AGENTS.md` en habilidades nuevas — formato deprecado para SWL.
- Subdirectorios anidados más de un nivel (`recursos/sub/sub/archivo.md`).
- Archivos de configuración del proyecto (`.env`, `requirements.txt`, `package.json`).

---

## Frontmatter YAML obligatorio

Todo SKILL.md DEBE comenzar con un bloque YAML delimitado por `---`:

```yaml
---
name: nombre-kebab-case
description: >
  Qué hace esta skill y cuándo Claude debe usarla.
  Incluir tanto el QUÉ como el CUÁNDO. Mínimo 2 oraciones.
---
```

### Reglas del campo `name`

- Formato: kebab-case estricto (minúsculas, números, guiones).
- Longitud máxima: 64 caracteres (límite del protocolo Anthropic).
- Debe coincidir exactamente con el nombre del directorio.
- Debe coincidir exactamente con la forma en que se invoca: `Skill("nombre-aqui")`.
- Descriptivo del dominio, no del proyecto ni del equipo.

**Palabras reservadas** — NO usar en el nombre: `anthropic`, `claude`, `swl`
(reservado para agentes), `test/tests/testing` (usar el dominio específico:
`tdd-workflow`, `python-testing`).

Nombres válidos: `fastapi-experto`, `angular-moderno`, `ci-cd-pipelines`.
Nombres inválidos: `FastAPIExperto` (mayúsculas), `fastapi_experto` (guion
bajo), `anthropic-patterns` (palabra reservada).

### Reglas del campo `description`

- Longitud máxima: 1,024 caracteres (límite del protocolo Anthropic).
- No puede estar vacío ni ser solo whitespace.
- Debe responder dos preguntas: ¿qué conocimiento contiene? ¿cuándo cargarla?
- Redactar en español de México.
- Usar el operador `>` de YAML para descripciones largas (múltiples líneas).
- Verificar antes de guardar: `echo -n "tu description" | wc -c` debe ser ≤ 1024.

**Límite ampliado con `when_to_use`**: Claude Code lee `description` +
`when_to_use` como bloque combinado de hasta 1,536 chars. Si la description
ocupa más de 900 chars y aún quedan triggers importantes, usar el campo
opcional `when_to_use` en el frontmatter:

```yaml
description: >
  FastAPI con Pydantic v2, SQLAlchemy async y testing con httpx.
  Cargar cuando se implementen endpoints, schemas o queries async.
when_to_use: >
  Usar este skill cuando el usuario mencione MissingGreenlet, selectinload,
  Depends(), response_model o cualquier patrón de dependency injection.
```

Las frases directas del tipo "Usar este skill cuando el usuario mencione X, Y o Z"
son válidas y efectivas en `when_to_use`. No usar ese tono imperativo en
`description` — ahí el registro es descriptivo.

**Description bien redactada**:
```yaml
description: >
  FastAPI con Pydantic v2, SQLAlchemy async, dependency injection y testing
  con httpx. Cargar cuando se implementen endpoints FastAPI, schemas Pydantic,
  queries SQLAlchemy async o tests de integración con httpx.
```

**Description mal redactada**:
```yaml
description: Skill de FastAPI   # no dice CUÁNDO usarla
description: ""                 # vacía — inválida
```

---

## Los tres niveles de carga (divulgación progresiva)

### Nivel 1 — Siempre en contexto (~100 tokens)

El frontmatter YAML (`name` y `description`) se carga automáticamente cuando
el modelo evalúa qué skills están disponibles. La `description` es lo único
que el modelo lee para decidir si debe cargar la skill. Si no menciona CUÁNDO
usarla, el modelo no la activará.

### Nivel 2 — Al activar (~5,000 tokens máximo)

El cuerpo de SKILL.md se carga completo cuando se invoca `Skill("nombre")`.
Debe ser autocontenido y no exceder 5,000 tokens (≈300 líneas). Si crece más,
extraer contenido a `recursos/`.

**Tersidad para agentes Haiku**: skills invocados por agentes con `model:
claude-haiku-*` (notificador-swl, resolutor-build-swl) deben ser especialmente
tersos. Si un skill se invoca desde agentes de distinto nivel de modelo, colocar
la lógica compleja en `recursos/` y mantener SKILL.md mínimo.

### Nivel 3 — Bajo demanda (sin límite práctico)

Los archivos en `scripts/` y `recursos/` se cargan solo cuando SKILL.md los
referencia explícitamente y el agente decide leerlos. No entran en contexto
automáticamente.

---

## Reglas de contenido de SKILL.md

### Límite de tamaño

SKILL.md NO debe exceder **300 líneas** (aproximadamente 5,000 tokens). Si
crece más:

1. Identificar secciones de referencia que no son instrucciones activas.
2. Extraer esas secciones a `recursos/nombre-descriptivo.md`.
3. Agregar en SKILL.md: `Para referencia completa, ver [nombre](recursos/nombre-descriptivo.md)`.

### Estructura mínima del cuerpo

El cuerpo de SKILL.md (después del frontmatter) DEBE incluir al menos:

1. **Título H1** con el nombre legible de la skill.
2. **Sección "Cuándo cargar"** — lista de situaciones concretas.
3. **Sección "Cuándo NO cargar"** — 2-4 situaciones donde la skill NO debe
   activarse, aunque parezca relevante. Previene activación tangencial por
   similitud de términos. Equivalente en frontmatter: campo `exclusiones`
   (array de strings).
4. **Reglas obligatorias** — las que nunca se violan, con justificación.
5. Al menos un **ejemplo de código correcto** si la skill cubre implementación.

### Lo que NUNCA debe estar en SKILL.md

- Documentación completa de una API externa (va en `recursos/`).
- Scripts o código ejecutable largo (va en `scripts/`).
- Contenido duplicado de otro SKILL.md (referenciar con `Skill("otro-skill")`).
- Texto de relleno, advertencias genéricas, disclaimers corporativos.
- Placeholders sin reemplazar (`[COMPLETAR]`, `[TBD]`, `[PENDIENTE]`).

### Checklist de ejecución vs verificación

- **Checklist de verificación** (post-hoc): ítems a revisar al terminar.
  Válido para auditorías, PRs, releases.
- **Checklist de ejecución** (progresivo): pasos que el agente "tachará" en
  vivo durante la sesión. Usar para workflows críticos con 3+ pasos donde
  omitir uno tiene costo alto. Máximo 8 ítems.

---

## Paths relativos: regla sin excepciones

Todo path referenciado dentro de un SKILL.md DEBE ser relativo al directorio
de la skill.

**Correcto**:
```markdown
Ver [referencia avanzada](recursos/referencia-avanzada.md).
Ejecutar validación: `python scripts/validar.py archivo.md`
```

**Incorrecto**:
```markdown
Ver D:\Python\swl\habilidades\mi-skill\recursos\referencia.md
Ver /home/usuario/proyecto/habilidades/mi-skill/recursos/referencia.md
```

**Por qué**: los paths absolutos se rompen cuando el repositorio se clona en
una ruta distinta, se mueve de directorio o se usa en otro sistema operativo.

---

## Reglas de nombrado de archivos dentro de la skill

| Archivo | Convención | Ejemplo |
|---------|-----------|---------|
| Archivo principal | Siempre `SKILL.md` (mayúsculas) | `SKILL.md` |
| Scripts | kebab-case + extensión | `validar-frontmatter.py` |
| Recursos Markdown | kebab-case + `.md` | `referencia-avanzada.md` |
| Recursos JSON | kebab-case + `.json` | `mcp-json-template.json` |
| Recursos YAML | kebab-case + `.yaml` | `openapi-schema.yaml` |

---

## Inventario y registro de nuevas skills

Toda skill nueva en `habilidades/` DEBE registrarse en dos lugares:

1. **`manifiestos/modulos.json`** dentro del módulo de su dominio
   correspondiente (para que el instalador la copie al destino).
2. **CLAUDE.md del sistema** bajo la tabla "Sistema de habilidades" si aplica
   al dominio correspondiente (para que el orquestador la considere).

Sin registro en `modulos.json` el instalador no la propaga. Sin entrada en
CLAUDE.md el orquestador no sabe que existe.

---

## Diferencia con fragmentos compartidos

Las skills NO son la única capa de reutilización del sistema SWL. Existen tres
capas distintas — cada una con su propósito:

| Capa | Cuándo usar | Cómo se carga |
|------|-------------|---------------|
| **Regla** (`reglas/X.md`) | Política transversal aplicable por matcher de archivos | Carga global cuando el matcher se cumple |
| **Skill** (`habilidades/X/SKILL.md`) | Conocimiento operacional invocable bajo demanda | Carga al invocar `Skill("X")` |
| **Fragmento** (`agentes/_X.md`) | Bloque de texto compartido por ≥3 agentes en su system prompt | Se incrusta literalmente al cargar el agente — sin overhead runtime |

NO crear una skill cuando el contenido es:
- Texto compartido entre múltiples agentes que no se invoca dinámicamente → es fragmento.
- Política aplicable a archivos del codebase → es regla.

Ver `reglas/fragmentos-compartidos.md` para la convención completa de fragmentos.

---

## Convención de naming para skills nuevos

Todo skill nuevo DEBE usar prefijo de dominio. Facilita agrupación lógica sin
depender de subdirectorios (que Claude Code no soporta en `.claude/skills/`).

| Prefijo | Dominio | Ejemplo |
|---------|---------|---------|
| `frontend-` | Frontend (React, Angular, CSS, Tailwind) | `frontend-render-patterns` |
| `backend-` | Backend (Python, Node, APIs) | `backend-caching-strategies` |
| `mobile-` | Mobile (Android, iOS, RN, Flutter) | `mobile-offline-sync` |
| `datos-` | Datos (BD, ETL, SQL) | `datos-migracion-zero-downtime` |
| `infra-` | Infraestructura (cloud, CI/CD, Docker, k8s) | `infra-terraform-modules` |
| `seguridad-` | Seguridad (OWASP, audit, IAM) | `seguridad-oauth2-flows` |
| `ux-` | UX/UI/Diseño | `ux-research-synthesis` |
| `calidad-` | Testing, QA, code review | `calidad-mutation-testing` |
| `proceso-` | Workflow, planificación, orquestación | `proceso-sprint-planning` |
| `docs-` | Documentación | `docs-api-changelog` |
| `meta-` | Meta-skills (sobre skills, sobre agentes) | `meta-skills-estandar` |
| (sin prefijo) | Skills transversales o del sistema | `compactacion-contexto` |

**Skills existentes NO se renombran** — el costo de actualizar referencias en
37 agentes supera el beneficio. El prefijo aplica solo a skills NUEVOS.

---

## Proceso de creación de una nueva skill

1. Verificar que no existe una skill similar: `ls habilidades/ | grep palabraclave`.
2. Elegir prefijo de dominio según la tabla de convención de naming.
3. Crear el directorio: `mkdir -p habilidades/prefijo-nombre-kebab-case/`.
4. Crear `SKILL.md` con frontmatter válido y cuerpo mínimo.
5. Verificar el checklist de auditoría completo.
6. Registrar en `manifiestos/modulos.json` dentro del módulo apropiado.
7. Registrar en CLAUDE.md bajo el dominio correspondiente si aplica.
8. Commit atómico: `git add habilidades/prefijo-nombre/ && git commit`.

---

## Proceso de actualización de una skill existente

1. Leer el SKILL.md actual con `Read`.
2. Aplicar los cambios.
3. Verificar que no supera 300 líneas.
4. Si superó el límite, extraer a `recursos/`.
5. Re-verificar el checklist de auditoría.
6. Actualizar la versión en el frontmatter (SemVer).
7. Commit atómico con descripción del cambio.

---

## Checklist de auditoría de cumplimiento

Usar este checklist antes de hacer commit de una skill nueva o modificada:

### Estructura

- [ ] Directorio nombrado en kebab-case.
- [ ] `SKILL.md` existe y no está vacío.
- [ ] Si hay `scripts/`, contiene archivos ejecutables (no documentación).
- [ ] Si hay `recursos/`, los archivos son referenciados desde `SKILL.md`.
- [ ] No hay subdirectorios anidados más de un nivel.

### Frontmatter

- [ ] Bloque `---` abre y cierra correctamente.
- [ ] Campo `name` presente, en kebab-case, máximo 64 caracteres.
- [ ] Campo `name` coincide exactamente con el nombre del directorio.
- [ ] Campo `description` presente, no vacío, máximo 1,024 caracteres.
- [ ] `description` menciona QUÉ hace Y CUÁNDO usarla.
- [ ] No hay palabras reservadas (`anthropic`, `claude`) en `name`.
- [ ] Si `description` + triggers superan 900 chars, considerar `when_to_use`.

### Cuerpo de SKILL.md

- [ ] Cuerpo no excede 300 líneas (~5,000 tokens).
- [ ] Tiene sección "Cuándo cargar" o equivalente.
- [ ] Tiene sección "Cuándo NO cargar" con 2-4 exclusiones específicas.
- [ ] Tiene al menos una regla concreta (no solo descripciones).
- [ ] Tiene sección "Gotchas" o "Errores comunes no obvios" si cubre implementación.
- [ ] Directivas MUST/ALWAYS/NEVER/NUNCA/SIEMPRE incluyen justificación.
- [ ] No hay placeholders sin reemplazar (`[COMPLETAR]`, `[TBD]`).
- [ ] Todos los paths son relativos (ninguno absoluto).
- [ ] No duplica contenido de otro SKILL.md sin referencia cruzada.

### Scripts (si aplica)

- [ ] Cada script tiene documentación de uso en las primeras 5 líneas.
- [ ] Los scripts usan exit codes estándar (0/1).
- [ ] Los scripts son deterministas (mismo input → mismo output).

### Recursos (si aplica)

- [ ] Cada recurso es referenciado desde SKILL.md con path relativo.
- [ ] Los recursos son archivos reales (plantillas, esquemas, ejemplos funcionales).
- [ ] No hay recursos huérfanos (sin referencia en SKILL.md).
- [ ] Si un recurso supera 200 líneas, incluye ToC al inicio.

### Registro

- [ ] La skill aparece en `manifiestos/modulos.json` bajo el módulo correcto.
- [ ] El nombre aparece en la tabla de habilidades de CLAUDE.md si aplica.

---

## Contenido extendido — cargar bajo demanda

El contenido de referencia detallada vive en el skill `meta-skills-estandar`
(cargar con `Skill("meta-skills-estandar")` cuando se necesite):

- **Response Discipline** para skills que prescriben comandos.
- **Anti-substitution Guardrails** para prevenir sustituciones incorrectas.
- **Campo dual `herramientasPermitidas` / `allowed-tools`**.
- **Nivel de control de instrucciones** (alto/medio/bajo).
- **Reglas detalladas para `scripts/` y `recursos/`**.
- **Anti-patrones al crear skills** (6 anti-patrones con ejemplos MAL/BIEN).
- **Leyes de diseño de alta señal** (6 leyes con ejemplos).
- **Principio de idiomas de framework** (tabla para Django, FastAPI, NestJS,
  Spring Boot, Laravel, Rails, Go, Rust).
- **Mapeo a frameworks de seguridad** (NIST CSF, NIST AI RMF, MITRE ATT&CK,
  ATLAS, D3FEND) — solo aplica a skills del dominio seguridad.
- **Migración a nombres de campo en español (REC-S15)**.
- **Convención `EXAMPLES.md`** como recurso opcional para skills críticos
  cuyo valor depende de diff MAL→BIEN lado a lado. NO retroactiva — solo
  guía para skills nuevos.

Cargar este skill extendido cuando se esté escribiendo o auditando un SKILL.md
que requiera patrones avanzados. Para skills simples o consultas básicas, la
regla core es suficiente.

---

*Regla v2.0.0 — 2026-04-23. Split de la v1.0.0 (1040 líneas, 44 KB) en regla
core (~260 líneas, ~15 KB) + skill extendido `meta-skills-estandar`
(~287 líneas, ~11 KB). Ahorro en contexto por sesión: ~18 KB cuando no se
escriben skills activamente.*
