xingcanlee/wisp-writer

wisp-writer: Escreva artigos com estilo consistente no tema Wisp

O Wisp preza pela calma, precisão e contenção. Os artigos são escritos em src/content/posts/<slug>/index.mdx (ou index.md), e o frontmatter é definido por src/content.config.ts. Este skill fornece:

SKILL.md
reference/   frontmatter.md  style-guide.md  elements.md  templates/
scripts/     new_post.py  check_post.py  tests/   (Python + uv, dependências inline PEP 723, sem necessidade de instalação)

Convenções de comando

Todos os comandos são executados na raiz do site, no formato uv run skills/wisp-writer/scripts/<script>.py .... Ao copiar este skill para outro site Wisp:

• Coloque em <site>/skills/wisp-writer/: os comandos permanecem inalterados.
• Coloque em <site>/.claude/skills/wisp-writer/ ou ~/.claude/skills/wisp-writer/: ajuste o caminho; o script procurará por astro.config.* ou src/content a partir do diretório atual, ou use --root <raiz_do_site> para especificar.
• Se o site não for encontrado, o script exibirá um aviso e terminará com código de saída 2, sem escrever nenhum arquivo.
• Se o uv não estiver disponível: python3 <caminho>/new_post.py ... também funciona (usa apenas a biblioteca padrão, requer Python 3.10+).

Fluxo de trabalho

1. Defina o público e os pontos principais. Antes de escrever, anote três coisas: quem é o leitor (o que ele sabe e não sabe), o que ele levará do artigo (uma conclusão em uma frase) e o tipo de artigo. Quando faltarem informações, pergunte ao usuário; não invente fatos, dados ou citações.
2. Crie o artigo. Escolha o template de acordo com o tipo: tutorial (tutorial), deep-dive (aprofundamento), algorithm (explicação de algoritmo, com componentes interativos), note (nota curta), paper-reading (leitura de artigo).

   uv run skills/wisp-writer/scripts/new_post.py attention-explained \
     --title "Explicação do Mecanismo de Autoatenção" --template deep-dive \
     --tags "LLM,Transformer" --category Machine Learning \
     --description "Da intuição à fórmula, explique o processo de cálculo da autoatenção."
   

   O slug deve estar em kebab-case; se já existir, o script reportará erro. O script listará tags e categorias existentes; reutilize-as sempre que possível. Parâmetros: --draft, --md/--mdx, --date, --list-templates.
3. Escreva. Siga o guia de estilo, a sintaxe de elementos está em elements e os campos em frontmatter. Substitua todos os TODO do template.
4. Imagens e interatividade. Quando precisar de diagramas, use o skill wisp-diagram para gerar os arquivos fonte e .wisp.svg, depois insira-os no artigo usando a sintaxe de referência de diagramas; fluxos simples podem usar Mermaid diretamente. Quando precisar de demonstrações interativas, use os componentes explainer existentes (atualmente MatMul); outros algoritmos exigem novos componentes, cujo método está em docs/guide/explainers.md — isso é uma alteração de código, deve ser discutida e aprovada separadamente, sem ser feita durante a escrita do artigo.
5. Verifique e corrija.

   uv run skills/wisp-writer/scripts/check_post.py attention-explained --strict
   

   Saída no formato arquivo:linha nível regra explicação. Erros (error) devem ser corrigidos; avisos (warning) devem ser avaliados um a um e corrigidos se possível; informações (info) são apenas sugestões. --json para saída processável por programas, --all para verificar todos os artigos.
6. Visualize. pnpm build deve passar (valida frontmatter e Mermaid); para ver o resultado, use pnpm dev. Opcional: tire screenshots da página do artigo nos temas claro e escuro com Playwright para verificar se fórmulas, diagramas e blocos de código não transbordam e são legíveis no modo escuro.

Regras rígidas

1. O corpo do texto começa com h2, não escreva h1; não pule níveis de cabeçalho; h2 deve ser um sintagma nominal.
2. title ≤ 80 caracteres, description ≤ 200 caracteres; a description deve deixar claro qual problema o artigo resolve.
3. Tags e categorias reutilizam a grafia existente, com a mesma capitalização (não tenha llm e LLM ao mesmo tempo).
4. Parágrafos em chinês usam pontuação de largura total (全角); não insira espaços manuais entre chinês e inglês; ênfase em chinês usa **negrito**, não itálico.
5. Termos técnicos são traduzidos na primeira ocorrência com o original em inglês entre parênteses, como “自注意力（self-attention）”.
6. Cada bloco de código tem um identificador de linguagem; blocos longos podem ter recolhimento opcional, mas por padrão não mexa.
7. Cada imagem tem texto alternativo (alt) que descreve a conclusão que a imagem quer transmitir; legendas usam o formato "Figura N: descrição".
8. Não codifique cores, não use style=, não use escalas de cores do Tailwind; as cores só podem vir de variáveis do tema.
9. Artigos que usam componentes devem ser .mdx e fazer import; componentes interativos devem ter client:visible.
10. Não invente fatos, dados, citações ou links; marque claramente ou remova conteúdo sem certeza.
11. Não altere artigos existentes, a menos que o usuário peça; trabalhe apenas dentro de src/content/posts/<slug>/.

Exemplo de trecho

Abaixo, um trecho que segue o tom do Wisp (explica uma coisa, sem rodeios ou exageros):

## Por que dividir por √d

Suponha que cada componente de $q$ e $k$ seja uma variável aleatória independente com variância 1. Então o produto escalar $q \cdot k$ tem variância $d_k$. Quanto maior a dimensão, maior o produto escalar, e mais próxima de one-hot fica a softmax, tornando os gradientes muito pequenos.

Ao dividir por $\sqrt{d_k}$, a variância retorna a aproximadamente 1, e a saída da softmax permanece em uma faixa suave. Sem este passo, redes profundas são difíceis de treinar.

Compare: "Como todos sabem, este truque super simples, mas extremamente importante, pode melhorar muito o desempenho!" — vazio, exagerado, sem informação.

Erros comuns

• Começar com “Este artigo apresentará…”, “Com o desenvolvimento de…”; dê diretamente a conclusão ou o problema.
• Escrever # Título no corpo do texto; ou pular de h2 para h4.
• Títulos em forma de frase (“Vamos ver como implementar”); devem ser sintagmas nominais (“Implementação”).
• Misturar vírgulas e parênteses de meia largura (half-width) em chinês; usar itálico para ênfase em chinês.
• Escrever componentes em arquivos .md, ou esquecer import em arquivos .mdx; esquecer client:visible em componentes interativos.
• Imagens sem texto alternativo; referenciar .excalidraw ainda não gerado (desenhe primeiro, referencie depois); referenciar .wisp.svg em vez do arquivo fonte.
• Usar novas tags para o mesmo conceito (como Llm, 大模型 coexistindo com LLM já existente).
• Texto muito longo em nós Mermaid, causando sobreposição na renderização; deve ter no máximo cerca de 12 caracteres chineses.
• Deixar placeholders TODO ao entregar; check_post.py --strict consegue detectá-los.
• Escrever código sem explicação: antes do código, explique o objetivo; depois do código, destaque os pontos-chave ou a saída esperada.