Diferencias

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

--- cursos:sdd:02-skills-agentes-mcp [2026/10/19 14:46] – Añade apartado AGENTS.md: docs_agent, por qué no usar CLAUDE.md y test que lo impide 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. 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.
-  * En claude code
-<code>
-.claude/skills/revisar-pr
-├── SKILL.md          <- las instrucciones
-└── checklist.md      <- material de apoyo, se carga solo si hace falta
-</code>
-  * En opencode
-<code>
-.opencode/skills/revisar-pr
-├── SKILL.md          <- las instrucciones
-└── checklist.md      <- material de apoyo, se carga solo si hace falta
-</code>
-<code markdown>
----
-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.
-</code>
-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/'' o ''.opencode/skills/'' **en el proyecto**: viajan en el repositorio, se revisan en el PR y valen para todo el equipo. Es el caso normal.
-  * ''~/.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, o cuando hay un procedimiento del equipo que hoy solo está en la cabeza de alguien. Lo que no puede hacer una //skill// es **actuar**: solo guía cómo se actúa.
-----
-===== 2. 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. A diferencia de una //skill//, **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 docs_agent ====
-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 ficheros dentro de la carpeta ''docs_agent/'', y el agente lee únicamente el que necesita para la tarea, igual que el cuerpo de una //skill//.
-<sxh plain>
-AGENTS.md
-docs_agent/
-├── producto.md
-├── tecnologia.md
-├── arquitectura.md
-├── arquitectura_cliente.md
-├── arquitectura_servidor.md
-├── desplegar.md
-├── desplegar_desarrollo.md
-└── desplegar_produccion.md
-</sxh>
-Los ficheros que tiene que haber como mínimo:
-  * ''producto.md'': para qué sirve el producto, qué valor aporta y sus capacidades principales.
-  * ''tecnologia.md'': el stack, los frameworks, las decisiones técnicas y las restricciones del sistema completo.
-  * ''arquitectura.md'': organización de directorios, patrones de arquitectura y convenciones de nombres.
-  * ''desplegar.md'': cómo se despliega la aplicación, lo común a todos los entornos.
-Si hay varias arquitecturas, ''arquitectura.md'' se queda con lo común y cada una va en su fichero: ''arquitectura_cliente.md'', ''arquitectura_servidor.md'', ''arquitectura_movil.md''. Con el despliegue igual: ''desplegar_desarrollo.md'' y ''desplegar_produccion.md'' con lo propio de cada entorno.
-''AGENTS.md'' dice **cuándo** leer cada uno, igual que la descripción de una //skill//:
-<sxh markdown;title:AGENTS.md>
-# Pedidos
-API REST de pedidos con cliente web. Compilar y probar: `./mvnw verify`.
-## Documentación del proyecto
-Lee solo el fichero que necesite la tarea:
-- `docs_agent/producto.md`: qué hace el producto. Antes de escribir o revisar una especificación.
-- `docs_agent/tecnologia.md`: stack y restricciones técnicas. Antes de añadir una dependencia.
-- `docs_agent/arquitectura.md`: carpetas, patrones y nombres. Antes de crear cualquier clase o fichero.
-- `docs_agent/arquitectura_servidor.md`: además, si tocas `servidor/`.
-- `docs_agent/arquitectura_cliente.md`: además, si tocas `cliente/`.
-- `docs_agent/desplegar.md`: antes de tocar el despliegue; y `desplegar_desarrollo.md` o `desplegar_produccion.md` según el entorno.
-</sxh>
-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>
-----
-===== 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>
-===== 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.