/docs-to-skill — documentação markdown → skill funcional

Pega documentação que já existe em .md e a destila numa skill instalável. O valor não é copiar a doc: é reestruturá-la para outro Claude usar enquanto trabalha — SKILL.md enxuto que roteia, detalhe em references/ carregado sob demanda, e cada afirmação rastreável até a fonte (anti-alucinação verificável). É a "fatia markdown" da book-to-skill, no estilo do ateliê.

Princípios herdados (não os viole): extrair estrutura, não resumo · nunca copiar verbatim — sintetizar · front-load o SKILL.md (compaction trunca o fim) · toda asserção ancorada · o Topic Index é o que faz a skill gerada navegável.

Quando NÃO usar

• Fonte é PDF/EPUB/DOCX → book-to-skill. Aqui é só markdown (.txt/.rst são ignorados com aviso).
• Não há doc, é criar uma skill do zero → skill-creator / /skill-scout.

Pipeline (4 passos)

1. SCAN — mapear a doc (determinístico)

pwsh -NoProfile -File scripts/scan.ps1 <arquivo.md | "glob/**/*.md" | pasta>

Devolve JSON: árvore de headings por arquivo, code-blocks/tabelas/links, tokens estimados, signals (procedural vs conceitual), suggestedType, suggestedName, skipped, warnings. Leia o JSON — ele é o seu mapa. Se ok:false, resolva o input antes de seguir.

2. PLAN + SCAFFOLD — decidir forma e criar o esqueleto (julgamento)

1. Confirme o tipo com o suggestedType + sua leitura dos headings. --type força; senão, se ambíguo, pergunte ao usuário (AskUserQuestion): workflow (doc procedimental → passos acionáveis) ou reference (doc conceitual → corpus consultável). Híbrido = workflow no SKILL.md + reference no references/.
2. Agrupe headings em tópicos (1 tópico ≈ 1 arquivo references/<topico>.md). Não faça "um arquivo por heading"; agrupe por área temática.
3. Crie o esqueleto: pasta <nome>/ com SKILL.md + references/ vazios. Leia references/output-templates.md para os moldes exatos de SKILL.md (workflow vs reference), do Topic Index e do layout references/.

3. BUILD + ANCHOR — preencher com fidelidade (julgamento)

• Preencha cada references/<topico>.md sintetizando a doc (voz prática "use X quando Y"; preserve termos/nomes exatos do autor; uma afirmação por parágrafo).
• Ancore cada afirmação na fonte. Formato e regras em references/anchor-protocol.md (leia antes de ancorar). Pule este endurecimento só se o usuário passou --no-anchors.
• Termine o SKILL.md: visão geral + Topic Index (termo/pergunta → arquivo) + "quando ler cada reference". Mantenha o corpo < 500 linhas; o peso vai para references/.

4. AUDIT — validar antes de fechar (determinístico)

pwsh -NoProfile -File scripts/audit.ps1 <pasta-da-skill-gerada> [-ScanJson scan.json]

Checa frontmatter, links internos, densidade de âncoras, placeholders residuais, corpo ≤500 linhas, referências órfãs e (com -ScanJson) cobertura (nenhum arquivo-fonte sem âncora). Itere até ok:true / exit 0. Reporte ao usuário os warnings que sobraram com seu parecer.

Fechamento

A skill nasce no ateliê (~/.claude/skills\<nome>\), inerte. Lembre o usuário: para usá-la num projeto é /install-skill <nome> lá dentro.

Guardrails

• Anti-alucinação: só afirme o que está na doc; se a fonte não cobre algo, não invente — a âncora é a prova. Cobertura incompleta vira aviso, não preenchimento criativo.
• Inspiração, não cópia: reescreva a doc com suas palavras; não cole blocos verbatim.
• A skill gerada não leva README/CHANGELOG/INSTALL internos — só o essencial à execução.
• Só toca a pasta da skill nova dentro do ateliê; nada fora dela.