IA y Markdown: Cómo Configurar Agents, Skills y Prompts con el Lenguaje Universal

Si hace unos años Markdown era “eso que usaba GitHub para el README”, hoy es algo completamente diferente: es el lenguaje con el que se le dice a la IA qué hacer, cómo comportarse y qué contexto tener en cuenta. Y no es una moda pasajera — es la base sobre la que se construye toda la configuración de agentes de IA modernos.

En este post vamos a ver exactamente qué está pasando, cómo configurar las principales herramientas de IA con Markdown, y qué recursos hay para aprender todo esto desde cero.

Tabla de contenidos

• ¿Por qué Markdown para la IA?
• Los 8 agents de IA que se configuran con Markdown
• Skills: Instrucciones reutilizables
• System Prompts estructurados
• Patrones de diseño para prompts
• Recursos gratuitos para aprender
• Herramientas prácticas
• Tabla resumen

¿Por qué Markdown para la IA?

La razón es simple: Markdown es legible tanto para humanos como para máquinas. Un archivo .md puede contener instrucciones, estructura, ejemplos y contexto — y cualquier modelo de lenguaje lo entiende perfectamente.

Pero hay más razones:

• Versionado: al ser texto plano, puedes usar Git para trackear cambios en la configuración de tu agente
• Colaboración: cualquier miembro del equipo puede editar las reglas sin herramientas especiales
• Portabilidad: el mismo formato funciona en OpenCode, Cursor, Claude, Windsurf y casi cualquier herramienta
• Legibilidad: a diferencia de JSON o YAML, Markdown es fácil de leer y escribir sin formateo especial

Los principales desarrolladores de herramientas de IA lo entendieron y adoptaron Markdown como estándar. Hoy, 8 de las herramientas de IA más populares usan archivos Markdown para su configuración.

Los 8 agents de IA que se configuran con Markdown

1. OpenCode — AGENTS.md

OpenCode usa AGENTS.md como archivo principal de configuración. Puede estar en la raíz del proyecto o en .opencode/AGENTS.md.

# Instrucciones del proyecto

## Convenciones
- Usar TypeScript estricto con `strict: true`
- Funciones con tipos explícitos
- Tests con Vitest

## Arquitectura
- Componentes en `src/components/`
- Utilidades en `src/utils/`
- API routes en `src/api/`

Ubicaciones:

OpenCode también es compatible con CLAUDE.md como fallback, y puede leer skills de .claude/skills/.

2. Cursor — .cursor/rules/*.mdc

Cursor migró de .cursorrules (legacy) a un sistema de rules con frontmatter YAML:

---
description: Convenciones de React y TypeScript
globs: ["**/*.tsx", "**/*.ts"]
alwaysApply: false
---

# Reglas de React

- Usar functional components siempre
- Hooks personalizados en `src/hooks/`
- No usar `any` — tipar todo
- Componentes de menos de 200 líneas

4 modos de activación:

• Always Apply: se aplica a todas las conversaciones
• Auto-attached: se activa cuando el glob coincide con archivos abiertos
• Agent-requested: el agente decide cuándo usarlo según la descripción
• Manual: solo se activa con @mention

3. Claude Code — CLAUDE.md

Claude Code (Anthropic) usa CLAUDE.md como archivo de memoria principal:

# Proyecto: Mi App

## Stack
- Next.js 14 con App Router
- PostgreSQL + Prisma
- Despliegue en Vercel

## Reglas de código
- Funciones puras cuando sea posible
- Manejo de errores con try/catch explícito
- Comments solo en funciones públicas

## Comandos útiles
- `npm run dev` — desarrollo
- `npm run build` — producción
- `npx prisma studio` — base de datos

Archivos de Claude Code:

Claude también escribe automáticamente en MEMORY.md dentro de ~/.claude/projects/ con lo que aprende durante la sesión.

4. Windsurf — .windsurf/rules/*.md

Windsurf (Codeium) sigue un patrón similar a Cursor:

---
trigger: always_on
description: Reglas generales del proyecto
---

# Estándares del proyecto

- Python 3.11+ con type hints
- Tests con pytest
- Formatting con black
- Linting con ruff

Límites importantes:

• 12,000 caracteres totales en reglas del workspace
• 6,000 caracteres por archivo individual
• Reglas globales en ~/.codeium/windsurf/memories/global_rules.md (6KB max)

5. GitHub Copilot — .github/copilot-instructions.md

Copilot usa un enfoque diferente: .github/copilot-instructions.md para instrucciones repo-wide:

# Instrucciones para GitHub Copilot

## Convenciones
- Usar ES modules (import/export)
- Async/await sobre callbacks
- Funciones puras cuando sea posible

## Formato
- 2 espacios de indentación
- Punto y coma al final
- Comillas simples en strings

También soporta instrucciones por path:

# .github/instructions/python.instructions.md
---
applyTo: "**/*.py"
---
- Usar type hints en todas las funciones
- Docstrings en formato Google

6. Aider — CONVENTIONS.md

Aider usa CONVENTIONS.md como archivo de convenciones del proyecto:

# Convenciones del Proyecto

## Estilo
- Funciones cortas (máx 30 líneas)
- Nombres descriptivos en inglés
- Sin abreviaturas en nombres de variables

## Arquitectura
- Patrón Repository para acceso a datos
- Servicios para lógica de negocio
- Controladores para HTTP

## Tests
- Un test por comportamiento
- Mock externo de APIs
- Datos de test en fixtures/

Se carga con --read CONVENTIONS.md o en .aider.conf.yml:

read:
  - CONVENTIONS.md
  - ARCHITECTURE.md

7. Continue.dev — .continue/rules/*.md

Continue es open-source y usa archivos Markdown simples:

# Reglas de TypeScript

- Usar `const` y `let`, nunca `var`
- Tipar parámetros y retornos de funciones
- Evitar `any` — usar `unknown` si es necesario
- Funciones puras cuando sea posible

Ubicaciones:

8. Cline — .clinerules/

Cline carga todos los archivos .md y .txt de .clinerules/:

# Reglas de Cline

## Código
- TypeScript estricto
- Componentes funcionales React
- Tests con Vitest

## Comunicación
- Explicar cambios antes de hacerlos
- Preguntar antes de borrar código
- Mostrar progreso en pasos largos

Cline también lee .cursorrules, .windsurfrules y AGENTS.md como fallback.

Skills: Instrucciones reutilizables

Los skills son paquetes de instrucciones que un agente puede cargar bajo demanda. No son solo “reglas” — son módulos completos con scripts, referencias y metadatos.

Estructura de un Skill en OpenCode

.opencode/skills/
└── git-release/
    ├── SKILL.md          ← Instrucciones del skill
    ├── scripts/
    │   └── changelog.ts  ← Scripts auxiliares
    └── references/
        └── release-policy.md  ← Documentación de referencia

Ejemplo de SKILL.md

---
name: git-release
description: Crear releases y changelogs consistentes
license: MIT
compatibility: opencode
metadata:
  audience: maintainers
  workflow: github
---

## Qué hago
- Genero release notes a partir de PRs merged
- Propongo bump de versión según conventional commits
- Creo el tag y la release en GitHub

## Cuándo usarme
Úsame cuando estés preparando un release etiquetado.

## Requisitos
- Git inicializado
- Acceso a GitHub CLI (`gh`)
- PRs mergeados con títulos descriptivos

Reglas de naming para skills

• Solo minúsculas, números y guiones
• Guiones simples (no dobles)
• 1-64 caracteres
• El nombre debe coincidir con el directorio

Búsqueda de skills

OpenCode busca skills en múltiples ubicaciones:

1. .opencode/skills/ (proyecto)
2. .claude/skills/ (compatibilidad)
3. ~/.config/opencode/skills/ (global)
4. ~/.claude/skills/ (global Claude)
5. .agents/skills/ (estándar abierto)

La especificación está abierta en openagentskills.dev.

System Prompts estructurados

Un system prompt bien estructurado en Markdown tiene 4 capas:

# Identidad
Eres un asistente de código para el equipo de Backend.

# Capacidades
- Puedes leer y modificar archivos del proyecto
- Tienes acceso a la terminal
- Puedes ejecutar tests

# Restricciones
- No modifiquest archivos de configuración sin preguntar
- No hagas commit sin confirmación explícita
- No compartas secrets o credenciales

# Formato de salida
- Explica cada cambio antes de hacerlo
- Usa bloques de código para mostrar diff
- Responde en español

Patrones de diseño efectivos

XML tags para Claude (el parsing más fiable):

<instructions>
Usa type hints en todas las funciones de Python.
</instructions>

<examples>
def process(data: list[dict]) -> str:
    return json.dumps(data)
</examples>

<output>
JSON con campos: status, message, data
</output>

Headers Markdown para estructura:

# Rol
Eres un reviewer de código senior.

# Objetivo
Detectar bugs, code smells y vulnerabilidades.

# Output Format
Lista de issues con severidad (high/medium/low).

Presupuesto de tokens: 200-800 tokens para la mayoría de agentes; 500-3,000 para sistemas en producción.

Recency bias: las reglas críticas van AL FINAL del system prompt — los modelos prestan más atención a lo último que leen.

Patrones de diseño para prompts

Chain-of-Thought (CoT)

Antes de responder, escribe:

<reasoning>
Paso 1: Identificar el problema
Paso 2: Revisar el contexto relevante
Paso 3: Proponer solución
</reasoning>

<answer>Tu respuesta aquí</answer>

CoT da un boost de 19 puntos en MMLU-Pro para modelos estándar. Para modelos con reasoning extendido (o-series, Claude Extended Thinking), no lo necesitas — lo hacen internamente.

Output estructurado

## Formato de salida

Devolver JSON con:
- `verdict` (string, una oración)
- `issues` (array de strings, cada uno <15 palabras)
- `rewrite` (string, versión mejorada, o null)

Variables reutilizables

# Prompt para revisión de PR

Revisar el PR #{{pr_number}} del repo {{repo_name}}.

## Checklist
- [ ] Tests pasan
- [ ] Tipos correctos
- [ ] No hay console.log
- [ ] README actualizado si aplica

Knowledge files

Mantén archivos .md o .txt como contexto — se parsean 3 veces mejor que PDFs:

context/
├── INDEX.md          ← Tabla de contenido
├── arquitectura.md   ← Decisiones de diseño
├── api-reference.md  ← Endpoints disponibles
└── conventions.md    ← Estilo de código

Recursos gratuitos para aprender

Cursos completos

La mayoría son gratuitos. Algunos ofrecen certificado de pago opcional, pero el contenido siempre está disponible sin coste.

Canales de YouTube

• 3Blue1Brown — Intuición de redes neuronales con animaciones increíbles
• freeCodeCamp — Cursos completos de deep learning y ML
• Patrick Loeber — Tutoriales prácticos de PyTorch
• Andrej Karpathy — Fundamentos de LLMs desde cero (nanoGPT, etc.)
• Fireship — Resúmenes rápidos de tecnologías de IA

Documentación oficial de agents

Comunidades y recursos adicionales

• r/LocalLLaMA — Comunidad de modelos locales
• Hugging Face — Modelos, datasets y espacios
• awesome-ai-tools — Lista curada de herramientas de IA
• OpenAgentsSkills.dev — Especificación abierta de skills

Herramientas prácticas

Si vas a escribir system prompts, skills y configuraciones de agentes en Markdown, necesitas buenas herramientas para:

• Vista previa en vivo — ver cómo se renderiza tu Markdown mientras escribes
• Exportar a PDF — compartir configuraciones con tu equipo
• Generar presentaciones — explicar la estructura de prompts a tu equipo
• Referencia rápida — tener la sintaxis de Markdown siempre a mano

Ahí es donde entran las Markdown Tools — herramientas offline que ejecutan directamente en el navegador:

• Markdown a PDF — Convierte tus prompts y configuraciones a PDF con soporte de tablas, código y listas
• Diapositivas — Crea presentaciones de tus system prompts para presentar al equipo
• Cheatsheet — Referencia completa de Markdown con preview en vivo de cada ejemplo

Todo funciona sin servidor, sin APIs, sin suscripciones. Solo abres el navegador y empiezas a trabajar.

Tabla resumen

Conclusión

Markdown ya no es solo para documentar proyectos. Es el lenguaje universal para comunicarse con la IA: configura agents, define skills, estructura prompts y organiza el contexto.

Lo mejor de todo: es el mismo formato en todas las herramientas. Si aprendes a escribir un buen AGENTS.md para OpenCode, ese mismo conocimiento te sirve para CLAUDE.md, .cursor/rules o .windsurf/rules.

Empieza pequeño: crea un AGENTS.md en tu proyecto, define las convenciones básicas, y ve añadiendo reglas conforme descubras qué funciona. Tu agente de IA te lo agradecerá.

¿Quieres practicar la sintaxis de Markdown? Usa las Markdown Tools para crear, previsualizar y exportar tus configuraciones.