AltrinaAI/skill-miner

Skill Miner

Convierte la señal enterrada en sesiones pasadas de agentes de programación en nuevas y existentes "Agent Skills". Una sesión merece una habilidad solo cuando supera esta puerta de entrada — repetible Y (margen de mejora O solicitud repetida):

1. Repetible — la tarea o el conocimiento se repite, o claramente podría hacerlo. La repetición pasada es la evidencia más sólida, pero una tarea plausiblemente repetible cuenta; una tarea genuinamente única nunca lo hace. (Obligatorio.)
2. Margen de mejora — hay retroalimentación significativa, para que la próxima vez supere a la primera:
   • Retroalimentación del entorno — lo que reveló la ejecución del trabajo: fallos, peculiaridades recurrentes de este entorno, caminos indirectos y sus atajos, heurísticas ganadas con esfuerzo. Esto es literalmente una habilidad.
   • Retroalimentación del usuario — el usuario es el experto y su retroalimentación es escasa; explótala para extraer su conocimiento (una corrección, una mejor manera que conocía, un hecho que entendimos mal).
3. Una solicitud repetida — el usuario sigue pidiendo lo mismo; extráelo una vez para que no tenga que volver a pedirlo.

Pipeline: descubrir → destilar (LLM económico, por conversación) → agrupar, juzgar y generar.

0. Requisitos previos

Debe ser accesible un LLM pequeño. Verifícalo primero:

python3 scripts/llm.py --check   # muestra el backend que usará, o cómo habilitar uno

Establece una de las siguientes variables de entorno: OPENAI_API_KEY / GEMINI_API_KEY / OPENROUTER_API_KEY, o ten un CLI claude / codex / gemini en el PATH. Sobrescribe el modelo con SKILL_MINER_MODEL, fuerza un backend con SKILL_MINER_LLM.

1–2. Ejecutar el pipeline (los scripts realizan el trabajo pesado con un LLM económico)

Mantén tu directorio de trabajo en el directorio de inicio: todos los artefactos se generarán en ./out.

OUT=./out
python3 scripts/discover.py  --since 35 --out $OUT/inventory.jsonl       # encuentra transcripciones en todos los agentes
python3 scripts/extract.py   --inventory $OUT/inventory.jsonl --out $OUT/conversations.jsonl --workers 10

• discover.py recorre cada adaptador en common.py:ADAPTERS (Claude Code, Codex, opencode; agrega más allí) y conserva las sesiones de los últimos --since días. Comienza con un máximo de 100 conversaciones a menos que el usuario solicite más. Agrega --limit 15 a extract.py para un muestreo rápido.
• extract.py analiza cada conversación y emite una fila JSONL: agent, session_id, path, main_dir, datetime, n_user_turns, topics[], tasks[], skills_used[], env_feedback[], user_feedback[]. main_dir = la carpeta más profunda donde ocurrió la mayor parte del trabajo (a partir de archivos editados/leídos/mencionados), no el cwd de inicio. topics es el alcance (normalmente uno solo — que actúa también como título — para agrupar). tasks, env_feedback y user_feedback son arreglos cortos que el LLM económico copia de las propias palabras del usuario (cada [] para la sesión típica) — se asignan a las tres dimensiones de la puerta de entrada. La llamada económica solo ve los turnos del usuario, por lo que env_feedback es lo que el usuario dijo sobre lo que se ejecutó, no el resultado bruto de la herramienta — verifícalo en el paso 4.

3. Agrupar las conversaciones

Lee conversations.jsonl — una fila por sesión. Con ≤100 filas, todo el archivo cabe en el contexto, así que léelo. (Si has minado muchas más, revisa rápidamente con jq/grep las filas con env_feedback / user_feedback no vacíos primero, luego lee los fragmentos interesantes). Ignora las filas cuyo topics sea <error> o trivial/vacío.

Agrupa por arquetipo de tarea — el TIPO de trabajo, no solo el directorio (por ejemplo, "depuración de despliegue CI", "iteración de UI de configuración", "migración de dependencias") — para juzgar dimensión 1 (repetible): qué tareas se repiten o claramente podrían hacerlo. Luego, en todas las filas, reúne las otras dos dimensiones:

• dimensión 2 — env_feedback y user_feedback que apuntan a una manera de hacer una tarea mejor la próxima vez (prioriza la retroalimentación del entorno). Una sola lección ganada con esfuerzo es una pista incluso sin un grupo a su alrededor.
• dimensión 3 — un detalle que se repite en muchas sesiones de tasks (el usuario sigue pidiendo lo mismo).

Reserva los pasos de configuración únicos y los comentarios aislados. Mantén notas cortas: grupos con nombre, cada uno con su recuento de conversaciones, main_dir(s) dominante(s), la retroalimentación /solicitudes repetidas que conlleva, y algunas paths de ejemplo para abrir como evidencia posterior.

4. Juzgar y generar

Lee references/quality-bar.md y aplica su puerta de entrada: repetible Y (retroalimentación O una solicitud repetida).

1. Conoce el panorama. Revisa tus habilidades existentes para ver cuáles se pueden ampliar — especialmente aquellas cuya retroalimentación indique que se quedaron cortas; si un candidato se superpone con una, abre ese SKILL.md y edítalo en su lugar. Para encontrar las rutas de los archivos de habilidades:

   python3 scripts/skills_inventory.py
   

   Úsalo solo para encontrar archivos para editar; tu contexto sigue siendo la fuente de verdad para el panorama. Si un candidato se centra en un repositorio específico, verifica qué documentos Markdown ya existen allí (README.md, documentos de diseño, planes); si el conocimiento recurrente pertenece a esos documentos en lugar de a una habilidad, recomiéndaselo al usuario en tu informe.
2. Confirma con las transcripciones. Para cada pista, abre 1–3 transcripciones de ejemplo (el campo path) para confirmar que la señal es real y para capturar los detalles específicos — la regla exacta, el error exacto y su solución alternativa, el mejor camino al que apuntó el usuario, la solicitud repetida. Lee las palabras del usuario en torno a cualquier corrección y en torno a los marcadores [skill used: X]. Las filas condensadas solo muestran los turnos del usuario, por lo que la transcripción es donde verificas lo que realmente hizo el entorno. Separa una peculiaridad recurrente (escríbela) de una configuración única (como máximo un truco de una línea).
3. Decide, según la puerta de entrada. Una pista se convierte en habilidad solo si es repetible Y tiene margen de mejora (retroalimentación) o una solicitud repetida. Las tres dimensiones tienen el mismo peso — no descartes una lección ganada con esfuerzo porque la tarea apareció una vez si claramente se repite, y no envíes una tarea repetible que no tenga nada que mejorar y ninguna solicitud repetida.
4. Genera / modifica ≤ 5 habilidades. Escribe cada una como contenido concreto: la regla, el desencadenante, los pasos/comandos, la peculiaridad + solución alternativa — con rutas de archivo relativas a la raíz del repositorio (src/pages/Run.tsx), nunca absolutas específicas de la máquina (/home/<usuario>/…) copiadas de una transcripción. Dónde colocarla:
   • Ampliar una habilidad existente → edítala en su lugar en la ruta de la habilidad. No la bifurques ni copies.
   • Una habilidad completamente nueva → escríbela en ~/.agents/skills/generated-skills/<nombre>/, preparada para que el usuario la revise y la promocione — no coloques habilidades nuevas directamente en un directorio activo.
5. Informe. Enumera lo que creaste/modificaste y, para cada uno, de qué dimensión(es) provino. Para cada candidato rechazado notable, di en una línea qué dimensión le faltó. Incluye cualquier documento del repositorio que creas que debería actualizarse en lugar de, o además de, los cambios en las habilidades.

Extensión a otros agentes

Cada agente almacena las transcripciones de manera diferente. Para admitir uno nuevo (Gemini CLI, Cursor, …) agrega un par (discover_fn, parse_fn) a common.py:ADAPTERS que produzca el registro normalizado (_norm(...)). El resto del pipeline no cambia. Cursor (sqlite state.vscdb) aún no está conectado — el adaptador de opencode (basado en SQLite) sirve como plantilla a seguir.

Notas

• Solo lectura sobre tus transcripciones; las únicas escrituras son los artefactos --out y las habilidades que elijas generar o mejorar — las habilidades nuevas se colocan preparadas en ~/.agents/skills/generated-skills/, las ediciones se realizan en el lugar de la habilidad existente.
• Los hilos de subagentes/revisión (cadenas laterales de Claude Code, thread_source: subagent de Codex) se filtran — solo se minan conversaciones reales de usuarios.

Visualización de resultados

Ejecutado de forma independiente, los resultados son archivos simples: los artefactos en ./out, y las habilidades que cambiaste (editadas en su lugar, o preparadas en generated-skills/). Esta habilidad también se entrega con Skill Studio, una aplicación de escritorio donde el usuario observa la ejecución en vivo, revisa cada nueva habilidad preparada en generated-skills/ como una tarjeta Propuesta para Aceptar o Descartar, y ve las ediciones en el lugar como cambios rastreados por git para guardarlos como una versión o revertirlos.