@saulwade/swl-ses 1.4.1 → 1.4.2

package/habilidades/meta-skills-estandar/recursos/convencion-examples.md

@@ -1,93 +1,93 @@
-# Convención `EXAMPLES.md` — recurso opcional para skills críticos
-
-Convención **opcional** para skills cuyo valor depende de ejemplos concretos
-con diff MAL → BIEN. Esta convención NO es retroactiva: las 63 carpetas
-`recursos/` existentes en `habilidades/` no se renombran. Solo aplica a:
-
-- Skills nuevos cuyo dominio se entiende mejor con ejemplos lado a lado.
-- Skills existentes que reciban actualización mayor y agreguen ejemplos.
-
----
-
-## Cuándo aplicarla
-
-Aplicar cuando:
-
-- El skill prescribe **decisiones técnicas** o **patrones** cuyo error es
-  sutil sin un caso concreto (ej: anti-patrones de async, gotchas de framework,
-  decisiones arquitecturales).
-- El skill se beneficia de mostrar 2-4 ejemplos lado a lado: el caso aplicado
-  correctamente vs el caso degenerado.
-- Los ejemplos suman > 100 líneas y meterlos en SKILL.md lo pasaría del
-  límite de 300 líneas.
-
-NO aplicar cuando:
-
-- El skill ya tiene `recursos/` con archivos temáticos específicos
-  (ej: `meta-skills-estandar/recursos/anti-patrones-y-leyes.md`). El nombre
-  temático es más informativo que `EXAMPLES.md`.
-- El skill es un how-to procedural sin antipatrones contrastables.
-- El skill tiene < 80 líneas en SKILL.md y los ejemplos caben en línea.
-
----
-
-## Estructura recomendada
-
-```
-habilidades/<skill-name>/
-├── SKILL.md
-└── recursos/
-    └── EXAMPLES.md
-```
-
-`SKILL.md` enlaza al final con:
-
-```markdown
-Para ejemplos concretos de aplicación, ver [`recursos/EXAMPLES.md`](recursos/EXAMPLES.md).
-```
-
-`EXAMPLES.md` contiene 2-4 ejemplos siguiendo el patrón:
-
-```markdown
-## Ejemplo N — [título corto del escenario]
-
-**Contexto**: [1-2 líneas]
-
-### ❌ Sin <skill-name> (hipotético)
-[código o descripción del enfoque incorrecto + consecuencia observable]
-
-### ✓ Con <skill-name>
-[código o descripción del enfoque correcto + por qué evita la consecuencia]
-```
-
-Cierre de `EXAMPLES.md`: tabla resumen de los ejemplos con la dimensión
-clave que cambió (costo, tiempo, severidad de bug, etc.).
-
----
-
-## Por qué OPCIONAL y no obligatoria
-
-- 63 carpetas `recursos/` ya existen con nomenclatura temática
-  (`anti-patrones-y-leyes.md`, `frameworks-seguridad.md`,
-  `idiomas-framework.md`). Forzar `EXAMPLES.md` rompería información
-  semántica del nombre.
-- La regla core `reglas/skills-estandar.md` ya prescribe que `SKILL.md`
-  no exceda 300 líneas y que los `recursos/` se nombren en kebab-case
-  con sufijo `.md` — esa regla cubre el 95% de los casos.
-- Esta convención **complementa** la regla core para skills donde un nombre
-  semántico genérico (`EXAMPLES.md`) comunica mejor el contenido que un
-  nombre específico (ej: `casos-decisiones-arquitecturales.md` es más largo
-  y menos buscable).
-
----
-
-## Origen
-
-Patrón observado en repos externos analizados el 2026-05-09
-(`temp/agent-skills-main`, `temp/andrej-karpathy-skills-main`):
-varios skills críticos exponen un `EXAMPLES.md` con diffs MAL/BIEN
-auto-cargable como referencia rápida del agente.
-
-Adoptado en `habilidades/doubt-driven-review/recursos/EXAMPLES.md` como
-primera aplicación. Casos futuros: skills de decisiones arquitecturales,
-seguridad, debugging avanzado.
+# Convención `EXAMPLES.md` — recurso opcional para skills críticos
+
+Convención **opcional** para skills cuyo valor depende de ejemplos concretos
+con diff MAL → BIEN. Esta convención NO es retroactiva: las 63 carpetas
+`recursos/` existentes en `habilidades/` no se renombran. Solo aplica a:
+
+- Skills nuevos cuyo dominio se entiende mejor con ejemplos lado a lado.
+- Skills existentes que reciban actualización mayor y agreguen ejemplos.
+
+---
+
+## Cuándo aplicarla
+
+Aplicar cuando:
+
+- El skill prescribe **decisiones técnicas** o **patrones** cuyo error es
+  sutil sin un caso concreto (ej: anti-patrones de async, gotchas de framework,
+  decisiones arquitecturales).
+- El skill se beneficia de mostrar 2-4 ejemplos lado a lado: el caso aplicado
+  correctamente vs el caso degenerado.
+- Los ejemplos suman > 100 líneas y meterlos en SKILL.md lo pasaría del
+  límite de 300 líneas.
+
+NO aplicar cuando:
+
+- El skill ya tiene `recursos/` con archivos temáticos específicos
+  (ej: `meta-skills-estandar/recursos/anti-patrones-y-leyes.md`). El nombre
+  temático es más informativo que `EXAMPLES.md`.
+- El skill es un how-to procedural sin antipatrones contrastables.
+- El skill tiene < 80 líneas en SKILL.md y los ejemplos caben en línea.
+
+---
+
+## Estructura recomendada
+
+```
+habilidades/<skill-name>/
+├── SKILL.md
+└── recursos/
+    └── EXAMPLES.md
+```
+
+`SKILL.md` enlaza al final con:
+
+```markdown
+Para ejemplos concretos de aplicación, ver [`recursos/EXAMPLES.md`](recursos/EXAMPLES.md).
+```
+
+`EXAMPLES.md` contiene 2-4 ejemplos siguiendo el patrón:
+
+```markdown
+## Ejemplo N — [título corto del escenario]
+
+**Contexto**: [1-2 líneas]
+
+### ❌ Sin <skill-name> (hipotético)
+[código o descripción del enfoque incorrecto + consecuencia observable]
+
+### ✓ Con <skill-name>
+[código o descripción del enfoque correcto + por qué evita la consecuencia]
+```
+
+Cierre de `EXAMPLES.md`: tabla resumen de los ejemplos con la dimensión
+clave que cambió (costo, tiempo, severidad de bug, etc.).
+
+---
+
+## Por qué OPCIONAL y no obligatoria
+
+- 63 carpetas `recursos/` ya existen con nomenclatura temática
+  (`anti-patrones-y-leyes.md`, `frameworks-seguridad.md`,
+  `idiomas-framework.md`). Forzar `EXAMPLES.md` rompería información
+  semántica del nombre.
+- La regla core `reglas/skills-estandar.md` ya prescribe que `SKILL.md`
+  no exceda 300 líneas y que los `recursos/` se nombren en kebab-case
+  con sufijo `.md` — esa regla cubre el 95% de los casos.
+- Esta convención **complementa** la regla core para skills donde un nombre
+  semántico genérico (`EXAMPLES.md`) comunica mejor el contenido que un
+  nombre específico (ej: `casos-decisiones-arquitecturales.md` es más largo
+  y menos buscable).
+
+---
+
+## Origen
+
+Patrón observado en repos externos analizados el 2026-05-09
+(`temp/agent-skills-main`, `temp/andrej-karpathy-skills-main`):
+varios skills críticos exponen un `EXAMPLES.md` con diffs MAL/BIEN
+auto-cargable como referencia rápida del agente.
+
+Adoptado en `habilidades/doubt-driven-review/recursos/EXAMPLES.md` como
+primera aplicación. Casos futuros: skills de decisiones arquitecturales,
+seguridad, debugging avanzado.

package/habilidades/meta-skills-estandar/recursos/skills-as-agents.md

@@ -1,163 +1,163 @@
-# 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("tldr-pdf")` 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.
+# 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("tldr-pdf")` 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.