cangjie-skill — 把一本书蒸馏成一组可执行 skills 的元 skill

Fuentes / Aguas arriba

• Repositorio: https://github.com/kangarooking/cangjie-skill
• Licencia: MIT
• Incluido en: .agents/skills/book-to-skill-distill/SKILL.md para instalación compartida de Moi/Codex
• Nota: El pipeline completo también necesita los extractores de metodología del repositorio original.

Este archivo puede ser una copia vendida o un enlace. Se prefiere instalar/clonar el repositorio original cuando incluya activos, scripts u obligaciones AGPL.

cangjie-skill — Meta-skill para destilar un libro en un conjunto de skills ejecutables

Misión

Descomponer la metodología contenida en un libro en habilidades atómicas que un agente pueda invocar en escenarios reales, compilándolas en la cantidad adecuada de skills según el propósito del usuario, para que los lectores realmente las utilicen.

Convención terminológica: En este documento, así como en methodology/ y extractors/, el término "libro" se refiere a cualquier contenido largo sometido a destilación: libros, transcripciones de videos largos, textos de podcasts, cursos, entrevistas, artículos extensos, conjuntos de datos.

Límites:

• ✅ Lo que SÍ hacemos: Destilación de metodologías / marcos de decisión / flujos de trabajo / reglas de cálculo / resolución de problemas / listas de verificación / principios, con el sistema conceptual como soporte de referencia.
• ❌ Lo que NO hacemos: Resúmenes de libros / reseñas / interpretación del autor (esto último es competencia de nuwa-skill).

Metodología central: RIA-TV++ (versión v2.5 Bundle)

Un pipeline de cinco fases + extracción paralela + triple verificación + puerta de promoción + prueba de compatibilidad darwin. Ver detalles en methodology/00-overview.md.

Fase 0:   Comprensión del libro (Adler) → BOOK_OVERVIEW.md
Fase 1:   5 agentes de extracción en paralelo → Pool de unidades candidatas
Fase 1.5: Filtro de triple verificación (validación de conocimiento) → Unidades aprobadas (confirmación ligera del usuario)
Fase 1.6: Puerta de promoción a Skill independiente (validación de producto) → destinos promoted / router
Fase 2:   Construcción de fichas de capacidad (RIA++) → .cangjie/capabilities/cards/<slug>.md
Fase 3:   Enlaces Zettelkasten → also_read de verified.yaml + GLOSSARY
Fase 4:   Pruebas de estrés (compatibilidad darwin) → Casos de evaluación + eliminación
Fase 5:   Compilación y entrega → cangjie.py compile (single/pack) + DIGEST.md + instalación

Cambio clave v2.5 (ADR-002): Las fases 2–4 ya no escriben cada unidad como un directorio de Skill final independiente, sino que producen un Bundle de Capacidades (books/<slug>/.cangjie/capabilities/verified.yaml + cards/*.md). Tanto single como pack se compilan de forma determinista desde este mismo Bundle mediante scripts/cangjie.py compile, ambos referenciando el mismo conjunto estable de capability_id. El antiguo formato uno-a-uno aún es compatible (legacy-pack, ver docs/migrations/2026-08-25-v2.0-to-v2.1.md).

Cuándo invocar este skill

El usuario dice algo como:

• "Ayúdame a destilar 'El libro de la sabiduría'"
• "Destila las Obras Escogidas de Mao en skills"
• "Destila este video de Bilibili / podcast / curso en skills"
• "distill this book into skills: "
• "Quiero convertir la metodología de este libro en un skill utilizable"

Requisitos de entrada

Antes de comenzar, debes confirmar con el usuario:

Dependencias de scripts: Los scripts deterministas (scripts/) requieren Python 3.10+ y PyYAML (python3 -m pip install pyyaml). Si falta PyYAML, ejecuta primero python3 scripts/cangjie.py doctor para autodiagnóstico; mostrará instrucciones de instalación.

1. Fuente del texto del contenido: PDF / EPUB / TXT / archivo de subtítulos / ruta de transcripción, o texto plano accesible. No destiles "de memoria" sin el texto — es mejor detenerse y pedírselo al usuario. (Para videos/podcasts, se recomienda usar herramientas como video-downloader para obtener la transcripción).
2. Metadatos del contenido: Para libros: "título + autor + año de publicación"; para videos/podcasts/cursos: "título + autor (creador/presentador/instructor) + fecha de publicación". Se usan para nombrar directorios y auditoría.
3. Propósito de uso (determina el modo de salida recomendado): Aprendizaje/consulta del libro → preferir single; Integración en flujos de trabajo diarios, combinación entre libros → preferir pack. En caso de duda, seguir el principio de single-first.
4. ¿Primera vez con cangjie-skill?: Si el usuario usa cangjie-skill por primera vez, se recomienda destilar 1 contenido primero para validar el proceso antes de hacerlo en lote.

Mapeo de campos para contenido no librario: Los campos de capítulo se mapean a marcas de tiempo o números de parte para videos, números de episodio para podcasts, números de sesión para cursos — asegurando trazabilidad.

Estructura de salida

books/<slug-del-libro>/
├── PIPELINE_STATE.md          # Estado del pipeline: fase actual + progreso (para reanudación)
├── BOOK_OVERVIEW.md           # Salida de la Fase 0: propósito/esqueleto/términos/crítica
├── verified.md                # Salida de la Fase 1.5: unidades aprobadas por triple verificación + justificación
├── coverage-audit.md          # Tareas clave del libro original → candidatos → juicio → destino real de entrega
├── references.md              # Contenido con fundamento pero no ejecutable + mapeo de entrega
├── needs-review.md            # Brechas de fuente/condiciones/pruebas; no se compila como capacidad activa
├── GLOSSARY.md                # Salida de la Fase 3: diccionario de términos compartido del libro
├── DIGEST.md                  # Salida de la Fase 5: resumen detallado orientado al lector
├── candidates/                # Salida de la Fase 1: pool de candidatos original (para auditoría)
├── rejected/                  # Unidades eliminadas en la Fase 1.5 + motivo (para auditoría)
└── .cangjie/                  # Capa lateral v2.5 (fuente de compilación + registros de ejecución)
    ├── capabilities/
    │   ├── verified.yaml      # Bundle de Capacidades (única fuente de compilación, schema capability-bundle.schema.json)
    │   ├── cards/<slug>.md    # Fichas de capacidad RIA (R/I/A1/A2/E/B, salida de la Fase 2)
    │   ├── resources/         # Scripts UTF-8, plantillas CSV/JSON/Markdown declarados explícitamente (opcional)
    │   ├── destinations.json  # Mapeo de destinos de promoción/ruta (salida de la Fase 1.6)
    │   └── book/{overview.md,glossary.md}
    ├── runs/<run-id>/         # Informes de decisión y registros de validación de cada compilación/actualización
    └── snapshots/             # Instantáneas previas a la publicación (para rollback)

El entregable final se compila desde el Bundle mediante scripts/cangjie.py compile (--output single → 1 entrada + fichas de capacidad; --output pack → 1 entrada de enrutamiento + algunas Skills promocionadas).

Flujo de ejecución (estrictamente secuencial)

Reanudación: Antes de comenzar, verifica si existe books/<slug>/PIPELINE_STATE.md. Si existe, léelo y reanuda desde la fase registrada; no empieces de nuevo. Al completar cada fase, actualiza el archivo.

Fase 0 — Comprensión del libro

1. Lee el texto del libro proporcionado. Divide archivos grandes en fragmentos.
2. Ejecuta los cuatro pasos de Adler (Estructura / Interpretación / Crítica / Aplicación) según methodology/01-stage0-adler.md.
3. Rellena la plantilla templates/BOOK_OVERVIEW.md.template y escribe en books/<slug>/BOOK_OVERVIEW.md.
4. Muestra el resultado al usuario para confirmación: "¿He entendido bien el esqueleto? ¿Hay algún enfoque que quieras destacar?" Espera confirmación antes de pasar a la Fase 1.

Fase 1 — 5 sub-agentes en extracción paralela

En paralelo, lanza 5 sub-agentes (usando la herramienta de Agente, en una sola llamada):

sub-agente	Prompt de lectura	Estrategia de contexto	Salida
Extractor de marcos	extractors/framework-extractor.md	Escaneo completo (abarcando capítulos y mecanismos completos en un solo lugar)	Marcos de decisión / Modelos mentales / Flujos / Resolución de problemas
Extractor de principios	extractors/principle-extractor.md	Escaneo completo (incluyendo fórmulas, tablas, notas al pie)	Principios / Listas de verificación / Reglas / Criterios de cálculo
Extractor de casos	extractors/case-extractor.md	Bloques recuperados (localizados)	Instancias del libro, casos parafraseados, ejercicios, indicando el tipo
Extractor de contraejemplos	extractors/counter-example-extractor.md	Bloques recuperados (localizados)	Patrones de fallo advertidos en el libro
Extractor de términos	extractors/glossary-extractor.md	Bloques recuperados + pre-filtrado por script	Diccionario de conceptos clave

Cada sub-agente juzga de forma independiente y escribe su salida en books/<slug>/candidates/<type>.md.

• Textos largos: Si el contenido supera el contexto de un sub-agente, sigue la estrategia de fragmentación de methodology/02-stage1-parallel-extract.md; si ya existe un índice de contenido (.cangjie/index/), los extractores recuperadores obtendrán bloques relevantes según el índice.
• Cobertura obligatoria: Al mismo tiempo, compara los candidatos de escaneo completo con la lista de tareas clave del libro de la Fase 0; no verifiques solo los elementos aprobados anteriormente. Las tareas importantes deben tener candidatos y un destino claro; si hay omisiones inexplicadas, vuelve a leer / retrocede a escaneo completo; no declares omisión cero falsamente.
• Plan de contingencia: Si el entorno no soporta sub-agentes paralelos, ejecuta los 5 extractores en serie con los mismos prompts, manteniendo el mismo formato de salida.

Fase 1.5 — Filtro de triple verificación (validación de conocimiento)

Lee methodology/03-stage1.5-triple-verify.md y para cada unidad candidata:

• V1 Suficiencia de la fuente: ¿Se puede localizar el texto original suficiente para respaldar el enfoque dentro del alcance definido? Un mecanismo completo explicado en un solo lugar también puede pasar.
• V2 Ejecutabilidad: ¿Con una entrada nueva y válida se puede completar la tarea y verificar el resultado? No se requiere extrapolación a otros dominios.
• V3 Ganancia de tarea: ¿Reduce omisiones, unifica criterios o estabiliza la entrega? No se exige originalidad del autor.

Clasifica en verified / reference / needs_review / rejected, registrando fundamentos y brechas; el contenido de referencia debe mapearse al overview/glossary real entregado; no todas las unidades no aprobadas se eliminan. Actualiza coverage-audit.md.

Confirmación ligera del usuario ★: Muestra las cuatro categorías (ejecutables, referencia, pendientes de revisión, eliminadas) y las brechas importantes antes de pasar a la Fase 1.6; la confirmación no reemplaza la validación de fuentes.

Fase 1.6 — Puerta de promoción a Skill independiente (validación de producto)

Lee methodology/03b-stage1.6-promotion-gate.md. Superar la validación de conocimiento no significa que merezca ser un Skill independiente. Para cada unidad, evalúa cinco criterios (intención independiente / contrato independiente / ejecución independiente / reutilización independiente / evaluación independiente; los primeros 3 deben pasar, al menos 1 de los últimos 2) y escribe el destino en promotion.destination del Bundle (promoted / router). Las unidades no promocionadas no se eliminan, se conservan como fichas de capacidad dentro de la entrada de enrutamiento. Presupuesto suave por defecto: 8 entradas promocionadas (incluyendo 1 entrada de enrutamiento).

Fase 2 — Construcción de fichas de capacidad RIA++

Para cada unidad aprobada, construye la ficha de capacidad de seis secciones (R / I / A1 / A2 / E / B) según methodology/04-stage2-ria-plus.md:

• Escribe el cuerpo de la ficha en books/<slug>/.cangjie/capabilities/cards/<slug>.md (sin frontmatter; los datos del frontmatter se registran en el Bundle);
• Al mismo tiempo, registra la capacidad en verified.yaml: capability_id estable, intents, keywords, one_liner, importance (con fundamento), frontmatter.description (versión resumida de A2).
• A1 distingue entre casos del libro original y ejercicios sintéticos marcados explícitamente; E define claramente entradas, salidas, ramas y criterios de finalización. Cuando sea necesario, declara recursos de texto complementarios mediante resources, como se indica en la Fase 2.

Fase 3 — Enlaces Zettelkasten

Según methodology/05-stage3-zettelkasten.md:

1. Encuentra relaciones de referencia entre capacidades y escríbelas en also_read de cada capacidad en el Bundle, completando la sección "diferenciación con capacidades vecinas" en A2.
2. Organiza candidates/glossary.md en books/<slug>/GLOSSARY.md y cópialo a .cangjie/capabilities/book/glossary.md.
3. El INDEX/tabla de enrutamiento es generado por el compilador desde el Bundle; ya no se escribe a mano.
4. Integra el contenido que debe conservarse de references.md en book/overview.md o book/glossary.md del Bundle, registrando la ruta real en la auditoría de cobertura; no disfraces contenido pendiente de revisión como métodos ejecutables.

Fase 4 — Pruebas de estrés (compatibilidad darwin)

Según methodology/06-stage4-pressure-test.md: Las capacidades promocionadas se prueban mediante activación; las capacidades de enrutamiento se prueban mediante accesibilidad. Ambos tipos deben completar tareas representativas reales y verificar la salida; no se puede sustituir "hará la llamada" por "lo hace bien". Las salidas faltantes se cuentan en el denominador de la evaluación; sin completar, no se declara aprobado. Si no se pasa, se vuelve a la Fase 2.

Fase 5 — Compilación y entrega

Según methodology/07-stage5-deliver.md:

1. Genera books/<slug>/DIGEST.md — resumen detallado orientado al lector.
2. Ejecuta python3 scripts/cangjie.py compile --bundle books/<slug>/.cangjie/capabilities --out <directorio-destino> --output auto, mostrando el informe de decisión al usuario para confirmación ligera (según recomendación / cambiar a single / cambiar a pack).
3. Pregunta al usuario la ubicación de instalación y copia o enlaza simbólicamente los artefactos compilados.
4. Informa al usuario: "Completado. Puede alimentarse directamente a darwin-skill para evolución automática."

Líneas rojas de calidad (bloquean la salida si se incumplen)

1. Cada capacidad debe pasar todas las tres verificaciones.
2. Cada ficha de capacidad debe tener las seis secciones completas (R / I / A1 / A2 / E / B); si A1 no tiene casos del libro original, indícalo explícitamente; los ejercicios sintéticos no deben hacerse pasar por hechos del libro.
3. Citas textuales ≤150 caracteres/párrafo (≤100 palabras/párrafo en inglés).
4. Cada capacidad activa debe tener exactamente un destino en destinations.json (promoted_to o served_by); las capacidades no promocionadas deben ser accesibles a través de la entrada de enrutamiento.
5. El description de un Skill promocionado debe especificar claramente la condición de activación y tener ejemplos negativos cercanos con la entrada de enrutamiento.
6. Los artefactos compilados deben pasar scripts/validate_skill_pack.py (formato / referencias relativas / frontmatter 100%).
7. Directorio de salida de solo lectura: si se detectan modificaciones locales, no sobrescribir silenciosamente (el compilador fuerza una de tres opciones).
8. La cobertura de tareas clave debe tener destinos trazables; las evaluaciones de salida real y las verificaciones de fuentes se registran por separado. Si existen brechas importantes, solo se puede entregar un borrador con el alcance claramente marcado, no declarar finalización completa.

Posicionamiento ecológico con nuwa-skill / darwin-skill

• nuwa-skill: Destila personas (forma de pensar / ADN de expresión).
• cangjie-skill (este skill): Destila libros (metodologías / marcos / principios).
• darwin-skill: Evoluciona cualquier skill.

Los tres se engranan: los casos de evaluación de salida de este skill siguen el formato de darwin-skill, para que los skills producidos puedan conectarse directamente a darwin para evolución automática.

Convenciones de invocación

• Siempre probar con 1 libro primero — a menos que el usuario diga explícitamente "en lote".
• Reportar progreso activamente entre fases — no ejecutes en silencio y luego vuelques los resultados.
• No destiles de memoria — si no hay texto, detente y pregunta.
• Conserva pistas de auditoría — las carpetas candidates/ y rejected/ deben mantenerse.
• Siempre se puede reanudar — actualiza PIPELINE_STATE.md al completar cada fase; se recupera desde el archivo de estado después de una interrupción.
• Persistencia de la estrategia de salida — las actualizaciones/reparaciones usan por defecto el modo de salida original; no se cambia la forma del producto silenciosamente por material nuevo.