# Skills as Agents — patrón técnico avanzado

Documenta el patrón Anthropic nativo de ejecutar un skill SWL en su propio
sub-agente con `agent: true` + `model:` en el frontmatter. Origen: artículo
"Claude Code's Limits Are Generous. The Problem Is Your Harness." sección 2.3.

## Concepto

Un SKILL.md normal es contenido que se carga al contexto del padre cuando
se invoca con `Skill("nombre")`. El skill aporta reglas, conocimiento o
guía al modelo del padre, que las usa al razonar.

Con el patrón skills as agents, el skill se vuelve **invocable como
sub-agente independiente**: tiene su propio modelo, su propio contexto,
y solo devuelve un resultado acotado al padre. Útil cuando el skill
procesa un input grande y debe entregar un resumen.

## Cuándo usar este patrón

- El skill procesa un archivo o input grande y debe devolver solo un
  resumen al padre (ejemplo: extraer TLDR de un PDF de 50 páginas, sin
  que el texto completo entre al contexto del padre).
- El skill ejecuta búsqueda exhaustiva o crawling de un codebase completo
  y el resultado es un set acotado de findings.
- El skill necesita un modelo distinto al del padre por costo o latencia
  (Haiku para trabajo mecánico cuando el padre es Opus).
- El trabajo del skill es paralelizable y se va a invocar varias veces en
  la misma sesión.

## Cuándo NO usar

- El skill solo aporta reglas o conocimiento estático que se aplica al
  razonamiento del padre — esos son skills "passive" normales y NO
  necesitan `agent: true`. Su valor es justamente que cargan reglas al
  contexto del padre.
- El skill es referenciado dentro de otro skill como contenido de apoyo
  — el contexto del padre lo necesita ver.
- El skill requiere acceso al contexto activo del padre (decisiones
  tomadas mid-session, archivos ya leídos) — `agent: true` aísla del
  padre, así que el sub-agente no vería esa información.
- El skill es invocado una sola vez en la sesión y su output es pequeño
  — el overhead de spawn de sub-agente puede dominar.

## Ejemplo de skill como agent

```yaml
---
name: tldr-pdf
description: >
  Extrae TLDR de 200 palabras de un PDF sin cargar el texto completo en
  el contexto del padre. Cargar cuando se reciba ruta a un PDF que solo
  necesita resumen ejecutivo.
agent: true
model: claude-haiku-4-5-20251001
herramientasPermitidas: [Bash, Read]
---

# tldr-pdf

Recibes la ruta de un PDF como input.

1. Ejecuta `pdftotext "$1" -` para extraer texto.
2. Lee la salida.
3. Devuelve SOLO:
   - 5 bullets de TLDR
   - 3 quotes que valga la pena conservar
   - URLs citadas

Nunca devuelvas el texto completo. Nunca expandas más allá de la estructura.
```

Flujo: el padre invoca `Skill("swl-markitdown")` con la ruta del PDF; el
sub-agente Haiku ejecuta `pdftotext`, lee la salida (que llena su propio
contexto, no el del padre), y devuelve ~200 palabras estructuradas. El PDF
completo nunca toca el contexto del padre.

## Reglas del patrón

### Frontmatter

- `agent: true` activa el modo sub-agente.
- `model:` debe ser un modelo Anthropic válido. Para skills mecánicos,
  preferir Haiku (5× más barato que Sonnet, 25× más barato que Opus 4.7).
- El frontmatter sigue siendo válido SWL: incluir `name`, `description`,
  `herramientasPermitidas`, `exclusiones` y demás campos obligatorios.

### Cuerpo

- Debe ser **autocontenido**: el sub-agente NO tiene acceso al contexto
  del padre (CLAUDE.md del proyecto, instintos cargados, sesión activa,
  archivos previamente leídos). Todo lo que necesite saber tiene que
  estar en el cuerpo del skill o en lo que reciba como input.
- El output debe ser **acotado**: si el sub-agente devuelve un dump
  masivo, se pierde el beneficio (terminamos pasando lo mismo al padre,
  solo con un round-trip extra). Especificar formato exacto en el
  cuerpo del skill: número de bullets, longitud máxima, qué incluir y
  qué no.

### Errores comunes a evitar

- **Usar Opus en `model:` para skills mecánicos**: invalida el ahorro de
  costo. La mayoría de skills as agents deberían ser Haiku o Sonnet.
- **Devolver el texto crudo del input**: si el skill recibe un PDF y
  devuelve el texto completo, no estamos aislando nada. Devuelve siempre
  la transformación, no el material crudo.
- **Asumir que el skill verá el CLAUDE.md del proyecto**: no lo verá.
  Si el skill necesita seguir convenciones del proyecto, hay que
  explicárselas en el cuerpo.

## Skills SWL candidatos al patrón (no migración masiva)

Evaluación caso por caso. NO aplicar masivamente — el patrón aporta solo
cuando el skill consume input grande y devuelve output acotado.

| Skill SWL | Por qué encaja | Modelo recomendado |
|-----------|----------------|--------------------|
| `extraccion-documentos` | Procesa PDFs/Office grandes | Haiku |
| `mapear-codebase` | Procesa codebase entero, devuelve reporte | Sonnet |
| `wiki-conocimiento` (modo query) | Búsqueda en wiki con respuesta acotada | Sonnet |

Skills NO candidatos (son passive, su valor es cargar reglas al contexto del padre):

- `manejo-errores`, `auth-patrones`, `api-rest-diseno`, `accesibilidad-a11y`, etc.
- Toda regla de estilo o convención por lenguaje.
- Toda regla SWL en `reglas/`.

## Implicaciones operativas

### Costo

Spawn de sub-agente tiene overhead (system prompt + carga del skill +
contexto inicial). Para inputs chicos, el overhead supera el ahorro.
Regla práctica: usar el patrón si el input que el skill procesa es
≥3,000 tokens (o ≥10K caracteres).

### Latencia

El padre espera al sub-agente antes de continuar. Si el skill demora >10s,
considerar si la operación cabe en el padre directamente (sin spawn).

### Trazabilidad

Los sub-agentes spawneados aparecen en `claude-usage` (vendor SWL) como
invocaciones separadas con su propio modelo. Útil para entender qué
porcentaje del costo viene de sub-agentes vs. trabajo del padre.

### Compatibilidad con SWL

- El skill sigue registrado normalmente en `manifiestos/modulos.json`.
- El skill se invoca igual: `Skill("nombre")`. La diferencia es interna
  (el harness Anthropic decide si lo carga al padre o lo ejecuta como
  sub-agente según el frontmatter).
- Hooks SWL siguen aplicando: `linea-estado.js`, `monitor-contexto.js`,
  `audit-trail.js` registran las invocaciones del sub-agente.

## Referencias

- Artículo de origen: "Claude Code's Limits Are Generous. The Problem Is
  Your Harness." (sección 2.3 — Skills Can Also Be Invoked as Agents).
- Documentación oficial Anthropic sobre Claude Skills (cuando esté
  disponible).
- `Skill("harness-claude-code")` — uso operativo del patrón en sesiones
  largas, junto con sub-agentes via Task tool y delegación explícita.
