Diferencias

Muestra las diferencias entre dos versiones de la página.

--- cursos:sdd:02-skills-agentes-mcp [2026/10/19 16:21] – La skill desplegar pasa a llamarse despliegue: es documentación, no una acción claude
+++ cursos:sdd:02-skills-agentes-mcp [2026/10/26 14:18] (actual) – Borrado: dividido en 02-conceptos-basicos, 07-agentes y 08-skills claude
@@ Línea 1: / Línea 1: @@
-====== Skills, Agentes y MCP ======
-Son tres cosas distintas que se confunden porque aparecen juntas en cualquier conversación sobre IA, y porque las tres «amplían» lo que puede hacer el modelo. No compiten: son **capas de la misma pila**.
-<note tip>**Las //skills// son el saber hacer, MCP son las manos, y el agente es quien decide qué se hace a continuación.**</note>
-^ ^ Skills ^ MCP ^ Agentes ^
-| Para qué | Que la salida sea consistente | Conectar con sistemas externos | Ejecutar una tarea de principio a fin |
-| Qué es | Un fichero de instrucciones | Un protocolo y un servidor | Un modelo en un bucle con herramientas |
-| Quién define la lógica | Quien escribe el fichero | Quien programa el servidor | El desarrollador y el modelo, a medias |
-| Esfuerzo de montaje | Bajo: un markdown | Medio: hay un servidor que mantener | Alto |
-| Estado | No tiene | No tiene | Puede mantenerlo |
-| Depuración | Leer el fichero | Red y protocolo | Prompts, código y servicios a la vez |
-----
-===== 1. AGENTS.md =====
-''AGENTS.md'' es un markdown en la raíz del repositorio con las instrucciones fijas del proyecto: lo que le contarías a un compañero nuevo el primer día. **Se carga entero en todas las sesiones**, encaje o no con la tarea. Es un [[https://agents.md/|estándar abierto]]: el mismo fichero lo leen Claude Code, OpenCode, Codex, Cursor, Copilot o Gemini CLI.
-==== Pequeño: el detalle va en skills ====
-Como se paga en cada petición, ''AGENTS.md'' tiene que ser **pequeño**: solo lo imprescindible y un índice. El detalle se reparte en [[#skills|skills]], una por tema, y el agente carga solo la que necesita para la tarea.
-<sxh plain>
-AGENTS.md
-.claude/skills/
-├── producto/
-│   └── SKILL.md
-├── tecnologia/
-│   └── SKILL.md
-├── arquitectura/
-│   ├── SKILL.md
-│   ├── cliente.md
-│   └── servidor.md
-└── despliegue/
-    ├── SKILL.md
-    ├── desarrollo.md
-    └── produccion.md
-</sxh>
-Las que tiene que haber como mínimo:
-  * ''producto'': para qué sirve el producto, qué valor aporta y sus capacidades principales.
-  * ''tecnologia'': el stack, los frameworks, las decisiones técnicas y las restricciones del sistema completo.
-  * ''arquitectura'': organización de directorios, patrones de arquitectura y convenciones de nombres.
-  * ''despliegue'': cómo se despliega la aplicación, lo común a todos los entornos.
-Si hay varias arquitecturas, el ''SKILL.md'' se queda con lo común y cada una va en un fichero de apoyo dentro de la //skill//: ''cliente.md'', ''servidor.md'', ''movil.md''. Con el despliegue igual: ''desarrollo.md'' y ''produccion.md'' con lo propio de cada entorno.
-<sxh markdown;title:.claude/skills/arquitectura/SKILL.md>
----
-name: arquitectura
-description: Carpetas, patrones y nombres del proyecto. Usar antes de crear
-  cualquier clase o fichero.
----
-# Arquitectura
-- Un paquete por funcionalidad (`pedidos`, `clientes`), no por capa.
-- Los controladores solo validan y delegan: la lógica va en los servicios.
-Lee además `servidor.md` si tocas `servidor/` y `cliente.md` si tocas `cliente/`.
-</sxh>
-''AGENTS.md'' dice **cuándo** usar cada una:
-<sxh markdown;title:AGENTS.md>
-# Pedidos
-API REST de pedidos con cliente web. Compilar y probar: `./mvnw verify`.
-## Skills del proyecto
-Antes de empezar, lee la skill que necesite la tarea:
-- `.claude/skills/producto/SKILL.md`: antes de escribir o revisar una especificación.
-- `.claude/skills/tecnologia/SKILL.md`: antes de añadir una dependencia.
-- `.claude/skills/arquitectura/SKILL.md`: antes de crear cualquier clase o fichero.
-- `.claude/skills/despliegue/SKILL.md`: antes de tocar el despliegue.
-</sxh>
-<note important>**La //skill// sola no basta.** El agente la carga solo si decide que encaja con la tarea, y muchas veces no lo decide: en las [[https://vercel.com/blog/agents-md-outperforms-skills-in-our-agent-evals|pruebas de Vercel]] no llegó a usarse en más de la mitad de los casos. El índice de ''AGENTS.md'' está siempre en contexto, así que convierte esa decisión en una instrucción. Y como da la ruta del fichero, funciona también en un agente que no sepa de //skills//.</note>
-Cómo generar un primer ''AGENTS.md'' con ''/init'' y cómo mantenerlo: [[cursos:sdd:03-opencode#agentsmdlas_instrucciones_fijas_del_proyecto|AGENTS.md en OpenCode]].
-==== CLAUDE.md: no usarlo ====
-<note important>Existe también ''CLAUDE.md'', el fichero propio de Claude Code. **No lo uses**: si en una carpeta hay ''CLAUDE.md'', Claude Code lee solo ese y **deja de leer el ''AGENTS.md''** de esa misma carpeta, sin avisar. El equipo que usa otra herramienta ve unas normas y el que usa Claude Code ve otras.</note>
-Como basta con que alguien cree un ''CLAUDE.md'' para que el ''AGENTS.md'' deje de valer, se añade una **regla de arquitectura** (tema 7) que lo impida: un test que falla si aparece alguno en el repositorio.
-<sxh java;title:src/test/java/es/logongas/pedidos/arquitectura/SinClaudeMdTest.java>
-class SinClaudeMdTest {
-    @Test
-    void noHayNingunClaudeMd() throws IOException {
-        try (Stream<Path> ficheros = Files.walk(Path.of("."))) {
-            List<Path> claudeMd = ficheros
-                    .filter(f -> !f.startsWith("./target") && !f.startsWith("./.git"))
-                    .filter(f -> f.getFileName().toString().equalsIgnoreCase("CLAUDE.md"))
-                    .toList();
-            assertThat(claudeMd)
-                    .as("Las instrucciones van en AGENTS.md, no en CLAUDE.md")
-                    .isEmpty();
-        }
-    }
-}
-</sxh>
-----
-===== 2. Skills =====
-Una //skill// es una carpeta con un fichero de instrucciones que le dice al agente **cómo se hace** una tarea concreta en tu equipo. No es código: es contexto empaquetado y versionado.
-<sxh plain>
-.claude/skills/revisar-pr
-├── SKILL.md          <- las instrucciones
-└── checklist.md      <- material de apoyo, se carga solo si hace falta
-</sxh>
-<sxh markdown;title:.claude/skills/revisar-pr/SKILL.md>
----
-name: revisar-pr
-description: Revisa un pull request con el checklist del equipo. Usar cuando se pida revisar un PR, unos cambios o un diff.
----
-# Revisión de pull request
-. Leer la descripción del PR y comprobar que hay una issue enlazada.
-. Revisar contra checklist.md, en ese orden.
-. Clasificar cada hallazgo: bloqueante, recomendable o nota.
-. No comentar estilo: de eso ya se encarga el formateador.
-</sxh>
-Lo que hace que esto escale es **cómo se cargan**: de todas las //skills// instaladas, el agente lleva siempre en contexto solo el nombre y la descripción —dos líneas—, y el cuerpo entra únicamente cuando la tarea encaja. Por eso se pueden tener veinte sin llenar la ventana de contexto.
-<note important>La **descripción** es lo único que el modelo lee para decidir si la usa. Se escribe diciendo **cuándo** se aplica, no qué hace: «usar cuando se pida revisar un PR» funciona; «utilidades de revisión» no la activa nunca.</note>
-Dónde viven:
-  * ''.claude/skills/'' **en el proyecto**: viajan en el repositorio, se revisan en el PR y valen para todo el equipo. Es el caso normal. OpenCode también lee esta carpeta, así que una sola vale para las dos herramientas.
-  * ''~/.claude/skills/'' **en tu casa**: tus manías, en todos los proyectos.
-Los comandos ''/kiro-*'' del tema 11 son exactamente esto: cc-sdd instala el flujo SDD completo como //skills// dentro del proyecto.
-**Cuándo escribir una**: cuando algo se repite y sale distinto cada vez, cuando hay un procedimiento del equipo que hoy solo está en la cabeza de alguien, o para el detalle del proyecto que solo hace falta en algunas tareas ([[#pequenoel_detalle_va_en_skills|sección 1]]). Lo que no puede hacer una //skill// es **actuar**: solo guía cómo se actúa.
-----
-===== 3. Agentes =====
-Un agente es un modelo metido en un **bucle con herramientas**: piensa, actúa, observa el resultado y vuelve a decidir. La diferencia con un chat no es el modelo, es que **puede ver las consecuencias de lo que hace** y corregir.
-<uml>
-start
-:peticion;
-repeat
-  :decidir el paso siguiente;
-  if (hay una skill que aplica) then (si)
-    :cargarla y seguirla;
-  else (no)
-  endif
-  :usar una herramienta;
-  :observar el resultado;
-backward:seguir;
-repeat while (objetivo cumplido) is (no) not (si)
-:responder;
-stop
-</uml>
-En este curso los agentes aparecen de dos formas:
-  * **El agente de terminal** que usas tú: Claude Code, OpenCode, Codex (tema 3). El bucle lo lleva la herramienta.
-  * **Los subagentes**: agentes especializados que el principal lanza para un trozo del trabajo, cada uno con **su propia ventana de contexto**, sus herramientas y sus instrucciones. Esa ventana propia es la razón de fondo para usarlos, más que el paralelismo: es lo que permite abarcar un problema que no cabría en una sola conversación (tema 5, orquestador).
-Montar un agente es decidir cuatro cosas, y ninguna es el prompt:
-  - **Qué herramientas** puede usar, y cuáles no.
-  - **Cuándo para**: el criterio de terminado, comprobable (tema 4).
-  - **Qué presupuesto** tiene: vueltas, tiempo, dinero.
-  - **Qué pasa cuando falla** un paso: reintento, vuelta atrás o persona.
-----
-===== 4. MCP =====
-//Model Context Protocol// es un protocolo abierto para conectar agentes con sistemas externos a través de una interfaz común. La analogía es el USB-C: antes cada herramienta escribía su propio conector para cada servicio; con MCP se escribe **un servidor** y lo usa cualquier cliente que hable el protocolo.
-Un servidor MCP expone tres cosas:
-^ Qué expone ^ Qué es ^ Ejemplo ^
-| **Herramientas** | Acciones que el agente puede ejecutar | Crear una incidencia en Jira |
-| **Recursos** | Datos que puede leer | El esquema de la base de datos |
-| **Prompts** | Plantillas de petición preparadas | «Analiza esta consulta lenta» |
-**Cuándo hace falta**: el agente necesita datos vivos que no están ni en su entrenamiento ni en el repositorio —el estado de un pedido, una consulta a la base de datos de preproducción, el CRM—, o varias herramientas distintas necesitan acceder igual al mismo sistema.
-**Cuándo no**: si lo que hace falta es leer un fichero, buscar en el proyecto o lanzar un comando, el agente **ya lo hace** con sus herramientas nativas. Montar un servidor MCP para eso es infraestructura que mantener a cambio de nada.
-<note warning>Cada servidor conectado tiene dos costes que no se ven en el tutorial: **ocupa contexto** —las descripciones de todas sus herramientas viajan en cada petición, y son muchas líneas— y **amplía la superficie de ataque**, porque mete en la conversación texto que viene de fuera y herramientas que el modelo puede invocar solo. Conectar únicamente lo que se usa, y ver el tema 8.</note>
-----
-===== 5. Cómo se combinan =====
-En un sistema montado del todo trabajan las tres capas a la vez: **MCP** le da acceso a los sistemas, las **skills** le dicen cómo usarlos bien, y el **agente** lleva el hilo de lo que hay que hacer.
-^ El problema que tienes ^ Lo que necesitas ^
-| «Cada vez lo hace distinto» | Una //skill// |
-| «Se inventa los datos» o «no puede consultarlo» | Un servidor MCP |
-| «Son doce pasos y hay que decidir sobre la marcha» | Un agente |
-| «No sé por dónde empieza» | Ninguna de las tres: falta especificación (tema 10) |
-<note important>**Empieza siempre por las //skills//.** Cuestan un rato y un fichero de texto, y arreglan la mitad de los problemas que la gente intenta resolver montando un agente. MCP cuando de verdad haya que salir fuera. Agentes cuando haya un flujo de varios pasos que tiene que correr solo. Añadir complejidad es fácil; quitarla, no.</note>
-===== 6. Cómo se organiza AGENTS.md =====
-La [[#agentsmd|sección 1]] dice que ''AGENTS.md'' es un índice pequeño. Aquí va qué entra en él, dónde va todo lo demás y cómo se escriben las referencias para que funcionen igual en Claude Code y en OpenCode.
-==== Qué entra ====
-El agente **obedece** lo que pone el fichero: en el [[https://arxiv.org/abs/2602.11988|estudio de ETH Zurich]], cuando ''AGENTS.md'' nombra una herramienta, el agente la usa en casi todas las tareas, y si no la nombra, casi nunca. Pero el fichero encarece cada tarea más de un 20 %, y solo mejora el resultado cuando cuenta lo que no es estándar. Así que entra solo lo que vale **para todas las tareas** y **no se deduce del código**:
-  * **Una frase** con qué es el proyecto.
-  * **Órdenes** para compilar, probar y comprobar, si no son las habituales.
-  * **Convenciones que se apartan de lo normal**: las que el agente no adivinaría leyendo el código.
-  * **Límites**: lo que no se hace nunca y lo que se pregunta antes.
-  * **El índice de //skills//**, con cuándo leer cada una.
-Fuera: la descripción general del proyecto, el árbol de carpetas, la lista de dependencias y las reglas de estilo. Las tres primeras el agente las saca del propio código, y en el estudio no le ayudaron a encontrar antes los ficheros que tenía que tocar. El estilo lo impone el formateador, no un párrafo.
-<note important>**No dejes tal cual el ''AGENTS.md'' que genera ''/init''.** Mete justo lo que sobra: descripción, arquitectura y dependencias. Los ficheros generados por el modelo salen peor que los escritos a mano. Úsalo de borrador y recorta.</note>
-<sxh markdown;title:AGENTS.md>
-# Pedidos
-API REST de pedidos con cliente web.
-## Órdenes
-- Compilar y probar: `./mvnw verify`
-- Solo los tests del servidor: `./mvnw -pl servidor test`
-## Convenciones
-- Los importes son `BigDecimal` con escala 2; nunca `double`.
-- Los errores de negocio heredan de `ErrorDeNegocio`; los controladores no lanzan `RuntimeException`.
-- Cada requisito de `specs/` tiene al menos un test que cita su identificador (`R-12`).
-## Límites
-- No modifiques una migración ya aplicada: crea una nueva.
-- Pregunta antes de añadir una dependencia o de cambiar un requisito de `specs/`.
-## Skills del proyecto
-Explora primero el código que toca la tarea. Después lee la skill que necesite:
-- `.claude/skills/producto/SKILL.md`: antes de escribir o revisar una especificación.
-- `.claude/skills/tecnologia/SKILL.md`: antes de añadir una dependencia.
-- `.claude/skills/arquitectura/SKILL.md`: antes de crear cualquier clase o fichero.
-- `.claude/skills/despliegue/SKILL.md`: antes de tocar el despliegue.
-</sxh>
-Cabe en una pantalla, y así tiene que seguir: **menos de 200 líneas**, mejor menos de 60. Cada instrucción de más hace que el modelo cumpla peor todas las demás, no solo la nueva.
-==== Dónde va lo demás ====
-^ Qué es ^ Dónde va ^ Ejemplo ^
-| Lo que vale en todas las tareas | ''AGENTS.md'' raíz | «Los importes son ''BigDecimal''» |
-| Lo que vale solo en una carpeta | ''AGENTS.md'' de esa carpeta | ''servidor/src/test/AGENTS.md'': «los tests de integración crean los pedidos con ''PedidoFactory''; no se mockea el repositorio» |
-| El detalle que solo hace falta en algunas tareas | Una //skill// | ''arquitectura'', ''despliegue'' |
-| Un procedimiento que se lanza para una tarea concreta | Una //skill// | ''revisar-pr'' |
-| Lo que tiene que cumplirse siempre | Un test, el linter o un //hook// | ''SinClaudeMdTest'', el formateador |
-  * **''AGENTS.md'' por carpeta**: Claude Code y OpenCode lo cargan cuando el agente trabaja con ficheros de esa carpeta. Solo se crea si sus normas difieren de las de la raíz, y **no puede contradecirla**: cada herramienta los junta en un orden distinto, así que no está claro cuál gana.
-  * **Lo que tiene que cumplirse siempre** no va en ''AGENTS.md'': ahí es una petición, no una garantía. Si de verdad no puede fallar, un test que lo compruebe, como el de la [[#claudemdno_usarlo|regla de ''CLAUDE.md'']].
-==== Cómo se escriben las referencias ====
-Cada referencia lleva **la ruta entre comillas invertidas** y **cuándo leerla**. Nunca con ''@'':
-^ Referencia ^ Claude Code ^ OpenCode ^
-| ''`.claude/skills/arquitectura/SKILL.md`: antes de crear cualquier clase o fichero.'' | La lee cuando la tarea lo pide | La lee cuando la tarea lo pide |
-| ''@.claude/skills/arquitectura/SKILL.md'' | La carga entera al arrancar, en todas las sesiones | No la entiende: es texto |
-| ''Ver la skill de arquitectura.'' | No sabe cuándo leerla | No sabe cuándo leerla |
-<note warning>**El ''@'' anula el índice.** En Claude Code, ''@ruta'' importa el fichero al arrancar, así que un índice escrito con ''@'' carga todas las //skills// en cada sesión: lo mismo que meterlas en ''AGENTS.md''. El ejemplo de la [[https://opencode.ai/docs/rules/|documentación de OpenCode]] usa ''@'' y en Claude Code hace justo eso.</note>
-La condición se escribe con **las palabras con las que se pedirá la tarea** («antes de escribir o revisar una especificación»), sin «MUST» ni mayúsculas. En la [[https://vercel.com/blog/agents-md-outperforms-skills-in-our-agent-evals|prueba de Vercel]], «explora primero el proyecto y luego usa la //skill//» acertó más que «debes usar la //skill//»: con la orden tajante, el agente leía la documentación primero, seguía sus ejemplos sin mirar el proyecto y se dejaba cambios.
-Lo mismo vale para la ''description'' de cada //skill// ([[#skills|sección 2]]): las //skills// se activan casi por palabra clave. En la [[https://scottspence.com/posts/measuring-claude-code-skill-activation-with-sandboxed-evals|medición de Scott Spence]], con la palabra en el prompt se activaban casi siempre; con una forma genérica de pedirlo, entre un 20 y un 40 % de las veces.
-===== 7. Fuentes =====
-  * [[https://dzone.com/articles/mcp-vs-skills-vs-agents|MCP vs Skills vs Agents With Scripts: Which One Should You Pick?]]
-  * [[https://agents.md/|AGENTS.md]]: el estándar, con ejemplos y la lista de herramientas que lo leen.
-  * [[https://vercel.com/blog/agents-md-outperforms-skills-in-our-agent-evals|AGENTS.md outperforms skills in our agent evals]]: la prueba de Vercel. Índice en ''AGENTS.md'': 100 %; //skill// sola: 53 %; //skill// con instrucción explícita: 79 %. La //skill// no llegó a usarse en el 56 % de los casos.
-  * [[https://agentskills.io/specification|Specification - Agent Skills]]: el estándar de las //skills//: formato de ''SKILL.md'' y carga por niveles (descripción, cuerpo, ficheros de apoyo).
-  * [[https://dreaming.press/posts/agents-md-vs-agent-skills-evals.html|AGENTS.md vs Agent Skills evals]]: lectura crítica de la prueba de Vercel. Lo que decide es dónde está el aviso de cargar la documentación (siempre en contexto o a decisión del modelo), no el formato.
-  * [[https://scottspence.com/posts/measuring-claude-code-skill-activation-with-sandboxed-evals|Measuring Claude Code skill activation]]: otra medición. Sin ayuda, las //skills// se activan solas la mitad de las veces; cuando se activan, siempre es la correcta.
-  * [[https://aihero.dev/a-complete-guide-to-agents-md|A complete guide to AGENTS.md]]: ''AGENTS.md'' mínimo y el detalle en ficheros enlazados por tema; qué no meter en él.
-  * [[https://skills.cat/skills/heykvnzhao/dotfiles/agents-md-best-practices|agents-md-best-practices]]: //skill// que parte un ''AGENTS.md'' grande en un índice y un fichero por tema.
-  * [[https://github.com/opsmill/infrahub-sdk-python/pull/609|infrahub-sdk-python PR #609]]: caso real. Un ''CLAUDE.md'' de 317 líneas pasa a un ''AGENTS.md'' de 77 más un ''AGENTS.md'' por carpeta; después el repositorio añadió //skills// para sus procedimientos.
-  * [[https://www.humanlayer.dev/blog/writing-a-good-claude-md|Writing a good CLAUDE.md]]: por qué cada instrucción de más empeora el cumplimiento del resto, y la carpeta de documentos enlazada desde el índice.
-  * [[https://arxiv.org/abs/2602.11988|Evaluating AGENTS.md]]: estudio de ETH Zurich. Los ficheros de contexto encarecen más de un 20 % cada tarea y en general no mejoran el resultado; sí ayudan cuando cuentan prácticas no estándar del proyecto.
-  * [[https://code.claude.com/docs/en/memory|Claude Code: memory]]: menos de 200 líneas; los procedimientos y lo que vale solo para una parte del código, a //skills//; ''@ruta'' no ahorra contexto porque carga el fichero al arrancar.
-  * [[https://code.claude.com/docs/en/features-overview|Claude Code: features overview]]: cuándo usar el fichero de instrucciones, //skills//, subagentes o //hooks//; el reparto «el fichero dice qué seguir y la //skill// tiene la guía».
-  * [[https://claude.com/blog/steering-claude-code-skills-hooks-rules-subagents-and-more|Steering Claude Code]]: el fichero de instrucciones como índice que apunta a otros ficheros.
-  * [[https://www.anthropic.com/engineering/equipping-agents-for-the-real-world-with-agent-skills|Equipping agents for the real world with Agent Skills]]: por qué las //skills// se cargan por niveles y qué pueden llevar dentro (scripts, plantillas).
-  * [[https://opencode.ai/docs/rules/|OpenCode: rules]]: OpenCode no sigue solo las rutas que aparecen en ''AGENTS.md''; hay que decirle cuándo leer cada fichero.
-  * [[https://opencode.ai/docs/skills/|OpenCode: skills]]: en qué carpetas busca //skills//, ''.claude/skills/'' incluida.