shimo4228/agent-stocktake

agent-stocktake — Auditoría de calidad de definiciones de agente

Evalúa cada definición de agente bajo <harness>/agents/*.md y asigna a cada una un veredicto: Keep / Improve / Update / Merge / Demote to skill / Dissolve / Retire. La unidad de auditoría es el archivo, pero la unidad de coste está dividida en dos capas — esa división es la razón por la que esta habilidad existe como un tercer hermano junto a skill-stocktake y rules-stocktake.

Nota de diseño — el modelo de coste híbrido. El coste de una habilidad es contaminación de activación (la activación probabilística degrada la selección); el coste de una regla es residencia (siempre cargada). Un agente tiene ambos a la vez: su description se inyecta en cada sesión a través del listado "Available agent types" (residencia, como una regla), mientras que su cuerpo se carga solo cuando se invoca al agente (invocación, como una habilidad — pero desencadenada por el juicio de delegación de Claude, no por la coincidencia de la descripción con las palabras del usuario). Por lo tanto, la descripción se audita por densidad de residencia y el cuerpo por calidad de invocación, con preguntas diferentes para cada capa.

Nota de diseño 2 — las ediciones aprobadas son aplicadas por esta misma habilidad, en la rama de apply. Misma lógica que rules-stocktake: no existe un motor de mejora para las definiciones de agente, y el corpus es lo suficientemente pequeño como para leerlo en un solo contexto — la delegación sería sobreingeniería. La excepción a la entrega es Demote to skill (crear una habilidad es trabajo del skill-writer).

Raíces. <harness> a continuación es el harness que cubre esta auditoría: ~/.claude por defecto, o el .claude/ de un repositorio cuando la habilidad harness-stocktake se ejecuta en modo proyecto (su sección Raíces mapea las rutas, nombra la evidencia que es n/a allí, y dice qué comprobaciones de convención aplican). El ledger <ledger> pertenece a ese harness: ${CLAUDE_SKILL_DIR}/results.json cuando el directorio de esta habilidad está dentro de <harness> (el harness lleva su propia copia de la habilidad), de lo contrario <harness>/stocktake/agent-stocktake.json (un plugin instalado, o modo proyecto). De cualquier manera se confirma con los otros cambios del harness en la rama de apply.

Modos ($ARGUMENTS)

Argumento	Comportamiento
none / full	Lee y evalúa cada definición de agente (por defecto)
changed	Reevalúa solo los archivos cuya mtime es más reciente que el evaluated_at de <ledger>; arrastra el resto desde el ledger

changed detecta cambios en línea (sin script):

Las rutas a continuación comienzan en ${CLAUDE_SKILL_DIR}, el directorio que contiene este SKILL.md; un agente que no sustituye la variable lo lee como ese directorio.

find <harness>/agents -name "*.md" -newermt "$(jq -r .evaluated_at "<ledger>")"

Como en rules-stocktake, las comprobaciones de integridad de la Fase 1 siempre se ejecutan sobre el conjunto completo — retirar una habilidad o hook rompe silenciosamente una referencia dentro del cuerpo de un agente no modificado, y mtime no puede verlo. Cualquier agente cuya comprobación de referencia (Paso 3 a continuación) falle recientemente se une al conjunto de reevaluación. El script tampoco tiene modo changed, por una razón diferente: los pares casi duplicados y el total de residencia son propiedades del conjunto, por lo que un corpus parcial daría números incorrectos en lugar de menos.

Fase 1 — Evidencia, inventario, uso

Paso 1 — Ejecutar el script de evidencia (no contar a mano)

uv run --frozen --project "${CLAUDE_SKILL_DIR}" \
       --directory "${CLAUDE_SKILL_DIR}" \
       python scripts/agent_evidence.py --root <harness>

Modo de evidencia: JSON en stdout, salida 0 aunque haya hallazgos (salida 2 solo cuando el corpus es ilegible). Mide y enumera; nunca asigna un veredicto.

Transcribe el JSON en hallazgos — nunca vuelvas a medir a ojo. Lo que proporciona:

Campo JSON	Reemplaza
desc_words / body_lines / total_desc_words	la pasada wc -w / wc -l
tools.items[].status + registry.known_tools	builtin / unverified / mcp. unverified significa "no está en la lista fechada del script", no "no existe" — tú tienes el registro de herramientas en vivo y el script no, así que confirma un unverified contra tu propia lista de herramientas antes de llamarlo evidencia de Update. registry.known_tools.as_of es la fecha de esa lista (null cuando --known-tools la reemplazó)
tools.items[].server_in_config + registry.mcp_config_files	No es un veredicto. Solo dice si el servidor aparece en los archivos de configuración local listados — los servidores proporcionados por un conector nunca aparecen allí, por lo que un false no es "retirado". null significa que no se analizó ninguna fuente de configuración. Verifica el status de cada fuente antes de usar esto; un false junto a una fuente que no sea ok no es evidencia
unreadable	archivos que el escaneo no pudo abrir, con una razón. No vacío significa que el escaneo está incompleto — nómbralos y arréglalos antes de indicar cualquier total, porque una instrucción de supresión dentro de un archivo ilegible ahora está certificada como ausente
tools_unparsable	agentes cuya línea tools: no se pudo analizar (p. ej., estilo de flujo YAML). Sus items es [], que se ve idéntico a un agente sin clave tools: — es decir, sin restricciones. No lo es; la lista simplemente no se leyó
description_near_duplicates	la comprobación de descripciones casi idénticas; los gemelos dividen el tráfico de delegación, por lo que cada par alimenta la pregunta de superposición de la Etapa 1
suppression_candidates	candidatos con números de línea para la pregunta de supresión de la Etapa 1 (el catálogo es bilingüe porque el corpus lo es)
always_never_candidates	candidatos con números de línea para la pregunta de sobre-restricción, solo del cuerpo — una descripción es un desencadenante de delegación, no una instrucción para el agente

Los dos últimos son candidatos, no hallazgos — lee cada línea citada antes de escribirla. El catálogo también es un piso, no un censo: contiene cinco frases extraídas de un corpus, por lo que una supresión escrita de otra manera ("salta cualquier cosa de la que no estés seguro", "evita hallazgos que serían solo ruido") no aparece en ningún campo JSON. Sigue leyendo para encontrarlos; una lista vacía no es un certificado de limpieza.

Las tasas de falsos positivos medidas viven fuera de este archivo, por lo que este paso no contiene números que se vuelvan obsoletos.

Paso 2 — Leer las puertas que ya son dueñas del resto

Tres comprobaciones permanecen fuera del script porque, en un harness que tiene una puerta de lint (<harness>/scripts/hooks/harness_lint.py), esa puerta es dueña de ellas. Lee su salida cuando exista; sin ella, realiza las tres comprobaciones con Read / Grep:

• El frontmatter se analiza y lleva name, description, origin, model, y model es un alias → el lint_agents del script de lint (en el harness del autor se ejecuta en .claude/verify.sh y en el hook de pre-commit). Un origen faltante, donde el harness establece la convención de origen, sigue siendo un hallazgo de integridad, que alimenta Improve.
• name es igual al nombre del archivo (stem) → el mismo lint_agents. No admite juicio y el registro de delegación se basa en él, por lo que pertenece a una puerta que detiene un commit — no a una evidencia que un lector puede o no transcribir. Un hallazgo aquí es un commit bloqueado, no un veredicto de stocktake.
• Los enlaces Markdown dentro de los cuerpos de los agentes se resuelven → el mismo lint_markdown_links del script (sus ámbitos incluyen agents).

Paso 3 — Resolver referencias de ruta simple (la única comprobación de la que nadie más es dueño)

lint_markdown_links solo ve la sintaxis de enlace, y scan_refs.py de skill-health escanea el árbol de habilidades. Una ruta escrita como prosa dentro del cuerpo de un agente (<harness>/hooks/foo.sh, skills/foo/SKILL.md) no está cubierta por ninguno. Busca en el corpus y haz ls a cada una.

Paso 4 — Inventario

Enumera con Glob: <harness>/agents/*.md. Lee cada archivo en un solo contexto (el corpus es pequeño). Las columnas de residencia y cuerpo provienen del JSON del Paso 1 — nunca confíes en cifras escritas en documentos, incluido este.

Paso 5 — Conteos de uso

Entrada de evidencia: el uso bajo nomina a un candidato, y el contenido decide el veredicto. Cuando la configuración mantiene un registro de uso del agente (<harness>/metrics/agent-usage.jsonl; ausente = uso n/a), léelo en línea (un hook de registro de uso como log-agent-usage.sh agrega un evento invoke por cada lanzamiento de la herramienta Agent, keyed por su campo agent, cuyo valor es el subagent_type) y cuenta los eventos por agente en 7 / 30 / 90 días. Agrega con un one-liner desechable de python3/jq.

• Si el registro falta o su primer evento es más reciente que 90 días, muestra el uso como — (no medido). Nunca lo muestres como 0 — no medido y no usado son hechos diferentes.
• Los conteos son límites inferiores: solo se capturan los lanzamientos de la herramienta Agent (Task). Los workers de agent() de Workflow, el despacho interno del plugin y la maquinaria incorporada que evita la llamada a la herramienta no llegan al hook. Un agente de bajo uso entra en la Etapa 1 como candidato a Retire/Dissolve; su valor puede ser episódico (por ejemplo, los revisores de artículos se activan solo cerca de un depósito), por lo que el contenido decide.
• El registro existe desde 2026-07-27; antes de esa fecha no hay medición.

Indica el resultado del escaneo por adelantado, tomando los conteos del JSON del Paso 1: agents_total menos cualquier cosa en unreadable, que debe ser nombrada, total_desc_words (el impuesto de residencia por sesión del listado), fallos de integridad, y si el uso es medible. Lleva los fallos a la Etapa 1 como evidencia precalculada.

Fase 2 — Evaluación (completamente en línea, holística)

Lee cada cuerpo mientras ves el conjunto completo.

Etapa 1 — pantalla binaria (cada agente). Sí/No explícito por elemento; muestra solo las respuestas No. Las dos primeras preguntas auditan la capa de descripción (residencia), el resto la capa del cuerpo (invocación):

• ¿La descripción se gana su residencia? — densa, distinta y que permite la selección en el listado siempre cargado; indica cuándo delegar Y cuándo no
• ¿La descripción es veraz con respecto al cuerpo? — lo que promete es lo que el cuerpo hace (una descripción desviada dirige mal la delegación cada sesión, incluso si el cuerpo está bien)
• ¿El cuerpo está libre de instrucciones de supresión? — comienza desde los suppression_candidates de este agente en el JSON de la Fase 1, manejados según el Paso 1. Lo que cuenta: umbrales de confianza ("solo informa hallazgos de los que estés ≥N% seguro", "asigna a cada hallazgo una confianza y descarta los bajos"), pisos de severidad ("solo alta severidad"), marcos "sé conservador". La guía de la generación actual es: informa todo, filtra en una pasada separada — una instrucción de supresión se sigue literalmente y elimina silenciosamente hallazgos. Un No aquí es un candidato a Improve por inversión: reescribe la instrucción en la dirección opuesta, nunca solo elimines la sección (eliminar deja el marco supresivo; invertir lo reemplaza)
• ¿La copia de origen externo está actualizada? — para un agente cuyo origin es un repositorio externo y cuyo cuerpo es una copia textual (por ejemplo, una sobreescritura incorporada como Explore), la versión de origen nombrada en el comentario principal del cuerpo coincide con la herramienta instalada (claude --version); una discrepancia es un Update (diferencia contra el paquete y recopia). Las preguntas de supresión y sobre-restricción se omiten para dichas copias — el cuerpo es del proveedor, no nuestro
• ¿El cuerpo está libre de sobre-restricción de generación anterior? — procedimientos paso a paso exhaustivos para el juicio que el modelo actual posee de forma nativa, énfasis repetido, pares SIEMPRE/NUNCA que el juicio del contexto circundante debería poseer. Los always_never_candidates de la Fase 1 localizan los tokens; decidir si un acierto es una directiva o simplemente cita las palabras es el trabajo de esta pregunta
• ¿No ha sido absorbido por el sustrato? — ¿el harness ahora cubre el trabajo de este agente de forma nativa (maquinaria de revisión nativa, modo plan, comandos slash incorporados)? Absorción → candidato a Dissolve; la afirmación debe nombrar su absorbedor de forma concreta. Juzga con el eje de contexto fresco/rico: los roles que se benefician del contexto fresco (revisión, verificación adversarial, evaluación de esencia — descorrelación del coste hundido del proponente) viven legítimamente en un subagente; los roles que se benefician del contexto rico (planificación, generación, implementación — intención del usuario, restricciones en la conversación) son trabajo del bucle principal, por lo que para ellos el propio bucle principal cuenta como un absorbedor. Dos justificaciones auxiliares anulan legítimamente la atracción del contexto rico: un contrato de renderizado con entrada congelada — el llamante congela un paquete autocontenido antes de la invocación, por lo que el contexto de la conversación no es necesario por diseño (prompt-forager, que recibe una línea a propósito) — y aislamiento de contexto masivo — el trabajo lee o produce un volumen que contaminaría el contexto principal (investigador, un ángulo de investigación web por ejecución)
• ¿Las referencias técnicas están actualizadas? — verifica incondicionalmente cada artefacto que el cuerpo nombra: haz ls a cada ruta referenciada, ejecuta --help / comprobaciones de versión para comandos, banderas, nombres de modelo y listas de herramientas nombradas. "Verifica si parece obsoleto" es una frase prohibida — la condición es lo que diluye; las afirmaciones comprobables de forma determinista reciben comprobaciones deterministas, cada vez
• ¿Único dentro del conjunto? — ningún otro agente (o habilidad) es dueño del mismo trabajo; una división documentada orquestador→subagente NO es superposición

Ocho preguntas y no más — una mayor descomposición degrada el juicio holístico (ver Referencias).

Etapa 2 — prueba de estrés del veredicto (solo candidatos que no son Keep). Genera 1–3 preguntas atómicas de sí/no específicas del agente que intenten refutar el veredicto preliminar, cada una respondida con una línea de evidencia (lectura de archivo, verificación de ruta, --help, WebSearch, verificación de documento del harness). Para los candidatos a Dissolve, una pregunta es obligatoria: "¿Se puede nombrar concretamente la característica absorbedora del harness — Sí/No" — una afirmación de absorción que no puede nombrar su absorbedor es refutada. Y cuando un Dissolve está a punto de ser refutado por una capacidad que falta en la contraparte del sustrato (una herramienta, un subagente cableado), una contra-pregunta es obligatoria antes de aceptar la refutación: "¿Es el subagente el lugar adecuado para usar esa capacidad — o el bucle principal la tiene de todos modos?" La existencia de la capacidad es necesaria pero no suficiente; el eje de contexto fresco/rico decide dónde pertenece la capacidad (precedente: la refutación del planificador colapsó porque el bucle principal tiene la herramienta Agent completa). Los agentes limitados a Keep no reciben preguntas dinámicas.

La evaluación es holística: datos de la Etapa 1 + preguntas de la Etapa 1 + una respuesta por pregunta de la Etapa 2 dan el veredicto completo. Cuando el veredicto es Improve, la redacción debe ser accionable y nombrada (por ejemplo, "Improve: longitud de descripción — acortar a ≤15 palabras en el siguiente commit"). Los veredictos Merge nombran el objetivo (por ejemplo, "Merge into: archiver").

Tabla de veredictos

Veredicto	Cuándo	Elementos de salida
Keep	El agente pasa las 8 preguntas y no hay nada que refinar	Nombre + veredicto
Improve	Una o más preguntas fallan pero el agente es fundamentalmente sólido; la reparación es incremental	Nombre + veredicto + elementos de acción con nombre
Update	El agente es una copia de origen externo que ha quedado atrás de su fuente (pregunta 4)	Nombre + veredicto + versión de origen y versión actual
Merge	El agente tiene un trabajo singular pero se superpone con otro en el mismo conjunto (pregunta 8, y la contra-pregunta de la Etapa 2 confirma la superposición en lugar de la división)	Nombre + veredicto + objetivo
Demote to skill	El agente tiene valor pero funciona mejor como una habilidad (invocado por sintaxis en lugar de delegación)	Nombre + veredicto + SKILL.md esbozado (responsabilidad del skill-writer)
Dissolve	El sustrato ahora posee el trabajo de este agente (pregunta 6); la eliminación es segura	Nombre + veredicto + absorbedor nombrado
Retire	Uso cero o casi cero medible, y la Etapa 2 no encuentra ningún valor episódico o futuro	Nombre + veredicto + la fecha de corte (7 / 30 / 90 días)

Salida

Archivo de resultados

Escribe en <ledger> un mapa JSON de agent_name → resultado. Ejemplo:

{
  "evaluated_at": "2026-07-27T10:30:00Z",
  "agents_total": 15,
  "agents_unreadable": [],
  "total_desc_words": 83,
  "usage_measured": true,
  "agents": {
    "explore": {
      "verdict": "Update",
      "detail": "origin=bundle, source_version=v1.2.0, cli_version=v1.3.5",
      "questions_asked": 8,
      "stage2_questions": [
        {
          "q": "Does the installed bundle zip list a different sha?",
          "a": "sha256 mismatch: expected abc, got def"
        }
      ]
    }
  }
}

Explicación en el chat

Tras emitir el archivo, resume en el chat:

Auditados N agentes; M necesitan cambios. El detalle de cada veredicto está en <ledger>.

Y cuando haya candidatos a Improve:

Agentes Improve: mejora la descripción de {a} (demasiado larga), suprime menos en {b} (instrucción supresiva encontrada en la línea 42), actualiza la referencia de herramienta en {c} (tool:foo renombrada a tool:bar en v2).

Confirmación del ledger

Cuando termines la evaluación, lee el archivo <ledger> confirmado para verificar que se haya escrito.

Referencias

• Verdad fundamental de la sobre-restricción: el fallo silencioso es el fracaso específico — el agente dice sí a peticiones irrealizables.
• Una descripción debe habilitar la selección sin tener que ser leída por humanos; el listado se muestra siempre en el panel de estado, por lo que es un coste de residencia fijo.

Nota de implementación. La guía de supresión de la generación actual ("informa todo, filtra en una pasada separada") es una recomendación, no un hecho consumado. Los proyectos que todavía ejecutan modelos 3.5 de 2024 pueden necesitar la pasada de filtro integrada en el propio agente; el stocktake se ajusta al harness, no al manual.