Cargador de Contexto de Agente
Resumen
Descubrimiento y carga automática de archivos AGENTS.md a través de jerarquías de proyectos para agentes de codificación de IA. Este skill escanea el espacio de trabajo actual y sus directorios padres para localizar archivos de instrucciones del agente, luego presenta su contenido para que la sesión activa del agente tenga un contexto operativo completo.
Requisitos previos
- Un espacio de trabajo de proyecto que contenga uno o más archivos
AGENTS.mden cualquier profundidad de directorio - Permisos de Lectura y Glob para recorrer el árbol de directorios
- Acceso a Grep para buscar contenidos de archivos cuando existan múltiples candidatos
Instrucciones
- Escanea el directorio de trabajo actual y todos los directorios ancestros (hasta la raíz del sistema de archivos o la raíz del repositorio) en busca de archivos llamados
AGENTS.mdoagents.md. - Busca en subdirectorios del espacio de trabajo actual archivos
AGENTS.mdadicionales que puedan aplicarse a subproyectos o módulos. - Determina el orden de carga: los archivos más cercanos a la raíz del repositorio se cargan primero (contexto global), los archivos en directorios más profundos se cargan después (anulación o complemento).
- Lee cada archivo
AGENTS.mddescubierto y extrae sus bloques de instrucciones, definiciones de flujo de trabajo y declaraciones de restricciones. - Fusiona las instrucciones en un contexto unificado, notando cualquier conflicto entre niveles (por ejemplo, un agente en un subdirectorio que anula una regla de nivel raíz).
- Presenta el contexto cargado como un resumen estructurado: ruta del archivo fuente, recuento de instrucciones y cualquier conflicto detectado.
- Almacena en caché los resultados del descubrimiento para la sesión actual, evitando escaneos redundantes del sistema de archivos en activaciones posteriores.
Salida
- Lista ordenada de rutas de archivos
AGENTS.mddescubiertos con su profundidad de directorio - Conjunto de instrucciones fusionado que combina todos los contextos de agente descubiertos
- Informe de conflictos que resalta cualquier directiva contradictoria entre niveles
- Estado de la caché de sesión que indica si los resultados son nuevos o reutilizados
Manejo de Errores
| Error | Causa | Solución |
|---|---|---|
No se encontró AGENTS.md | El espacio de trabajo no tiene archivos de instrucciones de agente | Confirma el directorio de trabajo correcto; crea un AGENTS.md en la raíz del proyecto si es necesario |
| Permiso denegado al recorrer directorios | Directorios padres restringidos por encima del espacio de trabajo | Limita la profundidad de escaneo a la raíz del repositorio (detectado mediante la presencia de .git/) |
| Enlace simbólico circular detectado | Directorios enlazados simbólicamente crean un bucle de recorrido infinito | Omite los directorios enlazados simbólicamente durante el escaneo; registra una advertencia con la ruta del enlace |
| Instrucciones conflictivas entre niveles | Un AGENTS.md de un subdirectorio contradice el archivo de nivel raíz | Marca el conflicto en la salida; aplica la instrucción más específica (más profunda) por defecto |
| Error de codificación de archivo | AGENTS.md utiliza una codificación no UTF-8 | Intenta con latin-1 como fallback; reporta la ruta del archivo y el problema de codificación |
Ejemplos
Ejemplo 1: Monorepo con instrucciones de agente por paquete
- Estructura: El
AGENTS.mdraíz establece convenciones globales;packages/api/AGENTS.mdagrega reglas de herramientas específicas de la API. - Resultado: Ambos archivos se cargan en orden. Las reglas específicas de la API complementan el contexto global sin conflicto.
Ejemplo 2: Espacio de trabajo anidado con políticas de commit conflictivas
- Estructura: El
AGENTS.mdraíz dice "siempre firmar los commits";services/legacy/AGENTS.mddice "omitir la firma de commits." - Resultado: Se detecta y reporta el conflicto. Se aplica la directiva más profunda (legacy) con una advertencia que indica la anulación.
Ejemplo 3: Configuración inicial sin archivos de agente
- Estructura: Un repositorio recién clonado sin
AGENTS.mden ningún lugar. - Resultado: El escaneo se completa sin encontrar archivos. La salida incluye una sugerencia para crear
AGENTS.mden la raíz del repositorio con una plantilla mínima.
Recursos
- Especificación de AGENTS.md de Claude Code: https://docs.anthropic.com/en/docs/agents
- Patrones de espacio de trabajo en monorepo para configuración de agentes: https://docs.anthropic.com/en/docs/claude-code
- Mejores prácticas de descubrimiento de archivos para carga jerárquica de configuraciones