@saulwade/swl-ses 1.0.0

package/habilidades/diseno-herramientas-agente/SKILL.md

@@ -0,0 +1,199 @@
+---
+name: diseno-herramientas-agente
+description: >
+  Principios de diseno de herramientas (tools) para agentes de IA: Principio de
+  Consolidacion, reduccion arquitectonica, limite 10-20 tools por coleccion,
+  description como prompt engineering, naming MCP y diseno de mensajes de error.
+  Cargar cuando se disenan tools para agentes, se configura MCP, se definen
+  toolBudget en agentes SWL, o se evalua la coleccion de herramientas de un agente.
+herramientasPermitidas: [Read, Grep]
+exclusiones:
+  - "No cargar para implementar el hook que ejecuta los tools — este skill diseña la interfaz, no el handler; para implementar PreToolUse o PostToolUse cargar `hooks` o el agente correspondiente."
+  - "No cargar para evaluar si un agente específico cumple su SLA — eso es `evaluacion-agentes`; este skill cubre diseño de colecciones de tools, no rendimiento de agentes."
+  - "No cargar cuando el cambio es solo actualizar la descripción de una tool existente sin rediseñar la colección — el costo de carga no compensa para un fix de texto de una línea."
+  - "No cargar para configurar permisos de red o escritura en frontmatter de agentes — eso cae bajo `seguridad-agentes` y `estructura-proyecto-claude`."
+evolvable: true  # default para skill estandar
+---
+# Diseno de Herramientas para Agentes
+
+## Cuando cargar
+
+- Al disenar o revisar tools para agentes de IA (MCP servers, function calling)
+- Al configurar `toolBudget` o `tools` en frontmatter de agentes SWL
+- Al evaluar si un agente tiene demasiadas o muy pocas herramientas
+- Al escribir descripciones de herramientas para consumo de LLMs
+- Al disenar mensajes de error que un agente pueda interpretar
+
+---
+
+## Principio de Consolidacion
+
+> Cuando multiples herramientas se solapan en funcionalidad, consolidar en una
+> sola herramienta con parametros que controlan el comportamiento.
+
+El exceso de herramientas similares degrada el rendimiento del agente porque:
+- Aumenta el espacio de decision en cada turno
+- Genera confuision sobre cuial herramienta usar para queii
+- Consume tokens de contexto en las descripciones de cada tool
+
+### Reduccion arquitectonica
+
+Preferir la coleccion MINIMA de herramientas que cubra todos los casos de uso.
+Si una herramienta puede hacer lo que dos hacen por separado con un parametro
+adicional, consolidar.
+
+```
+MAL (3 tools solapadas):
+- search_files_by_name
+- search_files_by_content
+- search_files_by_pattern
+
+BIEN (1 tool con parametro):
+- search_files(query, mode: "name" | "content" | "pattern")
+```
+
+### Limite de herramientas por coleccion
+
+| Tamano de coleccion | Evaluacion |
+|---------------------|------------|
+| **1-10 tools** | Optimo. El agente puede razonar sobre todas sin confusion |
+| **10-20 tools** | Aceptable. Documentar agrupacion logica para orientar al agente |
+| **20-30 tools** | Riesgoso. Considerar dividir en sub-agentes especializados |
+| **30+ tools** | Problematico. El agente perdera tiempo eligiendo y cometera errores |
+
+En SWL, el `toolBudget` del frontmatter de agentes controla cuantos tool calls
+puede hacer un agente por tarea (simple/standard/complex). El diseno de herramientas
+complementa esto: menos herramientas mejor disenadas = menos calls necesarios.
+
+---
+
+## Description como prompt engineering
+
+La `description` de una herramienta es un prompt para el LLM. No es documentacion
+para humanos. Disenarla como instruccion de activacion:
+
+### Estructura de una description efectiva
+
+```
+[QUE hace en 1 oracion]
+[CUANDO usarla — condiciones de activacion]
+[CUANDO NO usarla — desambiguacion con herramientas similares]
+[RESTRICCIONES criticas si las hay]
+```
+
+### Ejemplo concreto
+
+```
+MAL:
+  description: "Lee un archivo del sistema de archivos."
+
+BIEN:
+  description: "Lee el contenido de un archivo por su ruta absoluta.
+  Usar para archivos de texto, codigo fuente, JSON, YAML y Markdown.
+  Para archivos binarios (imagenes, PDFs) usar read_binary en su lugar.
+  Limite: 2000 lineas por defecto; usar offset/limit para archivos grandes."
+```
+
+### Regla de los 100 tokens
+
+La description de una herramienta debe tener entre 50 y 100 tokens. Menos de 50
+no da suficiente contexto de activacion. Mas de 100 consume contexto sin beneficio
+proporcional.
+
+---
+
+## Naming de herramientas MCP
+
+Para servidores MCP, el nombre de la herramienta sigue el patron:
+`ServerName:tool_name`
+
+Reglas de naming:
+- `tool_name` en snake_case (no kebab-case, no camelCase)
+- Verbo + sustantivo: `search_files`, `create_issue`, `read_document`
+- Sin prefijos redundantes: `github:github_create_issue` es redundante;
+  usar `github:create_issue`
+- Maximo 64 caracteres para el nombre completo
+
+---
+
+## Diseno de mensajes de error para agentes
+
+Los mensajes de error de las herramientas son INSTRUCCIONES para el agente sobre
+como recuperarse. No son mensajes para humanos.
+
+### Estructura de un error accionable
+
+```json
+{
+  "error": "ARCHIVO_NO_ENCONTRADO",
+  "message": "El archivo src/main.py no existe",
+  "recovery": "Verificar la ruta con search_files antes de intentar leer.
+               Rutas similares encontradas: src/app/main.py, src/core/main.py"
+}
+```
+
+### Principios
+
+1. **Incluir sugerencia de recovery**: El agente necesita saber queii hacer despues
+2. **Ofrecer alternativas**: Si la accion fallo, sugerir acciones correctivas concretas
+3. **No exponer internals**: Stack traces no ayudan al agente; acciones si
+4. **Mensajes como reask**: Enviar el error como contexto para que el LLM reformule
+   su siguiente intento (patron reask), no repetir el mismo call identico
+
+---
+
+## Integracion con el sistema SWL
+
+### toolBudget en agentes
+
+El campo `toolBudget` en frontmatter define limites por complejidad de tarea:
+
+```yaml
+toolBudget:
+  simple: 10    # tareas de busqueda, lectura
+  standard: 20  # implementacion de 1 slice
+  complex: 35   # refactor multi-archivo
+```
+
+El diseno de herramientas afecta directamente el presupuesto: herramientas bien
+consolidadas permiten hacer mas con menos calls.
+
+### toolsRequeridos en skills
+
+Los skills pueden declarar `toolsRequeridos` en frontmatter para indicar queii
+herramientas necesitan. Esto permite al orquestador verificar que el agente
+asignado tiene acceso a esas herramientas antes de delegarle la tarea.
+
+### Evaluacion de colecciones
+
+Antes de agregar una herramienta nueva a un agente, verificar:
+1. No hay otra herramienta que ya cubra el caso de uso (consolidacion)
+2. La description sigue el patron de activacion (no solo describe)
+3. Los errores incluyen recovery actions
+4. El total de herramientas no supera 20 por agente
+
+---
+
+## Anti-patrones
+
+- **Tool sprawl**: Agregar herramientas sin consolidar las existentes
+- **Description generica**: "Hace cosas con archivos" — no activa correctamente
+- **Error opaco**: "Error 500" sin sugerencia de recovery
+- **Herramienta monolitica**: Una sola herramienta con 30 parametros opcionales
+- **Duplicacion cross-agente**: La misma herramienta implementada distinto en 3 agentes
+- **Retry ciego**: Reintentar la misma llamada identica ante un error — usar reask
+
+## Cuándo NO cargar
+
+- Se implementa el handler de un PreToolUse o PostToolUse — este skill diseña la interfaz, no el código del hook. Para hooks cargar la regla `hooks.md` o el agente que corresponda.
+- Se evalúa el rendimiento histórico de un agente específico (tasa de éxito, latencia) — eso es `evaluacion-agentes`, no diseño de colección.
+- El único cambio pendiente es corregir el texto de la descripción de una tool existente sin rediseñar la colección — el costo de carga no compensa.
+- Se configuran `permisosRed`, `permisosEscritura` o `nivelRiesgo` en el frontmatter de un agente — esas decisiones caen en `seguridad-agentes` y `estructura-proyecto-claude`.
+
+## Gotchas / Errores comunes no obvios
+
+- **Description escrita para un humano, no para un LLM**: la descripción dice "Ejecuta comandos de sistema operativo" en vez de "Úsala cuando necesites ejecutar comandos de shell, manipular archivos o instalar dependencias". El LLM necesita saber cuándo activar la tool, no solo qué hace. Causa: confundir documentación para desarrolladores con prompt de activación. Solución: comenzar la description con el disparador de uso ("Úsala cuando...", "Llama esto cuando...") y mencionar los casos de uso concretos que activan la herramienta.
+- **Consolidación que rompe el límite de parámetros**: al consolidar tres tools en una, el parámetro `accion` acepta 15 valores posibles y el LLM los confunde. Causa: consolidar sin rediseñar la interfaz — la herramienta resultante hereda toda la complejidad de las tres. Solución: verificar después de consolidar que la interfaz resultante tiene ≤6 parámetros y ≤5 valores por enum; si no cabe, la consolidación está sobre-agrupando.
+- **Error `recovery` genérico ("intenta de nuevo")**: el agente reintenta la misma llamada idéntica y falla de nuevo. Causa: el campo `recovery` dice "Reintenta más tarde" sin indicar qué debe cambiar. Solución: el `recovery` debe describir la acción correctiva específica ("Verificar que el archivo existe antes de llamar", "Reducir el campo `limit` a menos de 100").
+- **Naming MCP sin prefijo de servidor**: la tool `buscar_documentos` de un MCP server colisiona con otra tool local del mismo nombre. Causa: no seguir el formato `ServidorMCP:nombre_tool`. Solución: en MCP servers siempre usar `NombreServidor:accion_sustantivo`; el `:` no es opcional aunque el servidor solo tenga una tool.
+- **toolBudget `complex: 35` ignorado porque el agente no lo valida**: el orquestador asigna una tarea simple a un agente que usó 42 tool calls. Causa: `toolBudget` solo es efectivo si el hook de validación o el agente lo respeta activamente; declararlo en frontmatter sin lógica que lo cumpla no tiene efecto. Solución: verificar que el agente o el hook de control de presupuesto lee el campo `toolBudget` del frontmatter antes de asumir que el límite se aplicará automáticamente.

package/habilidades/diseno-responsivo/SKILL.md

@@ -0,0 +1,186 @@
+---
+name: diseno-responsivo
+description: Diseño responsivo moderno. Container queries, fluid typography, CSS Grid, Flexbox, mobile-first, Tailwind CSS y patrones para interfaces adaptativas.
+version: "1.0.0"
+herramientasPermitidas: [Read, Grep]
+evolvable: true  # default para skill estandar
+exclusiones:
+  - "No cargar para sistemas de design tokens (paletas de colores, tipografía de marca, theming) — para tokens cargar `design-tokens`."
+  - "No cargar para accesibilidad (ARIA, contraste, lector de pantalla) — para a11y cargar `accesibilidad-a11y`."
+  - "No cargar para optimización de rendimiento de imágenes en el pipeline de build (WebP, AVIF, compresión) — para imágenes en build cargar el skill de rendimiento del framework."
+  - "No cargar para CSS de componentes individuales sin responsividad (estilos fijos de un card o modal) — cargar `css-moderno` para CSS de componente."
+---
+# Diseño Responsivo Moderno
+
+## Cuándo NO cargar
+
+- La tarea es definir el sistema de design tokens (paletas, tipografía de marca, theming light/dark): cargar `design-tokens`.
+- La revisión es de accesibilidad (contraste WCAG, ARIA, lectores de pantalla): cargar `accesibilidad-a11y`.
+- La optimización es del pipeline de imágenes en build (WebP, AVIF, lazy loading en Next.js): cargar el skill de rendimiento del framework.
+- El CSS es de componentes fijos sin comportamiento adaptativo: cargar `css-moderno`.
+
+## Filosofía mobile-first
+
+El diseño mobile-first significa escribir los estilos base para pantallas pequeñas
+y luego agregar complejidad para pantallas más grandes mediante breakpoints.
+
+```css
+/* MAL: desktop-first — sobreescribir para móvil es más complejo */
+.tarjeta {
+  display: grid;
+  grid-template-columns: 1fr 1fr 1fr;
+}
+@media (max-width: 768px) {
+  .tarjeta { grid-template-columns: 1fr; }
+}
+
+/* BIEN: mobile-first — agregar complejidad progresivamente */
+.tarjeta {
+  display: grid;
+  grid-template-columns: 1fr;
+}
+@media (min-width: 768px) {
+  .tarjeta { grid-template-columns: 1fr 1fr; }
+}
+@media (min-width: 1024px) {
+  .tarjeta { grid-template-columns: 1fr 1fr 1fr; }
+}
+```
+
+---
+
+## Breakpoints estándar (Tailwind CSS)
+
+```
+sm:   640px  — Teléfonos en horizontal
+md:   768px  — Tablets
+lg:   1024px — Laptops / pantallas pequeñas
+xl:   1280px — Desktops
+2xl:  1536px — Pantallas grandes
+```
+
+```html
+<!-- Tailwind mobile-first: sin prefijo = base -->
+<div class="grid grid-cols-1 sm:grid-cols-2 lg:grid-cols-3 gap-4 p-4">
+  <!-- Cards -->
+</div>
+```
+
+---
+
+## CSS Grid auto-responsive sin breakpoints
+
+```css
+.grid-auto-fill {
+  display: grid;
+  grid-template-columns: repeat(auto-fill, minmax(280px, 1fr));
+  gap: 1.5rem;
+}
+```
+
+Para layouts completos de página con Grid y Flexbox, ver [recursos/ejemplos-layouts.md](recursos/ejemplos-layouts.md).
+
+---
+
+## Container Queries — el futuro del diseño responsivo
+
+Container queries permiten aplicar estilos basados en el tamaño del **contenedor**,
+no de la ventana. Esencial para componentes verdaderamente reutilizables.
+
+```css
+.card-contenedor {
+  container-type: inline-size;
+  container-name: card;
+}
+
+.card {
+  display: flex;
+  flex-direction: column;
+}
+
+@container card (min-width: 400px) {
+  .card {
+    flex-direction: row;
+  }
+  .card-imagen {
+    width: 40%;
+    flex-shrink: 0;
+  }
+}
+
+@container card (min-width: 600px) {
+  .card-acciones {
+    display: flex;
+    justify-content: flex-end;
+    gap: 0.5rem;
+  }
+}
+```
+
+---
+
+## Tipografía fluida
+
+La tipografía fluida elimina los saltos abruptos de tamaño entre breakpoints.
+
+```css
+/* Escala linealmente de 1rem (320px) a 1.5rem (1200px) */
+.titulo-principal {
+  font-size: clamp(1rem, 0.75rem + 1.25vw, 1.5rem);
+}
+
+/* Escala de tipo fluida completa */
+:root {
+  --text-sm:   clamp(0.75rem,  0.7rem  + 0.25vw, 0.875rem);
+  --text-base: clamp(1rem,     0.9rem  + 0.5vw,  1.125rem);
+  --text-lg:   clamp(1.125rem, 1rem    + 0.625vw, 1.25rem);
+  --text-xl:   clamp(1.25rem,  1.1rem  + 0.75vw,  1.5rem);
+  --text-2xl:  clamp(1.5rem,   1.25rem + 1.25vw,  2rem);
+  --text-3xl:  clamp(1.875rem, 1.5rem  + 1.875vw, 2.25rem);
+}
+```
+
+---
+
+## Imágenes responsivas — reglas clave
+
+- Usar `srcset` y `sizes` para servir la imagen del tamaño adecuado.
+- SIEMPRE `loading="lazy"` y `decoding="async"` en imágenes fuera del viewport.
+- SIEMPRE atributos `width` y `height` para evitar layout shift.
+- Usar `<picture>` para art direction (recortes distintos por breakpoint).
+
+Para ejemplos completos de imágenes y patrones Tailwind, ver [recursos/ejemplos-layouts.md](recursos/ejemplos-layouts.md).
+
+---
+
+## Accesibilidad y responsivo — reglas clave
+
+- Botón de menú móvil SIEMPRE con `aria-label`, `aria-expanded` y `aria-controls`.
+- Respetar `prefers-reduced-motion: reduce` desactivando animaciones.
+- Áreas táctiles mínimas de 44x44px en móvil.
+
+Para ejemplos completos de accesibilidad responsiva, ver [recursos/ejemplos-layouts.md](recursos/ejemplos-layouts.md).
+
+---
+
+## Checklist de diseño responsivo
+
+- [ ] El diseño base está en mobile (sin prefijo en Tailwind).
+- [ ] Tipografía usa clamp() o escala fluida.
+- [ ] Las imágenes tienen srcset y loading="lazy".
+- [ ] Los formularios tienen labels visibles en todas las pantallas.
+- [ ] Los botones/links tienen área táctil mínima de 44x44px.
+- [ ] No hay overflow horizontal en ningún breakpoint.
+- [ ] El espaciado usa variables relativas (rem, em) no píxeles fijos.
+- [ ] Se probó en orientación portrait y landscape.
+- [ ] Los componentes reutilizables usan container queries donde aplica.
+
+## Gotchas / Errores comunes no obvios
+
+**`container-type: inline-size` en un elemento `position: relative` rompe los `position: fixed` de sus descendientes**: cuando un elemento tiene `container-type`, crea un nuevo contexto de contención que convierte cualquier `position: fixed` dentro de él en `position: absolute` relativo al contenedor. Causa: el spec de CSS Container Queries especifica que los contenedores crean contexto de contención y eso afecta a los elementos fijos. Fix: no usar `container-type` en wrappers que tengan descendientes con `position: fixed` (modales, tooltips, dropdowns). Para esos casos, usar un wrapper contenedor hermano en lugar de padre.
+
+**`clamp()` con unidades `vw` produce tipografía que se escala incorrectamente cuando el usuario hace zoom en el browser**: `font-size: clamp(1rem, 2vw, 2rem)` usa `vw` que es relativo al viewport, no al zoom del usuario. Al hacer zoom al 200%, `vw` se reduce proporcionalmente y la fuente puede quedar más pequeña de lo esperado. Causa: `vw` no respeta el factor de zoom del usuario — es siempre relativo al viewport físico. Fix: usar `vi` (inline size) o combinar con `em` en la expresión media: `clamp(1rem, 0.5rem + 1vw + 0.5em, 2rem)` para que el componente `em` escale con el zoom del usuario.
+
+**El breakpoint `md:` de Tailwind (`768px`) no corresponde al breakpoint de tablet real en 2026**: en 2026, las tablets más comunes tienen resoluciones de `820px` (iPad Air) o `912px` (Surface), no `768px`. Usar `md:` para "layout de tablet" produce un layout desktop que se activa en pantallas de teléfono grande. Causa: los breakpoints de Tailwind son históricos y no reflejan los viewports actuales de dispositivos. Fix: usar container queries en lugar de media queries para componentes que deben adaptarse al espacio disponible, no al tamaño del viewport. Para layouts de página, considerar breakpoints personalizados en `tailwind.config.js` basados en los dispositivos reales del público objetivo.
+
+**`srcset` con `sizes` incorrecto hace que el browser descargue la imagen en resolución incorrecta aunque el `srcset` tenga los tamaños correctos**: `sizes="(max-width: 768px) 100vw, 50vw"` le dice al browser que en desktop la imagen ocupa 50% del viewport. Si la imagen realmente ocupa 33%, el browser descarga una imagen más grande de lo necesario, desperdiciando ancho de banda. Causa: el atributo `sizes` es una instrucción al browser, no un cálculo automático. Fix: medir el ancho real que ocupa la imagen en cada breakpoint con las DevTools y usar ese valor en `sizes`. Un error en `sizes` no rompe el render (el browser usa el `src` como fallback) pero sí afecta el rendimiento.

package/habilidades/diseno-responsivo/recursos/ejemplos-layouts.md

@@ -0,0 +1,156 @@
+# Diseño Responsivo — Ejemplos completos de layouts
+
+## CSS Grid — Layout de página completo
+
+```css
+.layout-app {
+  display: grid;
+  grid-template-areas:
+    "header"
+    "main"
+    "footer";
+  grid-template-rows: auto 1fr auto;
+  min-height: 100vh;
+}
+
+@media (min-width: 1024px) {
+  .layout-app {
+    grid-template-areas:
+      "sidebar header"
+      "sidebar main"
+      "sidebar footer";
+    grid-template-columns: 260px 1fr;
+  }
+}
+
+header { grid-area: header; }
+main   { grid-area: main;   }
+footer { grid-area: footer; }
+.sidebar { grid-area: sidebar; }
+```
+
+---
+
+## Flexbox para componentes
+
+```css
+/* Navegación responsiva */
+.nav {
+  display: flex;
+  flex-direction: column;
+  gap: 0.5rem;
+}
+
+@media (min-width: 768px) {
+  .nav {
+    flex-direction: row;
+    align-items: center;
+    justify-content: space-between;
+  }
+}
+
+/* Tarjeta con footer pegado al fondo */
+.tarjeta {
+  display: flex;
+  flex-direction: column;
+  height: 100%;
+}
+
+.tarjeta-cuerpo {
+  flex: 1;  /* Ocupa el espacio disponible */
+}
+
+.tarjeta-footer {
+  margin-top: auto;  /* Siempre al fondo */
+}
+```
+
+---
+
+## Imágenes responsivas
+
+```html
+<!-- srcset para diferentes densidades de pantalla -->
+<img
+  src="imagen-800w.jpg"
+  srcset="imagen-400w.jpg 400w, imagen-800w.jpg 800w, imagen-1200w.jpg 1200w"
+  sizes="(max-width: 640px) 100vw, (max-width: 1024px) 50vw, 33vw"
+  alt="Descripción de la imagen"
+  loading="lazy"
+  decoding="async"
+  width="800"
+  height="600"
+/>
+
+<!-- Picture para art direction -->
+<picture>
+  <source media="(min-width: 1024px)" srcset="imagen-horizontal.webp" />
+  <source media="(min-width: 640px)" srcset="imagen-cuadrada.webp" />
+  <img src="imagen-vertical.jpg" alt="Imagen del producto" />
+</picture>
+```
+
+---
+
+## Patrones Tailwind para layouts comunes
+
+```html
+<!-- Sidebar + contenido -->
+<div class="flex min-h-screen">
+  <aside class="w-64 shrink-0 hidden lg:block bg-gray-800 text-white">
+    <!-- Sidebar -->
+  </aside>
+  <main class="flex-1 overflow-auto p-6">
+    <!-- Contenido -->
+  </main>
+</div>
+
+<!-- Dashboard con cards -->
+<div class="grid grid-cols-1 sm:grid-cols-2 xl:grid-cols-4 gap-4">
+  <!-- Métrica 1 -->
+  <!-- Métrica 2 -->
+</div>
+
+<!-- Formulario de dos columnas en pantallas grandes -->
+<form class="grid grid-cols-1 md:grid-cols-2 gap-6">
+  <div class="md:col-span-2"><!-- Campo de ancho completo --></div>
+  <div><!-- Campo izquierdo --></div>
+  <div><!-- Campo derecho --></div>
+</form>
+
+<!-- Hero section centrado -->
+<section class="flex flex-col items-center justify-center min-h-[60vh] text-center px-4">
+  <h1 class="text-3xl sm:text-4xl lg:text-5xl font-bold max-w-3xl">Título</h1>
+  <p class="mt-4 text-lg text-gray-600 max-w-xl">Subtítulo descriptivo.</p>
+</section>
+```
+
+---
+
+## Accesibilidad y responsivo
+
+```html
+<!-- Botón de menú móvil con aria apropiado -->
+<button
+  aria-label="Abrir menú de navegación"
+  aria-expanded="false"
+  aria-controls="nav-mobile"
+  class="lg:hidden p-2"
+>
+  <svg ...>...</svg>
+</button>
+
+<nav id="nav-mobile" class="hidden lg:flex" aria-label="Navegación principal">
+  <!-- Links -->
+</nav>
+```
+
+```css
+/* Preferencia de movimiento reducido */
+@media (prefers-reduced-motion: reduce) {
+  *, *::before, *::after {
+    animation-duration: 0.01ms !important;
+    transition-duration: 0.01ms !important;
+  }
+}
+```