CommunityProgramación y desarrollogithub.com

agents-md-audit

Verifica las instrucciones de AGENTS.md o CLAUDE.md contra la evidencia del proyecto y la política establecida. Útil para revisiones periódicas, detección de desviaciones tras cambios, o para establecer o continuar un registro de auditoría Git. Reporta defectos y límites de verificación, retiene hallazgos no resueltos y prepara un mensaje de checkpoint. Aplica correcciones o crea el checkpoint solo cuando se autoriza.

¿Qué es agents-md-audit?

El skill 'agents-md-audit' permite a agentes de IA (como Claude Code, Cursor, Codex, Windsurf) auditar sus propios archivos de instrucciones (AGENTS.md, CLAUDE.md) contra el estado real del proyecto y políticas definidas. Su propósito principal es detectar desviaciones entre lo que las instrucciones afirman y la evidencia del código, configuraciones, pruebas e historial Git. Es ideal para revisiones periódicas, tras refactorizaciones o cambios de dependencias, o para iniciar un registro de auditoría reproducible. El skill opera en modo de solo lectura por defecto, examinando archivos, afirmaciones, historial Git y ejecutando verificaciones factibles. Reporta defectos categorizados (desactualizados, contradictorios, faltantes, conflictos de política, advertencias obsoletas) y mantiene hallazgos no resueltos en checkpoints Git. Soporta plataformas que ejecuten SKILL.md, terminal y acceso a Git. Su flujo de trabajo incluye selección de línea base, verificación de precisión, mantenimiento, decisiones y forma, y finaliza con un mensaje de checkpoint estructurado. Solo escribe (corrige archivos o crea checkpoints) cuando el usuario lo autoriza explícitamente.

Compatible con✓Claude Code~Codex CLI~Cursor
npx skills add https://github.com/has2k1/agents-grimoire/tree/HEAD/skills/agents-md-audit

Installed? Explore more Programación y desarrollo skills: steipete/bluebubbles, steipete/eightctl, steipete/blucli · View all 6 →

Preguntar en tu IA favorita

Abre un nuevo chat con esta habilidad de agente ya precargada.

Documentación

Auditoría de AGENTS.md

Audita las instrucciones contra el estado del proyecto y la política establecida. Prioriza las afirmaciones que podrían engañar a un agente. La forma del documento y la frecuencia de edición por sí solas no establecen un defecto. No reportes ningún defecto cuando las comprobaciones demuestren que no lo hay; la documentación bootstrap breve y las instrucciones precisas sin cambios pueden ser suficientes.

Mantén la auditoría en modo de solo lectura por defecto, incluidos el índice y el historial Git. Prepara las correcciones y un mensaje de checkpoint para su revisión. Aplica las correcciones o crea un checkpoint cuando la solicitud lo autorice; usa la autoridad existente sin pedirla de nuevo. Ejecuta las comprobaciones sin opciones de corrección automática u otras opciones de escritura en el código fuente, e informa sobre los requisitos de ejecución que no estén disponibles.

Cobertura

Registra la cobertura como los archivos, afirmaciones, historial y comprobaciones realmente examinados.

  1. Registra la revisión del repositorio y el estado del árbol de trabajo. Inventaria los archivos de instrucciones, las reglas de ancestros relevantes, las anulaciones, las importaciones, los enlaces y los mapas de módulos en el repositorio. Incluye los sistemas CLAUDE.md existentes en lugar de asumir que AGENTS.md es su punto de entrada activo.
  2. Confirma qué archivos descubre el arnés previsto y cuáles requieren lecturas explícitas. Verifica las rutas de carga relevantes y los presupuestos de tamaño contra la configuración disponible o la documentación actual del arnés. Marca la entrega desconocida como no verificada; los nombres de archivo y la ubicación de los directorios por sí solos no prueban la carga.
  3. Indica los archivos y las afirmaciones a verificar, cualquier muestreo, los requisitos de los comandos y el historial disponible. Limita el veredicto cuando el repositorio esté sucio, el historial sea superficial o no esté disponible, o las comprobaciones no puedan ejecutarse. Audita los cambios locales por separado de una instantánea confirmada; no los atribuyas a su SHA. Cuando una comprobación se ejecute en archivos que difieren de la instantánea confirmada, como un árbol de trabajo con cambios locales, indica dónde se ejecutó y qué rutas diferían.

Historial y hallazgos anteriores

Para un repositorio Git, selecciona la línea base antes de verificar los cambios intervinientes. Sin historial Git, verifica el estado actual e informa de que la verificación histórica no está disponible.

Una auditoría completada ha finalizado las comprobaciones declaradas de todo el repositorio; puede informar sobre defectos, muestreo y comprobaciones no disponibles con límites explícitos. Un resultado limpio significa que no se demostró ningún defecto dentro de las comprobaciones completadas. Una auditoría que no puede finalizar produce un informe pero ningún checkpoint.

Un checkpoint es una confirmación Git vacía con un único padre cuyo mensaje almacena el informe de una auditoría completada y los trailers de la plantilla Mensaje de checkpoint. Su único padre es la revisión auditada, la instantánea confirmada examinada por esa auditoría. Los cambios locales están separados de esa instantánea. Una confirmación es un checkpoint solo cuando cumple todas las condiciones de Selección de línea base; cualquier otra confirmación es una confirmación ordinaria, sea cual sea su mensaje.

Una línea base es el checkpoint más cercano en el historial del primer padre de la rama objetivo. Establece el límite del historial, la revisión posterior a la cual la auditoría inspecciona los cambios hasta la revisión auditada. Sus hallazgos Nuevos y Trasladados son el conjunto completo de hallazgos anteriores abiertos. Una auditoría que no produce ningún checkpoint deja la línea base sin cambios.

La salida Bootstrap sigue siendo documentación candidata hasta que se verifica y por sí sola no puede proporcionar una línea base.

Selección de línea base

Recorre el historial del primer padre de la rama objetivo desde HEAD. Trata las confirmaciones con un trailer Agents-Audit-Version como candidatas; identifícalas por el trailer en lugar del asunto. Por ejemplo:

git log --first-parent --format='%H' --grep='^Agents-Audit-Version: 1$' HEAD
git show -s --format=%B <candidato> | git interpret-trailers --parse

Estos comandos encuentran candidatos. Un candidato es un checkpoint solo cuando su mensaje y los objetos Git cumplen todas estas condiciones:

  • Cada trailer en la plantilla del mensaje tiene un valor no conflictivo, la versión es compatible y la revisión del skill o el hash de contenido son identificables.
  • La confirmación tiene exactamente un padre. El SHA completo de ese padre es igual a Agents-Audit-Commit, y tanto el árbol del padre como el de la confirmación son iguales a Agents-Audit-Tree. La igualdad de árboles por sí sola no puede detectar una reproducción en un historial diferente que produzca los mismos archivos.
  • La confirmación se encuentra en el historial del primer padre del objetivo.
  • Agents-Audit-Previous nombra el checkpoint anterior más cercano en el historial del primer padre de la revisión auditada, o none para un límite de historial inicial establecido explícitamente. La confirmación nombrada debe ser a su vez un checkpoint.
  • El mensaje contiene cada sección del informe de la plantilla, con la cobertura declarada. A menos que Agents-Audit-Previous sea none, cada ID bajo los hallazgos Nuevos o Trasladados en el checkpoint nombrado aparece bajo los hallazgos Trasladados o Cerrados.

Debido a que cada predecesor debe ser a su vez un checkpoint, verifica los candidatos desde el más antiguo hacia adelante y reutiliza cada resultado; cada confirmación se verifica entonces una vez. Selecciona el candidato más cercano que cumpla estas condiciones como línea base. Trata cualquier otro candidato como una confirmación ordinaria en la ventana del historial: no leas hallazgos ni cierres de su mensaje, y déjalo fuera del informe y del mensaje del checkpoint.

Cuando un predecesor no esté disponible o el historial superficial impida estas comprobaciones, indica la brecha. No reemplaces silenciosamente un límite de historial conocido con los últimos commits ni declares el trabajo como una primera auditoría. Si no se puede establecer ninguna línea base, verifica el estado actual dentro de límites explícitos y deja la cobertura histórica sin verificar. Para una primera auditoría genuina sin un checkpoint anterior, verifica el estado actual e indica un límite de historial inicial explícito.

Rebase, cherry-pick y squash asignan nuevos padres a las confirmaciones, por lo que debes volver a verificar las condiciones después de reescribir el historial. Establece checkpoints duraderos después de la integración cuando el historial de características se aplaste.

Comprobaciones

Precisión y política

  • Verifica los comandos contra la configuración del proyecto y sus requisitos previos. Ejecuta las comprobaciones factibles en un entorno adecuado. Atribuye los fallos a una invocación obsoleta, un defecto de implementación, un requisito previo no disponible o una comprobación incompleta; un comando de prueba válido que encuentra una regresión no es obsoleto.
  • Resuelve referencias nombradas, rutas, importaciones y entradas de mapas de módulos. Inspecciona los cambios de nombre, la propiedad compartida y las reglas de ancestros aplicables antes de llamar a una instrucción faltante. Demuestra el defecto, luego juzga su gravedad por la consecuencia probable para un agente que siga la instrucción, no solo por un símbolo faltante.
  • Verifica invariantes importantes contra la implementación y las pruebas, tratando las cadenas de documentación y los comentarios como afirmaciones en lugar de evidencia. Verifica una afirmación condicional con entradas en ambos lados de su condición. Distingue las descripciones de la política: el código intencional aún puede violar un límite establecido. Resuelve los conflictos utilizando la autoridad de la tarea y las decisiones registradas; no reescribas la política simplemente para que coincida con el código que la viola.
  • Inspecciona las advertencias contra caminos concretos de fallo o regresión. Elimina detalles obsoletos o superficiales, conserva una salvaguarda útil cuando eludirla sigue siendo un riesgo realista, y recorta explicaciones ya adecuadamente soportadas por pruebas o cumplimiento. Prefiere una guía actual a un historial de fallos corregidos.

Reporta los defectos demostrados como desactualizados, contradictorios, faltantes, conflictos de política o advertencias obsoletas. Mantén las afirmaciones inciertas bajo comprobaciones no verificadas. Incluye la instrucción afectada, la evidencia del repositorio, la consecuencia y la corrección propuesta.

Mantenimiento

Inspecciona los cambios en el código, la configuración, las dependencias y las instrucciones desde el límite del historial. Asigna cada cambio relevante a las afirmaciones que podría invalidar, incluidos los archivos de instrucciones sin cambios. Utiliza palabras clave en los mensajes de confirmación y recuentos opcionales de confirmaciones que cambiaron código e instrucciones juntos para elegir los cambios a inspeccionar, no para juzgar la calidad de la documentación.

Reporta un defecto de mantenimiento solo cuando un cambio invalidó una afirmación documentada u omitió una instrucción necesaria. Permite que un invariante preciso sobreviva a muchos cambios intactos. Trata las correcciones independientes, las confirmaciones bootstrap, las reparaciones de auditoría y las confirmaciones de checkpoint como trabajo legítimo. Una refactorización entre módulos no necesita editar instrucciones cuyas afirmaciones sigan siendo ciertas.

Decisiones y advertencias

Inspecciona las decisiones arquitectónicas independientemente del descubrimiento de correcciones de errores. Busca elecciones aceptadas cuya consecuencia debería restringir cambios futuros y cuya razón no sea aparente a partir del código. Utiliza una explicación registrada o una confirmación del tomador de decisiones; un diff prueba un cambio, no su intención. Redacta la regla, la razón y las condiciones para su reconsideración solo cuando esté evidenciado y siga siendo útil. Deja una alternativa rechazada que valga la pena mencionar en un comentario en el código fuente al que afecta, donde un agente que cambie ese código la encontrará. Durante el bootstrap, continúa usando solo las fuentes actuales; no explotes el historial Git en busca de razones ni inventes una justificación.

Para errores diagnosticados significativos, verifica si la lección aún previene un error costoso o repetido. Propón una entrada concisa que registre el síntoma, el mecanismo y el reconocimiento o la evitación solo cuando agregue una guía útil. Cuando eludir una abstracción podría reintroducir el fallo, reformula la advertencia como una salvaguarda concisa y explica por qué. Propón la eliminación cuando el mecanismo haya desaparecido, el error sea superficial o el cumplimiento ya transmita adecuadamente la lección. Mantén los mecanismos inciertos como propuestas para su confirmación.

Forma

Verifica la forma después de la precisión. Coloca las reglas de todo el repositorio en el archivo raíz, las reglas compartidas por módulos en un archivo de raíz de código fuente o de paquete (un centro), y las reglas de módulos distintos en un archivo local (una hoja). Utiliza solo los ámbitos que necesiten una guía separada; permite proyectos de un solo archivo, múltiples centros y secciones vacías omitidas. Mantén una explicación canónica y permite un breve recordatorio con ámbito y un enlace cuando mejore el descubrimiento. Conserva las versiones aplicables, las fechas de verificación, las plataformas y las condiciones de medición. Elimina la narración de progreso obsoleta, la justificación inventada, la duplicación innecesaria y las instrucciones que ya no ayudan con un cambio. Juzga la especificidad por las decisiones útiles, no por la frecuencia con la que cambia el texto.

Informe

Indica si las instrucciones verificadas son precisas y limita esa conclusión a las afirmaciones examinadas. Registra la revisión, el contenido sucio o ignorado examinado, el inventario de instrucciones, las afirmaciones verificadas o muestreadas, el límite del historial, los resultados de los comandos, el entorno y las versiones relevantes, y las comprobaciones no resueltas. Mantén el informe interpretable desde el propio repositorio, utilizando rutas relativas al repositorio y revisiones Git como evidencia.

Vuelve a verificar cada hallazgo abierto de la línea base y colócalo bajo los hallazgos Trasladados o Cerrados antes de finalizar el informe.

Separa los hallazgos en estas secciones; escribe None cuando una esté vacía:

  • Registra nuevos hallazgos con IDs estables nuevos, instrucciones afectadas, evidencia, consecuencias y correcciones requeridas.
  • Traslada cada hallazgo no resuelto de la línea base, incluidos los que enumeró como nuevos, con su ID, su checkpoint de origen (el checkpoint que lo registró por primera vez) y un relato completo de su evidencia, consecuencia y corrección requerida. Mantén un hallazgo abierto cuando no se pueda verificar su resolución y divulga la evidencia que no se pueda validar.
  • Cierra los hallazgos con la resolución o sustitución verificada y la evidencia de respaldo. Registra cada cierre una vez y luego omítelo de informes posteriores. Mantén su historial en el checkpoint anterior en lugar de acumular un archivo en cada informe.

Asigna IDs sin reutilizar los retirados; por ejemplo, usa una marca de tiempo UTC específica de la auditoría más un contador y conserva ese ID en adelante. Indica en el informe si la auditoría se completó; una auditoría interrumpida o no finalizada termina con el informe. Reclama un resultado limpio solo dentro de las comprobaciones que lo demuestren.

Mensaje de checkpoint

Prepara el siguiente mensaje como parte del entregable de una auditoría completada. Incluye el informe de auditoría en sí mismo, no punteros a un rastreador de incidencias externo, un informe local u otra fuente externa. Usa el asunto y los trailers exactamente como se muestran, con encabezados ## y líneas en blanco para las secciones del informe. Registra IDs de objeto completos y una revisión o hash de skill identificable en lugar de basarte en una ruta instalada.

chore: registrar auditoría de documentación de agente

## Cobertura

Examinados <archivos o directorios de instrucciones relativos al repositorio>.
Verificadas <afirmaciones y comprobaciones realizadas, incluyendo cualquier muestreo>.
Inspeccionado el historial desde <límite del historial> hasta la revisión auditada.
Utilizado <entorno y versiones de herramientas relevantes, y dónde se ejecutaron las comprobaciones>.

## Comprobaciones no verificadas

<Comprobaciones no completadas y sus razones, o None.>

## Hallazgos nuevos

<ID estable, instrucción y sección afectadas, hallazgo, evidencia, consecuencia y corrección requerida para cada hallazgo nuevo; o None.>

## Hallazgos trasladados

<ID estable, checkpoint de origen y un relato autónomo de cada hallazgo no resuelto, incluyendo evidencia, consecuencia y corrección requerida; o None.>

## Hallazgos cerrados

<ID estable, resolución o sustitución, y evidencia de respaldo para cada hallazgo que esta auditoría cierra; o None.>

Agents-Audit-Version: 1
Agents-Audit-Commit: <SHA completo de la confirmación padre auditada>
Agents-Audit-Tree: <SHA del árbol auditado>
Agents-Audit-Skill-Revision: <revisión del skill o hash de contenido>
Agents-Audit-Previous: <SHA del checkpoint de línea base o none>

Creación de checkpoint

Crea un checkpoint solo para una auditoría completada y solo con autorización para esa escritura. Requiere que la revisión auditada siga siendo HEAD y que las instrucciones y el código auditados estén representados en su árbol. Confirma primero las correcciones autorizadas y verifica esa instantánea resultante antes de registrar su checkpoint. Actualiza el informe y los trailers para describir esa instantánea verificada si las correcciones cambiaron la revisión auditada. Excluye el contenido no confirmado o ignorado de las afirmaciones sobre la instantánea confirmada y registra cualquier límite de cobertura resultante. Rechaza registrar un checkpoint para un estado sucio observado como si estuviera limpio. Un checkpoint para una instantánea diferente a HEAD requeriría una nueva autorización; no la crees.

Skills relacionados