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

Fontes / Upstream

• Upstream: https://github.com/kangarooking/cangjie-skill
• Licença: MIT
• Vendido em: .agents/skills/book-to-skill-distill/SKILL.md para instalação compartilhada Moi/Codex
• Nota: O pipeline completo também precisa de methodology/ e extractors/ do repositório upstream.

Este arquivo pode ser uma cópia vendida ou um ponteiro fino. Prefira instalar/clonar o repositório upstream quando ele fornecer assets, scripts ou obrigações AGPL.

cangjie-skill — Meta-skill para destilar um livro em um conjunto de skills executáveis

Missão

Decompor a metodologia consolidada em um livro em capacidades atômicas e acionáveis por agentes em cenários reais, compilando-as no número adequado de skills de acordo com o propósito do usuário, para que o leitor realmente as utilize.

Convenção de termos: Neste documento e em methodology/, extractors/, todo "livro" refere-se genericamente a qualquer conteúdo longo a ser destilado — livros, transcrições de vídeos longos, textos de podcasts, cursos, entrevistas, artigos longos, conjuntos de materiais.

Limites:

• ✅ Fazemos: Destilação de metodologias / frameworks de decisão / fluxos operacionais / regras de cálculo / troubleshooting / checklists / princípios, com o sistema conceitual como suporte de referência.
• ❌ Não fazemos: Resumos de livros / resenhas / role-playing como o autor (para isso, use nuwa-skill).

Metodologia Central: RIA-TV++ (v2.5 Bundle)

Um pipeline de cinco estágios + extração paralela + verificação tripla + portão de promoção + teste de compatibilidade Darwin. Consulte methodology/00-overview.md para detalhes.

Estágio 0:   Compreensão Adler do livro inteiro → BOOK_OVERVIEW.md
Estágio 1:   Extração paralela por 5 agentes    → Pool de unidades candidatas de metodologia
Estágio 1.5: Tripla verificação (verificação de conhecimento) → Unidades aprovadas (confirmação leve do usuário)
Estágio 1.6: Portão de promoção para Skill independente (verificação de produtização) → promovidas / router (destinos)
Estágio 2:   Construção do cartão de capacidade RIA++ → .cangjie/capabilities/cards/<slug>.md
Estágio 3:   Vinculação Zettelkasten → also_read + GLOSSÁRIO em verified.yaml
Estágio 4:   Teste de estresse (compatibilidade Darwin) → Casos de teste + eliminação por retrabalho
Estágio 5:   Compilação e entrega → cangjie.py compile (single/pack) + DIGEST.md + instalação

Mudanças chave do v2.5 (ADR-002): Os Estágios 2–4 não mais escrevem cada unidade como um diretório de Skill final independente; em vez disso, produzem um Capability Bundle (books/<slug>/.cangjie/capabilities/verified.yaml + cards/*.md). Tanto single quanto pack são compilados deterministicamente a partir deste Bundle pelo scripts/cangjie.py compile, ambos referenciando o mesmo conjunto estável de capability_id. A saída antiga um-para-um ainda é suportada (legacy-pack, veja docs/migrations/2026-08-25-v2.0-to-v2.1.md).

Quando chamar esta skill

O usuário diz algo como:

• "Me ajude a destilar 'O Jeito Harvard de Negociar'"
• "Destile 'O Poder do Hábito' em skills"
• "Transforme este vídeo do B站/podcast/curso em skills"
• "distill this book into skills: "
• "Quero transformar a metodologia deste livro em uma skill utilizável"

Requisitos de Entrada

Antes de começar, deve-se confirmar com o usuário:

Dependências de script: Os scripts determinísticos (scripts/) requerem Python 3.10+ e PyYAML (python3 -m pip install pyyaml). Se faltar PyYAML, execute primeiro python3 scripts/cangjie.py doctor para autoverificação; ele fornecerá instruções de instalação.

1. Fonte do texto do conteúdo: Caminho para PDF / EPUB / TXT / arquivo de legenda / transcrição, ou texto puro acessível. Não destile "de memória" sem o texto — pare e peça ao usuário. (Para vídeos/podcasts, sugira usar ferramentas como video-downloader para obter a transcrição primeiro.)
2. Metadados do conteúdo: Para livro: "título + autor + ano de publicação"; para vídeo/podcast/curso: "título + autor (criador/apresentador/palestrante) + data de publicação". Usado para nomeação de diretório e auditoria.
3. Propósito de uso (determina a recomendação do modo de saída): Aprender/consultar o livro → tende a single; integrar ao fluxo de trabalho diário, combinar entre livros → tende a pack. Em caso de dúvida, siga o princípio single-first e recomende single inicialmente.
4. É a primeira tentativa? Se o usuário estiver usando cangjie-skill pela primeira vez, sugira destilar 1 conteúdo primeiro para verificar o fluxo antes de processar em lote.

Mapeamento de campos para conteúdo não-livro: Para campos de capítulo, use timestamps ou número de parte para vídeos, número de episódio para podcasts, número de aula para cursos — garanta rastreabilidade.

Estrutura de Saída

books/<slug-do-livro>/
├── PIPELINE_STATE.md          # Estado do pipeline: estágio atual + progresso (para retomada)
├── BOOK_OVERVIEW.md           # Saída do Estágio 0: tema/estrutura/termos/crítica
├── verified.md                # Saída do Estágio 1.5: unidades aprovadas na tripla verificação + justificativa
├── coverage-audit.md          # Tarefas chave do livro original → candidatos → veredito → destino real de entrega
├── references.md              # Conteúdo referenciado mas não executado + mapeamento de entrega
├── needs-review.md            # Gaps de fonte/condição/teste; não compilar como capacidade ativa
├── GLOSSARY.md                # Saída do Estágio 3: dicionário de termos compartilhado do livro inteiro
├── DIGEST.md                  # Saída do Estágio 5: resumo longo orientado ao leitor
├── candidates/                # Saída do Estágio 1: pool de candidatos brutos (para auditoria)
├── rejected/                  # Unidades rejeitadas no Estágio 1.5 + motivo (para auditoria)
└── .cangjie/                  # Camada lateral do v2.5 (fonte factual de compilação + registro de execução)
    ├── capabilities/
    │   ├── verified.yaml      # Capability Bundle (única fonte factual de compilação, capability-bundle.schema.json)
    │   ├── cards/<slug>.md    # Cartão de capacidade RIA (R/I/A1/A2/E/B, saída do Estágio 2)
    │   ├── resources/         # Scripts UTF-8, templates CSV/JSON/Markdown declarados explicitamente pela capacidade (opcional)
    │   ├── destinations.json  # Mapeamento de destino de promoção/rota (saída do Estágio 1.6)
    │   └── book/{overview.md,glossary.md}
    ├── runs/<run-id>/         # Relatórios de decisão e logs de verificação de cada compilação/atualização
    └── snapshots/             # Snapshots pré-publicação (para rollback)

O entregável final é compilado pelo scripts/cangjie.py compile a partir do Bundle (--output single resulta em 1 entrada principal + cartões de capacidade; --output pack resulta em 1 entrada de rota de origem + algumas Skills promovidas).

Fluxo de Execução (rigorosamente em ordem)

Retomada de ponto de parada: Antes de começar, verifique se books/<slug>/PIPELINE_STATE.md existe. Se existir, leia e retome a partir do estágio registrado; não recomece do zero. Atualize o arquivo ao concluir cada estágio.

Estágio 0 — Compreensão do livro inteiro

1. Leia o texto do livro fornecido pelo usuário. Para arquivos grandes, leia em partes.
2. Execute os quatro passos Adler (Estrutura / Interpretação / Crítica / Aplicação) conforme methodology/01-stage0-adler.md.
3. Preencha o modelo templates/BOOK_OVERVIEW.md.template e escreva em books/<slug>/BOOK_OVERVIEW.md.
4. Apresente a saída ao usuário para confirmação: "Entendi corretamente a estrutura? Há alguma direção que você gostaria de destacar?" Obtenha confirmação antes de prosseguir para o Estágio 1.

Estágio 1 — Extração paralela por 5 subagentes

Em paralelo, spawn 5 Task subagentes (use a ferramenta Agent, iniciando 5 em uma única chamada):

Subagente	Prompt lido	Estratégia de contexto	Saída
Extrator de Frameworks	extractors/framework-extractor.md	Varredura total (abrangendo tanto entre capítulos quanto mecanismos completos em um único local)	Frameworks de decisão / modelos mentais / fluxos / troubleshooting
Extrator de Princípios	extractors/principle-extractor.md	Varredura total (incluindo fórmulas, tabelas, notas de rodapé)	Princípios / checklists / regras / critérios de cálculo
Extrator de Casos	extractors/case-extractor.md	Recuperação de blocos (acuracidade local)	Exemplos do livro, casos recontados, exercícios, com tipo marcado
Extrator de Contracasos	extractors/counter-example-extractor.md	Recuperação de blocos (acuracidade local)	Padrões de falha alertados no livro
Extrator de Glossário	extractors/glossary-extractor.md	Recuperação de blocos + pré-filtragem por script	Dicionário de conceitos chave

Cada subagente julga e produz independentemente para books/<slug>/candidates/<type>.md.

• Texto longo: Se o conteúdo exceder o contexto de um único subagente, siga a estratégia de particionamento em methodology/02-stage1-parallel-extract.md; quando um índice de conteúdo já existir (.cangjie/index/), extratores por recuperação buscarão blocos relevantes pelo índice.
• Portão de cobertura: Compare simultaneamente os candidatos de varredura total com a lista de tarefas chave do livro do Estágio 0; não verifique apenas itens aprovados da versão antiga. Tarefas importantes devem ter candidatos e destinos claros; se houver lacunas inexplicadas, releia/retorne à varredura total, não finja cobertura zero.
• Plano de degradação: Se o ambiente atual não suportar subagentes paralelos, execute os mesmos 5 prompts de extrator sequencialmente, mantendo o formato de saída inalterado.

Estágio 1.5 — Tripla verificação (verificação de conhecimento)

Leia methodology/03-stage1.5-triple-verify.md e execute para cada unidade candidata:

• V1 Suficiência da fonte: O texto original pode ser localizado para suportar a prática dentro do escopo definido? Um mecanismo completo explicado em um único local também pode passar.
• V2 Executabilidade: Com uma nova entrada válida, a tarefa pode ser concluída e o resultado verificado? Não é necessária extrapolação entre domínios.
• V3 Ganho de tarefa: Pode reduzir omissões, unificar critérios ou estabilizar entregas? Não é exigido que o autor seja original.

Classifique como verified / reference / needs_review / rejected, registrando a base e as lacunas; conteúdo de referência deve ser mapeado para o overview/glossary realmente entregue, nem todo item não aprovado é descartado. Atualize coverage-audit.md.

Confirmação leve do usuário ★: Apresente as quatro categorias (executáveis aprovados, referência, a revisar, rejeitados) e lacunas importantes antes de prosseguir para o Estágio 1.6; a confirmação não substitui a verificação de fonte.

Estágio 1.6 — Portão de promoção para Skill independente (verificação de produtização)

Leia methodology/03b-stage1.6-promotion-gate.md. Passar na verificação de conhecimento não significa que vale a pena ser uma Skill independente. Para cada unidade, avalie cinco critérios (intenção independente / contrato independente / execução independente / reutilização independente / avaliação independente; os 3 primeiros devem passar, pelo menos 1 dos 2 últimos). Escreva o destino no promotion.destination do Bundle (promoted / router). Unidades não promovidas não são descartadas, mas mantidas como cartões de capacidade dentro da entrada de rota de origem. O orçamento suave da entrada descoberta é 8 por padrão (incluindo 1 entrada de rota de origem).

Estágio 2 — Construção do cartão de capacidade RIA++

Para cada unidade aprovada, construa o cartão de capacidade de seis seções (R / I / A1 / A2 / E / B) conforme methodology/04-stage2-ria-plus.md:

• Escreva o corpo do cartão em books/<slug>/.cangjie/capabilities/cards/<slug>.md (sem frontmatter; dados do frontmatter são registrados no Bundle);
• Simultaneamente, registre a capacidade no verified.yaml: capability_id estável, intents, keywords, one_liner, importance (com fundamentação), frontmatter.description (versão condensada de A2).
• A1 deve distinguir entre casos originais do livro e exercícios sintéticos explicitamente marcados; E deve especificar entradas, saídas, ramificações e critérios de conclusão. Quando necessário, declare explicitamente recursos de texto complementares via resources, conforme instruções do Estágio 2.

Estágio 3 — Vinculação Zettelkasten

Conforme methodology/05-stage3-zettelkasten.md:

1. Encontre relações de referência entre capacidades, escreva no also_read de cada capacidade no Bundle e preencha de volta a seção A2 "diferenciação de capacidades adjacentes".
2. Organize candidates/glossary.md em books/<slug>/GLOSSARY.md e copie para .cangjie/capabilities/book/glossary.md.
3. O índice/tabela de rota é gerado pelo compilador a partir do Bundle, não mais escrito manualmente.
4. Incorpore o conteúdo de references.md que precisa ser mantido no book/overview.md ou book/glossary.md do Bundle, registrando o caminho real na auditoria de cobertura; não disfarce conteúdo a revisar como método executável.

Estágio 4 — Teste de estresse (compatibilidade Darwin)

Conforme methodology/06-stage4-pressure-test.md: Capacidades promovidas testam acionamento; capacidades de rota testam alcançabilidade; ambos os tipos devem realmente completar tarefas representativas e conferir a saída, não use "será chamado" como substituto para "fazer corretamente". Saídas ausentes contam no denominador da avaliação; não concluídas não podem ser declaradas como aprovadas. Se falhar, retorne ao Estágio 2 para retrabalho.

Estágio 5 — Compilação e entrega

Conforme methodology/07-stage5-deliver.md:

1. Gere books/<slug>/DIGEST.md — um resumo longo orientado ao leitor.
2. Execute python3 scripts/cangjie.py compile --bundle books/<slug>/.cangjie/capabilities --out <diretório-alvo> --output auto e apresente o relatório de decisão ao usuário para confirmação leve (conforme recomendação / mude para single / mude para pack).
3. Pergunte ao usuário o local de instalação e copie ou crie um link simbólico dos artefatos compilados.
4. Informe ao usuário: "Concluído. Pode ser alimentado diretamente para darwin-skill para evolução automática."

Linhas Vermelhas de Qualidade (violação impede a saída)

1. Cada capacidade deve passar todas as três verificações.
2. Cada cartão de capacidade deve ter as seis seções completas R / I / A1 / A2 / E / B; A1 deve marcar honestamente quando não há caso original do livro; exercícios sintéticos não devem se passar por fatos do livro.
3. Citações originais ≤150 caracteres/parágrafo (inglês ≤100 palavras/parágrafo).
4. Cada capacidade ativa deve ter exatamente um destino em destinations.json (promoted_to ou served_by); capacidades não promovidas devem ser acessíveis via entrada de rota de origem.
5. A description da Skill promovida deve especificar claramente a condição de trigger e ter exemplos negativos próximos com a entrada de rota de origem.
6. O artefato compilado deve passar por scripts/validate_skill_pack.py (formato / referências relativas / frontmatter 100%).
7. Diretório gerado é somente leitura: se detectar modificação manual local, não sobrescrever silenciosamente (o compilador força uma escolha entre três opções).
8. Cobertura de tarefas chave com destinos rastreáveis; avaliação real de saída e verificação de fonte registradas separadamente. Se houver lacunas importantes, só entregar rascunho com escopo claramente marcado, não declarar aprovação completa.

Posicionamento Ecológico com nuwa-skill / darwin-skill

• nuwa-skill: Destila pessoas (modo de pensar / DNA de expressão)
• cangjie-skill (esta skill): Destila livros (metodologias / frameworks / princípios)
• darwin-skill: Evolui qualquer skill

Os três se encaixam: Os casos de teste de saída desta skill seguem o formato darwin-skill, para que as skills produzidas possam ser diretamente conectadas ao darwin para evolução automática.

Convenções de Chamada

• Sempre teste 1 primeiro — a menos que o usuário diga explicitamente "em lote"
• Relate progresso ativamente entre os estágios — não execute silenciosamente e despeje o resultado
• Não destile de memória — se não houver texto, pare e pergunte
• Mantenha trilha de auditoria — candidates/ e rejected/ devem ser preservados
• Sempre retomável — atualize PIPELINE_STATE.md após cada estágio concluído; após interrupção, retome do arquivo de estado
• Persistência de estratégia de saída — update/repair mantém o modo de saída original por padrão, não altera silenciosamente a forma do artefato devido a novo material