Agentes locales y capacidades reutilizables

Una carpeta puede ser un proyecto

En nuestro computador reunimos apuntes, planillas, documentos y datos para estudiar o trabajar. Una carpeta puede organizar esos archivos alrededor de un objetivo y convertirse en un proyecto. Sus materiales permiten desarrollar el trabajo; sus resultados permiten revisar qué produjo una persona o un agente.

Un agente con acceso a la carpeta puede consultar sus archivos y producir material que quede guardado. Para que trabaje de forma útil necesita entender dónde están las fuentes, qué queremos obtener y qué condiciones debe respetar. En este contexto, un repositorio de información es una colección organizada de materiales de trabajo.

Estructura de una carpeta de estudio

mi-curso/
├── clases/
│   ├── clase-01.md
│   └── clase-02.md
├── fuentes/
│   └── lectura.pdf
└── resultados/

Los nombres entregan pistas sobre la función de cada archivo. En este ejemplo, clases/ reúne los apuntes, fuentes/ contiene una lectura y resultados/ recibe el material que elaboramos. La estructura facilita encontrar información y reconocer los productos del trabajo.

Imagina que un agente abre por primera vez tu carpeta de estudio o los documentos de una empresa. ¿Cómo le explicarías de qué trata el proyecto y orientarías su forma de trabajar? La organización de los archivos, las instrucciones del proyecto y las capacidades reutilizables contribuyen a ese contexto.

AGENTS.md: instrucciones para trabajar en el proyecto

AGENTS.md es un archivo Markdown que reúne instrucciones de proyecto para el agente. Puede indicar qué fuentes consultar, dónde guardar los resultados y qué condiciones cuidar. Mantener esas orientaciones en un archivo evita volver a escribirlas en cada conversación.

La aplicación incorpora el archivo al contexto según sus propias reglas. Su alcance es el proyecto y su prioridad depende de la aplicación y de las demás instrucciones recibidas. El pedido de una conversación entrega el objetivo del momento; las instrucciones persistentes describen cómo trabajar en ese proyecto.

Una convención compartida

Varias aplicaciones ofrecen instrucciones persistentes, con diferencias en su ubicación y lectura. La portabilidad exige comprobar el soporte de la herramienta elegida.

CLAUDE.md continúa vigente. Al compartir instrucciones entre aplicaciones conviene revisar cómo cada una las carga. La guía de Codex sobre AGENTS.md describe su convención de instrucciones globales y por proyecto.

Instrucciones situadas y observables

Podemos orientar un proyecto de estudio con instrucciones como las siguientes. Las rutas deben corresponder a las carpetas reales: el ejemplo supone que las lecturas están en fuentes/ y los apuntes en apuntes/.

AGENTS.md

# Trabajo en mi-curso

Usa las lecturas de fuentes/ y los apuntes de apuntes/.
Guarda el material nuevo en resultados/.
Conserva los archivos originales.
Vincula las afirmaciones a la fuente y su página o sección.
Si falta información, señala qué necesitamos conseguir.
Explica los conceptos antes de usar términos técnicos.

Una instrucción útil identifica un objeto, una acción y una condición observable. Esa precisión ayuda al agente a tomar decisiones y nos permite comprobar si cumplió el encargo.

La especificidad debe proteger un resultado que nos importa. También necesitamos dejar espacio para decidir: al resumir una lectura, el agente puede elegir una organización que ayude a comprenderla. Una secuencia demasiado rígida puede obligarlo a seguir un procedimiento poco adecuado para el encargo.

La carpeta también explica el trabajo

Los nombres, la estructura y el contenido de los archivos deberían explicar de qué trata el proyecto. Conviene mantener cada explicación cerca del material que describe. Un diccionario junto a una planilla puede explicar sus columnas; un ejemplo puede mostrar el informe esperado.

Estructura de encuesta-taller

encuesta-taller/
├── README.md
├── AGENTS.md
├── datos/
│   ├── respuestas.csv
│   └── diccionario.md
├── ejemplos/
│   └── informe-esperado.md
└── resultados/

AGENTS.md puede concentrarse en las instrucciones de trabajo para el agente. Si falta contexto general que no encaja en otro archivo, un README.md puede explicar el propósito del proyecto y cómo orientarse en la carpeta. Documentar un repositorio así es una práctica habitual de los desarrolladores que ayuda a cualquier persona que lo abra.

Reservemos las instrucciones persistentes para condiciones estables y relevantes: dónde están las fuentes, qué archivos cuidar y cómo reconocer un resultado revisable. Un encargo puntual puede ir en la conversación y los detalles de los datos pueden vivir junto a ellos. Después de probar el agente, revisamos qué reglas ayudaron y cuáles dificultaron el trabajo, usando casos y criterios de éxito concretos.

Skills: conocimiento que podemos reutilizar

Una Skill es una carpeta con conocimiento e instrucciones para realizar un tipo de trabajo. Su punto de entrada es SKILL.md. Puede incluir documentación, scripts y plantillas para entregar una capacidad reutilizable que el agente utilice cuando la tarea la requiera.

Por ejemplo, una Skill puede enseñar a preparar tarjetas a partir de una lectura. Las instrucciones orientan qué contenido elegir y cómo comprobarlo; un script produce la página HTML. El paquete reúne decisiones y herramientas que sabemos usar, ahorrando la necesidad de reconstruirlas para cada encargo.

La descripción del formato Agent Skills presenta la carpeta como una forma de distribuir instrucciones y recursos reutilizables.

De las herramientas a las capacidades

Un servidor MCP puede exponer herramientas, recursos y prompts. El cliente conecta al agente con esas capacidades; cada servidor ofrece las que necesita para su propósito.

Las descripciones de muchas herramientas pueden consumir una parte importante del contexto. Algunas aplicaciones ofrecen descubrimiento progresivo: el agente encuentra las herramientas relevantes y obtiene sus detalles cuando hacen falta. El comportamiento concreto depende del cliente.

El diagrama ilustra la diferencia entre cargar muchas definiciones de entrada y cargar las pertinentes para una tarea. Sus cantidades de tokens representan el ejemplo mostrado; el costo real depende de las herramientas y de cómo la aplicación maneja el contexto.

Los prompts de MCP permiten reutilizar instrucciones preparadas con cuidado y orientar el uso de las herramientas de un servidor. Una Skill puede reunir un tipo de trabajo más amplio, con referencias, plantillas y código que utiliza varias herramientas. Es una forma de empaquetar conocimiento sobre cómo realizar ese trabajo. La documentación de MCP describe las tres capacidades.

La charla Don't Build Agents, Build Skills Instead presenta la idea de Skills desde el minuto 2:56.

Anatomía de una Skill

El archivo requerido es SKILL.md, ubicado directamente dentro de la carpeta. Las demás carpetas son convenciones para organizar material opcional. Una Skill sencilla puede quedar completa en su archivo principal.

Estructura de crear-documentos

crear-documentos/
├── SKILL.md
├── scripts/
│   └── exportar.py
├── references/
│   └── estructura.md
└── assets/
    └── plantilla.docx

El nombre de la Skill usa minúsculas y guiones, como crear-documentos. Para compartirla siguiendo el formato Agent Skills, ese nombre debe coincidir con el de su carpeta.

SKILL.md explica cuándo usar la capacidad, cómo trabajar y qué resultado esperamos. También indica qué script ejecutar o qué referencia consultar para un caso específico. Conviene mantenerlo breve y enlazar los detalles extensos: al activarla, el agente leerá el archivo principal completo.

Frontmatter: identificar la capacidad

El frontmatter es el bloque inicial de metadatos, escrito en YAML y delimitado por dos líneas de tres guiones. name identifica la Skill y description comunica qué hace y cuándo usarla. Ambos campos son obligatorios.

SKILL.md: frontmatter de crear-documentos

---
name: crear-documentos
description: Prepara documentos con la estructura de la organización. Úsala al crear o editar informes y actas.
---

La sintaxis requiere respetar los nombres de los campos, los dos puntos que separan cada nombre de su valor y la indentación. El ejemplo mantiene la descripción en una línea y evita introducir separadores adicionales dentro de ella. Los criterios de trabajo van después del bloque de metadatos, en el cuerpo Markdown.

Una descripción precisa permite que el agente reconozca cuándo la capacidad le sirve. Para la Skill del ejercicio, podemos describirla así:

SKILL.md: metadatos de estudiar

name: estudiar
description: Crea material de estudio a partir de fuentes del curso. Resúmenes, flashcards y preguntas de repaso. Úsala al preparar una sesión de estudio o revisar un tema.

La especificación de Agent Skills define los campos del formato. La descripción ayuda a seleccionar una capacidad; los criterios detallados pertenecen a sus instrucciones.

Progressive disclosure: cargar lo pertinente

Progressive disclosure, o carga progresiva, permite acceder al detalle cuando la tarea lo necesita. En el patrón de Skills, el agente conoce primero los nombres y las descripciones de las capacidades disponibles. Cuando activa una, lee su SKILL.md; después consulta las referencias o utiliza los scripts pertinentes.

Una descripción clara facilita descubrir la capacidad adecuada. Un archivo principal breve reduce el contexto que ocupa al activarla. Separar una referencia extensa permite consultarla en el momento en que aporta al trabajo. El agente debe encontrar en SKILL.md la indicación de cuándo abrir cada referencia.

El agente puede elegir una Skill al reconocer su relación con la tarea. También podemos pedir explícitamente que la use. La forma de invocarla y el lugar donde se instala dependen de la aplicación. En el ejercicio usaremos /estudiar; la barra inicial se conoce como slash.

Una ubicación habitual es .agents/skills/: dentro de ella se guarda la carpeta de cada Skill. La carpeta .agents comienza con un punto, por lo que puede aparecer oculta en el explorador de archivos. Algunos sistemas requieren activar la visualización de archivos ocultos. Debemos comprobar que nuestra aplicación reconoce esa ubicación.

La explicación de Skills de Anthropic desarrolla este patrón de carga progresiva.

Terminal, CLI y scripts

La terminal es una interfaz donde escribimos comandos y leemos sus resultados. La shell interpreta esos comandos. Una CLI, o command-line interface, permite usar un programa mediante comandos y argumentos: el comando indica una operación y los argumentos entregan los datos necesarios para realizarla.

Un agente con una herramienta de terminal puede solicitar la ejecución de programas. Estos corren en el entorno que le ofrece la aplicación, como nuestro computador o un entorno aislado. Para usar un script deben estar disponibles el programa que lo ejecuta, sus dependencias y los permisos correspondientes.

Distribuir una operación determinista

Una Skill puede incluir código para resolver una operación conocida. En nuestro ejemplo, el agente elige las preguntas y las respuestas; flashcards.py crea o modifica el HTML siguiendo reglas explícitas. El resultado queda en un archivo que podemos abrir y comprobar.

Esta distribución aprovecha al modelo para comprender la tarea y elegir el contenido, y al código para repetir una operación de forma consistente. Las instrucciones explican cómo pedir la operación y qué resultado esperar del programa.

Compatibilidad y permisos

El campo opcional compatibility permite describir requisitos del entorno. Por ejemplo, la capacidad para tarjetas requiere Python 3.10 o una versión posterior. Indicar el requisito ayuda a reconocer qué necesita la aplicación para ejecutar el script.

allowed-tools es otro campo opcional del formato, de carácter experimental. Puede declarar herramientas preaprobadas cuando la aplicación lo soporta. Su interpretación depende del cliente y de sus reglas de permisos. Ejecutar un programa exige que la herramienta exista y que el entorno permita utilizarla.

Compartir una Skill

Al compartir una Skill distribuimos los archivos que incluimos en su carpeta. Hay que revisar las instrucciones, scripts, ejemplos y plantillas antes de empaquetarlos. Las credenciales, los datos personales y los documentos confidenciales deben mantenerse fuera del paquete; las instrucciones pueden indicar cómo obtener acceso autorizado cuando haga falta.

Antes de instalar una Skill de otra persona, conviene leer qué instrucciones entrega, qué código ejecuta y a qué servicios se conecta. Esa revisión permite comprender el trabajo que estamos incorporando a nuestro agente.

Tools, Capacities y Workflows

Podemos diseñar una Skill con alcances distintos. Usaremos Tools, Capacities y Workflows como categorías de diseño del curso para decidir qué conocimiento queremos empaquetar. El estándar Agent Skills admite distintos enfoques, incluidos procedimientos secuenciales.

Una Skill centrada en una herramienta explica cómo utilizarla. Una Capacity reúne herramientas y contexto para realizar un tipo de trabajo. Una Skill centrada en un Workflow establece el orden de las etapas de un encargo completo.

Capacidades que se pueden combinar

Para preparar documentos de una organización podemos reunir su jerarquía documental, los elementos que debe contener un acta, los criterios para revisar un informe y un script que exporta el archivo.

Estructura de documentos-organizacion

documentos-organizacion/
├── SKILL.md
├── references/
│   ├── estructura.md
│   └── criterios.md
├── assets/
│   └── plantilla.docx
└── scripts/
    └── exportar.py

Las referencias entregan el contexto de la organización; la plantilla define una estructura de documento y el script se encarga de exportar el resultado. El agente selecciona los recursos según el documento solicitado.

En este diseño priorizamos capacidades reutilizables. Cada una resuelve una parte reconocible y atómica del trabajo, con condiciones que deben cumplirse. Editar un documento debe conservar la estructura requerida y entregar un archivo válido. El agente decide cómo aplicar esa capacidad dentro de un encargo mayor.

Podemos combinar capacidades para preparar un acta, producir un resumen y revisar sus fuentes. Definir las condiciones de cada pieza permite conservar criterios importantes y adaptar su uso a solicitudes distintas.

Playbooks para un flujo completo

Un playbook es una guía para completar un trabajo que reúne varias etapas y capacidades. Para este diseño, lo guardamos fuera de la Skill, como documentación del proyecto. El agente puede encontrar la guía y usar las Skills pertinentes en cada etapa.

Estructura de un proyecto con playbook

proyecto/
├── playbooks/
│   └── preparar-actividad.md
└── materiales/

Para preparar una actividad de jardín infantil sobre el ciclo del agua, el playbook podría organizar este recorrido:

1. Definir qué queremos que comprendan los niños y cómo observarlo.
2. Elegir una actividad adecuada a su edad y a los materiales disponibles.
3. Preparar el material con una capacidad para documentos o ilustraciones.
4. Revisar las instrucciones y los cuidados necesarios antes de realizarla.

La guía conecta las etapas y señala qué capacidades sirven en cada una. Una misma capacidad puede utilizarse en varios playbooks. Sus Skills se instalan en la ubicación que reconoce la aplicación; la guía indica sus nombres y cuándo usarlas.

Ejercicio: diseñar y comprobar /estudiar

Queremos transformar las fuentes de un curso en material de estudio que podamos usar y comprobar. /estudiar reúne capacidades para preparar flashcards, resúmenes y preguntas, y para observar qué temas dominamos y cuáles requieren práctica. Cada recurso debe poder revisarse contra las fuentes del curso.

Cada capacidad necesita instrucciones y un criterio para reconocer un resultado útil. El agente debe poder seleccionar la pertinente según el pedido y mantener esos criterios cuando cambie el encargo.

Material descargable y estructura

El ZIP de la Skill estudiar contiene el ejemplo completo: SKILL.md, la referencia de evaluación y el script de tarjetas. Descárgalo y descomprímelo para revisar sus archivos. Conserva la carpeta estudiar/ y su estructura al instalarla en la ubicación que admite tu aplicación.

Estructura de estudiar

estudiar/
├── SKILL.md
├── references/
│   └── evaluar-dominio.md
└── scripts/
    └── flashcards.py

SKILL.md reúne las capacidades para tarjetas, resúmenes y preguntas. También indica cuándo leer references/evaluar-dominio.md, que mantiene los criterios de evaluación en un documento separado. scripts/flashcards.py crea y modifica el HTML de las tarjetas.

Los siguientes fragmentos muestran las instrucciones que escribiríamos para cada capacidad. Se dirigen al agente y establecen cómo debe producir y comprobar su resultado.

Crear flashcards

Una tarjeta concentra un concepto con una pregunta al frente y una respuesta verificable al reverso. Las instrucciones cuidan el contenido y permiten intentar una respuesta antes de mostrar la solución. También indican cómo usar el script incluido en el paquete.

SKILL.md: capacidad para flashcards

## Crear flashcards

Diseña una tarjeta por concepto: pregunta al frente, respuesta verificable al reverso.
Agrupa por tema, cita la fuente y permite responder antes de revelar el reverso.

Gestiona el HTML con `scripts/flashcards.py` (Python 3.10+). Resuelve el script
desde la Skill y el HTML desde el proyecto. Consulta `--help` o inspecciona el código.
Cada operación exige `--path` del mismo HTML; su directorio de destino debe existir.

- `create-box --box ID --title TÍTULO`: crea una caja.
- `add-card --box ID --front HTML --back HTML`: agrega una tarjeta.
- `list [--box ID]`: obtiene cajas e IDs.
- `remove-card --box ID --card UUID`: elimina una tarjeta.
- `delete-box --box ID`: elimina la caja y sus tarjetas.

Codifica las caras con HTML sin atributos: párrafos, énfasis, listas y código.
Usa `--front-file` y `--back-file` para archivos UTF-8. Obtén los IDs de tarjetas
con `list` o `add-card`. Conserva las cajas ajenas a la operación.
Entrega la ruta del HTML y enumera las modificaciones.

Preparar un resumen

El resumen debe conservar las ideas centrales, sus relaciones y los matices que afectan su significado. Su organización y profundidad se ajustan al objetivo de estudio. Las referencias permiten comprobarlo y volver al contenido que requiere una lectura más detallada.

SKILL.md: capacidad para resúmenes

## Crear un resumen

Sintetiza **las ideas centrales y sus relaciones**, preservando significado,
alcance y matices. Ajusta extensión y profundidad al objetivo de estudio.

Organiza con títulos descriptivos y párrafos breves. Define conceptos e incorpora
ejemplos que aclaren su aplicación.

Referencia las fuentes y las secciones para profundizar. Señala contradicciones
y vacíos que afecten la comprensión.

Crear preguntas de alternativas

Las preguntas ofrecen una oportunidad de practicar antes de consultar la clave. Los distractores representan errores conceptuales plausibles; las explicaciones posteriores permiten comprender por qué una alternativa es correcta y qué revisar cuando nos equivocamos.

SKILL.md: capacidad para preguntas de alternativas

## Crear preguntas de alternativas

Formula preguntas alineadas con las fuentes y el objetivo de estudio, con
enunciados inequívocos y una única respuesta correcta fundamentada.

Diseña distractores basados en errores conceptuales plausibles. Mantén alternativas
comparables en extensión y precisión; elimina pistas que revelen la clave.

Presenta preguntas y alternativas; reserva clave y explicaciones hasta la respuesta
del estudiante. Después, justifica la opción correcta, explica el error de cada distractor
y referencia el contenido que conviene repasar.

Evaluar el dominio de los temas

La evaluación requiere un criterio y evidencia de las respuestas del estudiante. Según el objetivo, puede pedir recuperar información, explicarla o aplicarla. La referencia separada orienta la selección de tareas; el agente registra evidencias, errores y práctica recomendada por tema.

SKILL.md: capacidad para evaluar dominio

## Evaluar el dominio de los temas

Consulta [references/evaluar-dominio.md](references/evaluar-dominio.md) para seleccionar
criterios y tareas acordes con el objetivo de estudio.

Evalúa recuperación, explicación o aplicación según el criterio. Solicita
justificaciones y contrasta las respuestas con las fuentes.

Registra por tema evidencias, errores conceptuales y práctica recomendada.
Fundamenta el diagnóstico en varias respuestas y explicita la evidencia pendiente
para afirmar dominio. Usa la confianza declarada como dato complementario.

Comprobar la capacidad con una lectura breve

1. Elige una lectura breve del curso que puedas revisar y sitúala en la carpeta de fuentes del proyecto. Comprueba que tu aplicación reconoce la Skill y que permite ejecutar su script con Python 3.10 o posterior.
2. Pide usar /estudiar para producir tarjetas a partir de esa lectura. Indica la ruta del HTML de salida y asegúrate de que su carpeta de destino exista.
3. Revisa si el agente selecciona la capacidad pertinente, cita la fuente y entrega la ruta del archivo creado. Abre el HTML, intenta responder antes de revelar cada reverso y contrasta las respuestas con la lectura.
4. Cambia el pedido y solicita un resumen de la misma fuente. Comprueba si conserva las ideas centrales, sus relaciones y referencias al material.
5. Solicita evaluar el dominio de un tema y revisa si consulta la referencia correspondiente. Observa qué respuestas usa como evidencia y qué práctica recomienda.

La prueba permite comprobar si la capacidad se adapta a pedidos distintos conservando sus criterios. Si una instrucción produce resultados poco útiles, precisa la condición que falta y vuelve a comprobar el comportamiento con la lectura.