feat: biblioteca de skills y agente arquitecto (TheDebugDuck)

.claude-plugin/marketplace.json

@@ -0,0 +1,14 @@
+{
+  "name": "evolith",
+  "description": "Marketplace de BeyondNet Tech: skills y agentes reutilizables para trabajar con IA en cualquier proyecto.",
+  "owner": {
+    "name": "BeyondNet Tech"
+  },
+  "plugins": [
+    {
+      "name": "evolith-skills",
+      "source": "./",
+      "description": "Skills y agentes reutilizables para trabajar con IA en cualquier proyecto."
+    }
+  ]
+}

.claude-plugin/plugin.json

@@ -0,0 +1,20 @@
+{
+  "name": "evolith-skills",
+  "version": "1.0.0",
+  "description": "Biblioteca de skills y agentes reutilizables: arquitectura, datos, operación, APIs, seguridad, código, IA y comunicación de decisiones. Formato Agent Skills (SKILL.md) legible por cualquier LLM.",
+  "author": { "name": "BeyondNet Tech" },
+  "homepage": "https://github.com/beyondnetcode/evolith-agent-skills",
+  "repository": "https://github.com/beyondnetcode/evolith-agent-skills",
+  "license": "MIT",
+  "keywords": ["skills", "arquitectura", "system-design", "adr", "resiliencia", "base-de-datos", "agentes"],
+  "skills": [
+    "./skills/arquitectura/",
+    "./skills/datos/",
+    "./skills/operacion/",
+    "./skills/apis/",
+    "./skills/seguridad/",
+    "./skills/codigo/",
+    "./skills/ia/",
+    "./skills/comunicacion/"
+  ]
+}

.github/workflows/validar.yml

@@ -0,0 +1,19 @@
+name: validar-skills
+
+on:
+  pull_request:
+  push:
+    branches: [main]
+
+jobs:
+  validar:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: Validar skills e índices generados
+        run: python3 scripts/build_catalog.py --check
+      - name: Pruebas de los scripts
+        run: python3 -m unittest discover -s tests -v

.gitignore

@@ -141,3 +141,12 @@ dist
 vite.config.js.timestamp-*
 vite.config.ts.timestamp-*
 .vite/
+
+# Sistema y Python
+.DS_Store
+__pycache__/
+*.pyc
+
+# Transcripciones descargadas (material de trabajo, no se versiona)
+transcripciones/
+.venv/

AGENTS.md

@@ -0,0 +1,48 @@
+# AGENTS.md — Protocolo para agentes y LLMs
+
+Este repositorio es una **biblioteca de skills**: conocimiento y procedimientos reutilizables que cualquier LLM o agente de código puede leer y aplicar en cualquier proyecto. No contiene una aplicación. Todo está en Markdown plano con frontmatter YAML, sin dependencias de una herramienta concreta.
+
+## 1. Descubrir
+
+Usa el primer índice que tu entorno pueda leer:
+
+| Índice | Para qué |
+|---|---|
+| [`catalog.json`](catalog.json) | Máquinas: nombre, categoría, descripción, ruta, versión, recursos y relaciones de cada skill y agente |
+| [`llms.txt`](llms.txt) | LLMs: lista enlazada y resumida por categoría |
+| [`skills/README.md`](skills/README.md) | Personas y agentes: catálogo navegable por categoría |
+
+Cada skill vive en `skills/<categoria>/<nombre>/SKILL.md`. Los agentes (roles que combinan skills) viven en `agents/`.
+
+## 2. Elegir
+
+- Compara la tarea con el campo `description` de cada skill: dice **qué resuelve y cuándo usarla**, incluidos casos en que el usuario no nombra el tema.
+- Si la tarea es un diagnóstico o una revisión de arquitectura y no sabes por dónde empezar, empieza por [`radar-arquitectura`](skills/arquitectura/radar-arquitectura/SKILL.md): enruta a la skill especializada.
+- Varias skills pueden aplicar a la vez; `metadata.relacionadas` indica combinaciones habituales.
+
+## 3. Aplicar (carga progresiva)
+
+1. Lee el `SKILL.md` elegido **completo**: contiene el método, las matrices de decisión, las preguntas de revisión y el formato de salida.
+2. Abre **solo** los archivos de `references/` que el `SKILL.md` indique para el caso concreto. Son detallados; cargarlos todos desperdicia contexto.
+3. Si la skill trae `scripts/`, ejecútalos en lugar de reimplementarlos (Python estándar, sin dependencias). Sus resultados son señales que se confirman leyendo el código.
+4. Entrega usando el **formato de salida** de la skill.
+
+## 4. Reglas de uso
+
+- **Precedencia:** las instrucciones del usuario y las reglas del proyecto donde trabajas (ADRs aceptados, stack autorizado, guías de estilo) prevalecen sobre una skill. Una skill aporta criterio; no autoriza tecnología ni decisiones por sí sola.
+- **Evidencia antes que afirmación:** cita archivo:línea, métrica o consulta. Lo que no puedas comprobar va como pregunta abierta.
+- **Precisión técnica:** las skills marcan con «(complemento)» el conocimiento añadido o corregido respecto de la fuente y enumeran simplificaciones que no deben repetirse. Respétalas.
+- **Idioma:** el contenido está en español; responde en el idioma del usuario.
+
+## 5. Si vas a modificar este repositorio
+
+- Sigue [`docs/estandar-de-skills.md`](docs/estandar-de-skills.md) y parte de [`plantillas/SKILL.template.md`](plantillas/SKILL.template.md).
+- `catalog.json`, `llms.txt`, `skills/README.md` y `skills/<categoria>/README.md` **se generan**: no los edites a mano.
+- Después de cualquier cambio ejecuta y deja en verde:
+
+  ```bash
+  python3 scripts/build_catalog.py
+  ```
+
+  En CI o antes de un commit: `python3 scripts/build_catalog.py --check` y, si tocaste scripts, `python3 -m unittest discover -s tests`.
+- Registra el origen de todo conocimiento nuevo en [`fuentes/`](fuentes/README.md).

CLAUDE.md

@@ -0,0 +1,6 @@
+@AGENTS.md
+
+## Notas para Claude Code
+
+- Este repositorio también es un plugin de Claude Code (`.claude-plugin/`). Las skills y el agente `arquitecto` quedan disponibles al instalarlo; ver [`docs/integracion.md`](docs/integracion.md).
+- Al trabajar **dentro** de este repositorio, valida siempre con `python3 scripts/build_catalog.py` antes de dar una tarea por terminada.

README.md

@@ -1,2 +1,72 @@
 # evolith-agent-skills
-Set of Agents Skills
+
+Biblioteca de **skills y agentes reutilizables** para trabajar con IA en cualquier proyecto. Cada skill es conocimiento accionable (método, matrices de decisión, preguntas de revisión, formato de salida) en Markdown plano con frontmatter estándar, así que la puede leer **cualquier LLM o agente**: Claude Code, Codex, Copilot, Cursor, Gemini o un chat al que le adjuntes los archivos.
+
+## Estructura
+
+```text
+evolith-agent-skills/
+├── AGENTS.md              # protocolo para agentes: descubrir, elegir y aplicar skills
+├── CLAUDE.md              # importa AGENTS.md para Claude Code
+├── llms.txt               # índice para LLMs (generado)
+├── catalog.json           # índice para máquinas (generado)
+├── skills/
+│   ├── categorias.json    # taxonomía (fuente de verdad)
+│   ├── README.md          # catálogo por categoría (generado)
+│   └── <categoria>/<skill>/
+│       ├── SKILL.md       # frontmatter + instrucciones
+│       ├── references/    # detalle bajo demanda
+│       └── scripts/       # herramientas deterministas
+├── agents/                # roles que combinan skills (p. ej. arquitecto)
+├── docs/                  # integración por herramienta y estándar de autoría
+├── plantillas/            # plantillas de skill y agente
+├── fuentes/               # origen y trazabilidad del conocimiento
+├── scripts/               # build_catalog.py (valida y genera índices) e instalar_skills.py
+├── tests/                 # pruebas de los scripts (unittest)
+└── .claude-plugin/        # empaquetado como plugin de Claude Code
+```
+
+## Catálogo
+
+Ver [`skills/README.md`](skills/README.md) (generado). Hoy: 10 skills en 8 categorías y el agente [`arquitecto`](agents/arquitecto.md), destilados de los 48 videos del canal TheDebugDuck ([fuente](fuentes/thedebugduck/README.md)).
+
+| Categoría | Skills |
+|---|---|
+| Arquitectura | `radar-arquitectura` (entrada), `estilos-arquitectonicos`, `consistencia-distribuida` |
+| Datos | `datos-persistencia` |
+| Operación | `resiliencia-operacion` |
+| APIs y contratos | `contratos-api` |
+| Seguridad | `seguridad-aplicaciones` |
+| Código | `diseno-de-codigo` |
+| IA | `sistemas-con-ia` |
+| Comunicación | `comunicar-decisiones` |
+
+## Uso rápido
+
+- **Claude Code:** instala el repo como plugin o enlaza las skills; ver [`docs/integracion.md`](docs/integracion.md).
+- **Otros agentes (Codex, Copilot, Cursor, Gemini…):** apunta el agente a [`AGENTS.md`](AGENTS.md) o copia/enlaza las carpetas de skills en la ruta que su herramienta lea; ver [`docs/integracion.md`](docs/integracion.md).
+- **Chat sin herramientas:** adjunta el `SKILL.md` de la skill (y las referencias que indique) y pide que lo aplique.
+
+Escáner de riesgos de arquitectura sobre cualquier repositorio (Python estándar):
+
+```bash
+python3 skills/arquitectura/radar-arquitectura/scripts/escanear_senales.py <ruta-del-repo>
+```
+
+## Añadir o cambiar skills
+
+1. Sigue [`docs/estandar-de-skills.md`](docs/estandar-de-skills.md) y parte de [`plantillas/`](plantillas/SKILL.template.md).
+2. Registra el origen en [`fuentes/`](fuentes/README.md).
+3. Valida, regenera índices y prueba:
+
+   ```bash
+   python3 scripts/build_catalog.py
+   ```
+
+   ```bash
+   python3 -m unittest discover -s tests
+   ```
+
+## Licencia
+
+[MIT](LICENSE) © 2026 BeyondNet Tech.

agents/arquitecto.md

@@ -0,0 +1,40 @@
+---
+name: arquitecto
+description: Arquitecto de software pragmático entrenado con el catálogo de TheDebugDuck (48 casos de producción). Úsalo para diagnosticar incidentes (lentitud, caídas, duplicados, pérdidas de datos), revisar diseños, PRs o repositorios en busca de riesgos, decidir topologías y patrones (monolito vs microservicios, Outbox, Saga, CQRS, caché, colas), y redactar ADRs o postmortems con trade-offs explícitos.
+tools: Read, Grep, Glob, Bash, Edit, Write, WebFetch
+skills:
+  - radar-arquitectura
+  - estilos-arquitectonicos
+  - consistencia-distribuida
+  - datos-persistencia
+  - resiliencia-operacion
+  - contratos-api
+  - seguridad-aplicaciones
+  - diseno-de-codigo
+  - sistemas-con-ia
+  - comunicar-decisiones
+---
+
+# Arquitecto
+
+Eres un arquitecto de software que razona desde el **mecanismo** (qué hace el motor, el runtime, el broker, la red) y no desde el nombre del patrón. Tu conocimiento base son las skills listadas en `skills:`; sus `references/` tienen el detalle de cada caso y se leen bajo demanda.
+
+> Portabilidad: si tu herramienta no precarga el campo `skills:`, localiza cada skill por su nombre en `catalog.json` (o en `skills/<categoria>/<nombre>/SKILL.md`) y lee su `SKILL.md` cuando la tarea lo requiera, empezando por `radar-arquitectura`.
+
+## Cómo trabajas
+
+1. **Empieza por `radar-arquitectura`**: decide si es diagnóstico (Modo A) o revisión preventiva (Modo B) y deriva a la skill especializada.
+2. **Evidencia antes que afirmación.** Cada riesgo lleva archivo:línea, métrica, log o consulta. Lo que no puedas probar va como pregunta abierta, no como hallazgo.
+3. **Pide los números que cambian la decisión**: volumen y crecimiento, ratio lectura/escritura, distribución (claves calientes, outliers), tamaño de equipo, SLO, motor y versión. Si faltan, declara el supuesto.
+4. **Una recomendación, no un menú.** Decide y justifica en una línea; lista alternativas solo dentro de un ADR.
+5. **Siempre trade-offs y "cuándo NO".** Toda recomendación dice qué se paga y en qué contexto sobra.
+6. **La solución mínima que hace imposible el estado incorrecto** (restricción, transacción, límite explícito) le gana a la que solo lo hace improbable.
+7. **Operable o no está terminado**: cada patrón propuesto trae su métrica, su alerta y su runbook.
+8. **Corrige simplificaciones.** Las skills marcan las afirmaciones de los videos que son imprecisas o dependen del motor; no las repitas.
+9. **Si el repositorio tiene un proceso de gobierno** (ADRs aceptados, registro de hallazgos, stack autorizado), respétalo: verifica ADRs existentes antes de decidir, registra lo que no se cierre y no propongas tecnología fuera del stack sin ADR.
+
+## Estilo de respuesta
+
+- Ejecutivo y directo: respuesta primero, viñetas cortas, sin relleno. Amplía solo si te lo piden.
+- Los artefactos documentales (ADR, postmortem, diseño) siguen su plantilla completa; usa `comunicar-decisiones` para su contexto y consecuencias.
+- Todo en español.