Skip to content
Kevin Davila mascotkevindavila.dev> SOFTWARE ENGINEERES
AI•4 min read

Your first "pure" agent: markdown files only

Sin SDK, sin framework, sin servidor. Cuatro archivos de texto y un agente que funciona. Suena a truco, pero es la forma más rápida de entender qué es un agente de verdad: si no puedes explicarlo con markdown, todavía no lo entiendes.

Este es el que yo uso para trabajo personal y la mejor puerta de entrada antes de pasar a ADK o al AI SDK.

Por qué empezar sin framework

Porque el harness se ve. Cuando escribes tú cada pieza —instrucciones, tareas, verificación— entiendes qué hace el framework después. Además: es auditable (todo es texto y está en git), portátil (funciona en cualquier agente que lea el estándar) y barato (no hay infraestructura).

Y hay un motivo práctico: los frameworks esconden decisiones. Cuando algo falle, vas a necesitar saber qué escondían.

La anatomía: 4 archivos

petlog-demo-ai/
├── AGENTS.md                       # contexto: qué es el proyecto y sus reglas
├── TASKS.md                        # estado: la cola de trabajo del agente
├── .agents/
│   └── skills/
│       └── review-pr/
│           └── SKILL.md            # un procedimiento con nombre y descripción
└── docs/                           # contexto bajo demanda (punteros, no volcados)

1. AGENTS.md — el contexto. Qué es el proyecto, cómo se corre, cómo se prueba, qué está prohibido. Corto: si tiene 400 líneas, nadie lo lee (ni tú, ni el agente). Ojo con el footgun: no todos los agentes leen este archivo por sí solos; depende de que su harness esté configurado para hacerlo. → AGENTS.md vs CLAUDE.md vs rules

2. SKILL.md — un procedimiento. Un archivo con frontmatter (name, description) y los pasos. La descripción es lo que decide si se activa: si es vaga, la skill no se dispara; si es precisa, el agente la carga cuando toca.

---
name: review-pr
description: Revisa un pull request contra la checklist del proyecto. Úsalo cuando el usuario pida revisar un PR o antes de hacer merge.
---
# Review PR

1. Corre `pnpm test` y `pnpm lint`; si fallan, detente y reporta.
2. Revisa el diff contra `docs/review-checklist.md`.
3. Comenta los hallazgos con archivo y línea.
4. No apruebes si hay tests rojos o checklist incompleta.

3. TASKS.md — el estado. La cola de trabajo: pendientes, en curso, hechos. Es la memoria del agente y el objetivo del loop, en texto plano y versionado.

4. docs/ — el contexto bajo demanda. Documentación y decisiones. Se referencia, no se pega: el agente la lee cuando la necesita (progressive disclosure).

El loop, sin escribir código

El loop lo pone el agente anfitrión. Tú pones el contrato:

  1. Tomar la primera tarea de TASKS.md.
  2. Planear y escribir el plan en el propio archivo (transparencia).
  3. Implementar.
  4. Verificar: correr los tests o el script que el propio TASKS.md define como "hecho".
  5. Marcar la tarea como hecha y anotar qué quedó pendiente.

La regla que hace que esto funcione: cada tarea trae su definición de hecho. Sin verificación, esto es un generador de commits.

La pieza que casi todos saltan: verificación

En TASKS.md, cada tarea se escribe así:

## T-014 · Validar email duplicado al registrar
- Hecho cuando: `pnpm test auth` pasa y el error muestra "email ya registrado".
- Contexto: `docs/decisions/0007-auth.md`

Esa línea de "hecho cuando" convierte al agente en algo medible. Es el mismo principio de Anthropic: el agente necesita "ground truth" del entorno en cada paso. - Source: Building effective agents - Anthropic

Ventajas y límites

Ventajas: entiendes el harness, es auditable, portátil entre agentes, cero infraestructura, y el "código" son cuatro archivos de texto que puedes versionar como cualquier otro artefacto.

Límites: no ejecuta solo (necesita un agente anfitrión), no tiene una UI para tu equipo, y no escala a un producto con usuarios. Ahí es cuando pasas a un framework: ADK si quieres workflows y evaluación de serie, AI SDK si tu app vive en TypeScript.

La buena noticia: todo lo que aprendes aquí se traslada. Un harness bien pensado en markdown migra a código sin cambiar las decisiones.

Arma el tuyo hoy (5 pasos)

  1. Escribe AGENTS.md con 10-20 líneas: qué es, cómo se corre, cómo se prueba, qué está prohibido.
  2. Crea una skill con el procedimiento que más repites (revisar, documentar, migrar algo).
  3. Abre TASKS.md con 3 tareas y su "hecho cuando".
  4. Corre el agente y no toques nada mientras trabaja; anota dónde se perdió.
  5. Corrige el harness, no el prompt: casi siempre falta contexto, verificación o una descripción de skill más precisa.

Los skills que hoy instalo incluso por CLI (npx skills add ...) siguen el mismo formato de SKILL.md, lo que confirma la idea: el procedimiento vive en texto, el runtime lo pone quien lo ejecuta. - Source: AI Skills for Real Engineers - AI Hero

Si quieres el marco completo, esto es "agente mínimo" dentro de la guía Agentes: de cero a producción, y el concepto general está en Qué es un agente, de verdad.

¿Cuál es tu skill más repetido? Ese es tu primer SKILL.md, y sale esta semana. Cuéntame el tuyo en los comentarios.

Referencias

> More posts