shimo4228/skill-stocktake

skill-stocktake — Auditoría de Calidad de Skills

Evalúa los skills instalados de forma holística, todos en un solo contexto, y asigna a cada uno un veredicto: Keep / Improve / Update / Retire / Merge. Este skill no realiza la mejora — una vez que tiene un veredicto, delega en skill-creator (el motor de mejora). Este límite es el punto central: stocktake es la puerta de calidad, skill-creator es el reparador.

Nota de diseño: la versión anterior usaba scripts de escaneo y dividía la evaluación en ~20 skills por lote de subagente. Con un contexto de 1M esto no solo es innecesario sino perjudicial — los lotes ciegan a cada subagente frente a skills de otros lotes, por lo que se pierden solapamientos entre skills. Ahora enumeramos con Glob y leemos cada skill en un solo contexto. La detección de solapamientos depende de esta vista unificada.

Modos ($ARGUMENTS)

Argumento	Comportamiento
ninguno / full	Lee y evalúa cada skill (predeterminado)
changed	Re-evalúa únicamente los skills cuyo SKILL.md tiene mtime más reciente que evaluated_at de results.json; arrastra el resto del libro de registro

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

find ~/.claude/skills -name SKILL.md -newermt "$(jq -r .evaluated_at ~/.claude/skills/skill-stocktake/results.json)"

Fase 1 — Inventario

Enumera los archivos de definición de skills con Glob (sin necesidad de script):

• ~/.claude/skills/*/SKILL.md
• ~/.claude/skills/learned/*.md
• si el directorio de trabajo tiene .claude/skills/, también {cwd}/.claude/skills/*/SKILL.md (skills de proyecto)

Debido a que Glob apunta solo a SKILL.md / learned/*.md, el markdown de dependencias bajo .venv o .pytest_cache queda excluido estructuralmente (no se requiere poda). El ruido que el antiguo find -name "*.md" introducía no puede ocurrir.

Conteos de uso: leer ~/.claude/metrics/skill-usage.jsonl en línea (el hook PostToolUse log-skill-usage.sh añade líneas — una capa de medición independiente) y contar eventos por skill durante 7 / 30 / 90 días. Cada línea es JSON {ts,event,skill,path,project}; contar tanto eventos invoke como read. Agregar con un one-liner de python3/jq desechable en lugar de contar manualmente — el registro crece con el tiempo y contar manualmente desperdicia un turno de herramienta por invocación.

• Si el registro falta o su primer evento es más reciente que 90 días, mostrar uso como — (no medido). Nunca mostrarlo como 0 — no medido y no usado son hechos distintos.

Indicar el resultado del escaneo al principio: qué rutas se escanearon, cuántos skills se encontraron y si el uso es medible.

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

Leer el cuerpo de cada skill objetivo y evaluarlos uno por uno mientras se ve el conjunto completo. Lista de verificación:

• Solapamiento de contenido con otros skills (una división documentada de orquestador/sub-skill NO es solapamiento — p. ej. paper-ecosystem → sus revisores, citation-sync → release-doi/wikidata. Distinguir la estratificación intencional de la duplicación genuina)
• Solapamiento con MEMORY.md / CLAUDE.md / reglas
• Frescura de las referencias técnicas (si los indicadores de CLI / APIs / nombres de herramientas parecen obsoletos, confirmar con WebSearch)
• Frecuencia de uso (ignorar como señal cuando no está medida)

La evaluación es juicio holístico, no una rúbrica numérica. Dimensiones orientadoras: Accionabilidad (ejemplos/pasos concretos en los que se puede actuar), Ajuste de alcance (nombre, activador y cuerpo alineados — ni demasiado amplio ni demasiado estrecho), Singularidad (no reemplazable por MEMORY / otro skill), Vigencia (las referencias funcionan en el entorno actual).

Costo agregado (a nivel de conjunto, no por skill): mantener un skill no es gratuito incluso cuando el skill individualmente está bien. Los beneficios de los skills son frágiles — una biblioteca grande y no curada degrada la capacidad del agente para seleccionar el skill correcto y empuja el comportamiento hacia la línea base sin skills. Por lo tanto, el umbral de Keep aumenta con el tamaño de la biblioteca: cuando el conjunto es grande, un skill meramente adecuado (uso raro, baja singularidad, gran adyacencia a otros) es candidato a Retire/Merge solo por razones de dilución agregada — independientemente de cualquier defecto en el skill en sí. Esto es una entrada de juicio, nunca una cuota; no retirar para alcanzar un número.

Veredicto	Significado
Keep	Útil, actual, valor único
Improve	Vale la pena conservarlo, pero se necesitan mejoras específicas
Update	La tecnología referenciada está desactualizada (verificar con WebSearch)
Retire	Baja calidad, obsoleto o asimétrico en costo
Merge into [X]	Solapamiento sustancial con otro skill; nombrar el objetivo

Regla de uso cero: cuando el primer evento del registro de uso tiene al menos 90 días de antigüedad Y un skill tiene use_90d == 0, DEBE aparecer como candidato a Retire (la decisión final es del usuario). Mientras el registro sea más reciente que 90 días, esta regla no se activa y los veredictos se basan únicamente en el juicio holístico.

La evaluación es ciega al origen: no bifurcar por ECC / autoelaborado / extraído automáticamente. La misma lista de verificación se aplica a cada skill.

Fase 3 — Resumen

Mostrar una tabla: Skill | 7d | 90d | Veredicto | Razón.

Fase 4 — Consolidación

• Retire / Merge: por archivo, presentar (1) el defecto específico encontrado, (2) qué cubre la misma necesidad en su lugar (Retire: qué skill/regla existente; Merge: el objetivo y qué contenido integrar), (3) el impacto de la eliminación (skills dependientes, referencias en MEMORY). Actuar solo después de que el usuario confirme.
• Improve / Update: ofrecer delegar — "¿Entregar <skill> a skill-creator para mejorar?" — y al aprobar invocar skill-creator con el skill objetivo. Stocktake nunca realiza el trabajo de mejora por sí mismo.
• Actualizar el libro de registro: Leer results.json → fusionar los veredictos de esta ejecución → Escribirlo de vuelta (evaluated_at = UTC real de date -u +%Y-%m-%dT%H:%M:%SZ). En modo changed, conservar los veredictos anteriores de los skills que no se re-evaluaron.
• Si MEMORY.md supera las 100 líneas, proponer compresión.

Calidad de la razón (obligatorio)

Cada reason debe ser autocontenida — suficiente para tomar una decisión por sí sola. "sin cambios" solo está prohibido; siempre reafirmar la evidencia.

• Retire: indicar el defecto + el reemplazo. Mal: "Superado" / Bien: "disable-model-invocation: true ya está establecido; continuous-learning-v2 cubre los mismos patrones más puntuación de confianza. No queda contenido único."
• Merge: nombrar el objetivo + qué integrar. Mal: "Se solapa con X" / Bien: "Contenido delgado de 42 líneas; el Paso 4 de chatlog-to-article ya cubre este flujo de trabajo. Integrar el consejo de 'ángulo del artículo' allí como una nota."
• Improve: qué sección, qué cambio (tamaño objetivo si es relevante). Mal: "Demasiado largo" / Bien: "276 líneas; 'Comparación de marcos' (L80–140) duplica ai-era-architecture-principles. Eliminarlo para alcanzar ~150 líneas."
• Keep (solo cambio de mtime en modo changed): reafirmar la razón original. Mal: "Sin cambios" / Bien: "Contenido sin cambios. Referencia única de Python importada explícitamente por rules/python/; sin solapamiento."

results.json (libro de registro ligero)

{
  "evaluated_at": "2026-06-24T11:09:00Z",
  "skills": {
    "<nombre-del-skill>": {
      "path": "~/.claude/skills/<nombre>/SKILL.md",
      "verdict": "Keep",
      "reason": "...",
      "mtime": "2026-01-15T08:30:00Z"
    }
  }
}

Un libro de registro para el historial de veredictos y la marca de tiempo de la última auditoría únicamente. Actualizarlo en línea con Read/Write, no con un script. Solo skills globales (los skills de proyecto se leen frescos del directorio de trabajo, no se almacenan en caché aquí).

Relacionados

• skill-creator — el motor de mejora; delegar el trabajo de Improve/Update.
• config-gc — GC sobre la existencia de skills y todo ~/.claude (hooks/permisos/MCP/caché); stocktake juzga la calidad del skill.
• harness-sync — usarlo para sincronizar este skill con su repositorio público.
• Medición de uso: ~/.claude/hooks/log-skill-usage.sh → ~/.claude/metrics/skill-usage.jsonl (una capa de medición independiente de stocktake).