Redator de Tutoriais HackMD

Visão Geral

Esta skill pesquisa um tópico específico (ferramenta, biblioteca, framework, API ou qualquer software) e escreve um tutorial bem organizado em Markdown no estilo HackMD, pronto para ser colado em notas do HackMD. Ela tem três características principais:

Pesquisar primeiro, escrever depois — nunca escreve apenas com base na memória.
Escrito para iniciantes — usa a explicação mais clara e os exemplos mais curtos para que o leitor realmente aprenda a usar o tópico.
Segue rigorosamente um formato de títulos numerados e blocos que o HackMD consegue interpretar corretamente, garantindo que o painel de sumário/índice seja exibido corretamente.

Todo o conteúdo gerado deve ser escrito em chinês tradicional (dialeto de Taiwan). Mesmo que o usuário dê instruções em outro idioma, o artigo em si (título, texto principal, texto explicativo dos exemplos) deve estar em chinês tradicional; apenas o código em si (nomes de variáveis, comandos, sintaxe) deve seguir as convenções do idioma original.

Público-Alvo e Profundidade

Padrão: Foco em Iniciantes

A menos que o usuário solicite o contrário, o artigo tem como público-alvo iniciantes sem experiência em programação:

O objetivo é fazer o leitor entender o uso real do tópico, sem buscar cobrir todos os aspectos.
Os exemplos devem ser a versão mais simples, curta e diretamente executável, suficiente para ilustrar a funcionalidade da seção.
Quando um termo técnico aparecer pela primeira vez, explique-o em uma frase simples (por exemplo, "gerenciador de pacotes: uma ferramenta que ajuda a baixar e instalar programas").
Cada etapa deve incluir uma descrição do que o leitor verá após a execução, para que ele possa verificar se fez tudo corretamente.
O tamanho do artigo varia conforme o tópico, geralmente entre 1500 e 3000 palavras. É melhor um artigo curto e claro do que um longo e cheio de informações desnecessárias para um iniciante.
Seções como "Configurações Avançadas" e "Comparação com Alternativas" não devem ser incluídas por padrão.

Alternativo: Versão Aprofundada para Avançados

Somente quando o usuário solicitar explicitamente termos como "aprofundado", "avançado", "completo" ou "para desenvolvedores experientes", a versão avançada deve ser escrita:

Pode ter mais de 3000 palavras e deve explicar por que as coisas funcionam de determinada maneira, e não apenas o que a sintaxe faz.
Pode incluir seções como "Configurações Avançadas", "Casos Limite", "Considerações de Performance", "Comparação com Alternativas" etc.

Escolha da Stack Tecnológica

Não use a stack tecnológica padrão das preferências do usuário (por exemplo, ASP.NET Core MVC, C#, SQL Server), a menos que o tópico do artigo seja essa tecnologia. Os exemplos devem usar a linguagem e o ambiente mais comuns na documentação oficial do tópico e mais amigáveis para iniciantes.

Fluxo de Trabalho

Passo 1: Esclarecer o Tópico e o Ângulo (Perguntar apenas quando realmente necessário)

Se o tópico fornecido pelo usuário já for específico o suficiente, pode-se começar a trabalhar imediatamente (por exemplo, "me escreva um tutorial sobre Vite", "write a tutorial on FastAPI dependency injection"). Não pare para fazer perguntas; vá direto para a fase de pesquisa.

Só é necessário perguntar ao usuário nas seguintes situações:

O nome do tópico pode corresponder a várias coisas diferentes (por exemplo, "Mongo" pode ser o banco de dados MongoDB ou outra coisa).
O escopo é vago a ponto de afetar a direção de todo o artigo (por exemplo, "React" é uma introdução geral ou uma funcionalidade específica?).

Passo 2: Pesquisar Exaustivamente Antes de Escrever

Este é o passo mais importante. Não escreva o conteúdo com base na memória para depois "verificar os fatos"; pesquise primeiro e escreva depois.

Considere a documentação oficial/site e tutoriais de alta qualidade como fontes confiáveis. A documentação oficial é a melhor fonte para obter uma lista precisa de funcionalidades, etapas de instalação e detalhes da API. Tutoriais independentes e blogs são úteis para obter exemplos de uso real, armadilhas comuns e cenários de uso real que a documentação oficial muitas vezes ignora.
Ajuste o número de buscas de acordo com a amplitude do tópico: tópicos focados (uma única ferramenta CLI, uma única funcionalidade de biblioteca) exigem cerca de 4 a 6 buscas; tópicos mais amplos (um framework inteiro) exigem de 8 a 15 buscas ou mais, cobrindo diferentes aspectos (instalação, conceitos principais, configuração, casos de uso comuns, mudanças recentes de versão).
Verifique sempre a versão mais recente. Pesquise por palavras-chave como "release notes", "changelog", "version" e "what's new" para garantir que os comandos de instalação e as descrições de funcionalidades reflitam o estado mais atual, e não informações desatualizadas.
Para as páginas mais relevantes (guia de início oficial, página de instalação, tutoriais importantes), use uma ferramenta de captura de páginas web para ler o texto completo. Não confie apenas nos trechos dos resultados de busca, pois eles geralmente são muito superficiais para escrever um conteúdo preciso.
Respeite os direitos autorais: nunca copie e cole longos trechos de texto de uma fonte. Todo o conteúdo deve ser reescrito com suas próprias palavras, integrando informações de várias fontes, em vez de copiar uma única fonte. Escrever seus próprios exemplos de código é uma prática normal de escrita técnica e não é considerado reprodução de conteúdo.
Anote as URLs das fontes realmente usadas durante a pesquisa para listá-las na seção de recursos adicionais do artigo.

Passo 3: Determinar a Estrutura de Seções do Artigo com Base no Tópico

Não há um modelo fixo. Deixe que a natureza do tópico determine quais seções são relevantes; não force seções irrelevantes em um esqueleto pré-definido. Artigos voltados para iniciantes geralmente cobrem as seguintes partes:

Introdução: O que é isso? Por que alguém usaria isso? Use uma analogia da vida real para explicar.
Funcionalidades/Recursos: O que ele realmente pode fazer? Escolha algumas das funcionalidades mais úteis para iniciantes.
Instalação/Configuração: Inclua apenas se a instalação for realmente relevante (CLI ou bibliotecas precisam; produtos SaaS baseados na web ou conceitos de linguagens de programação podem não precisar).
Início Rápido: Um exemplo mínimo que funcione, com uma explicação do que o leitor verá após a execução.
Exemplos de Uso: Um ou dois exemplos próximos do uso real, mas ainda assim curtos.
Perguntas Frequentes/Solução de Problemas: Inclua apenas se a pesquisa revelar erros ou problemas reais e comuns. Não invente problemas; se a pesquisa não encontrar nada, pule esta seção.
Conclusão e Recursos Adicionais: Finalize e inclua links para a documentação oficial e artigos de referência usados na pesquisa.

A versão avançada pode incluir seções como "Configurações Avançadas" e "Comparação com Alternativas" (consulte a seção "Público-Alvo e Profundidade").

Passo 4: Escrever o Artigo Usando o Formato de Títulos Numerados do HackMD

Esta é uma regra de formatação rigorosa. O HackMD analisa esses formatos e os exibe no painel de sumário/índice. Seguir as regras à risca é muito mais importante do que parecer bonito.

4-1 Início do Documento: Metadados YAML

O HackMD usa os metadados do documento ou o primeiro título como nome da nota. Para evitar que cada nota se chame "1. Introdução", o início do documento deve sempre incluir metadados YAML, definindo o título e as tags:

---
title: Tutorial de Introdução ao Vite
tags: Vite, Front-end, Tutorial
---

Após os metadados, deixe uma linha em branco e comece diretamente com o primeiro título de nível 1, 1\. Introdução. Não escreva # Título do Artigo separadamente, para não adicionar um título não numerado ao sumário.

4-2 Quatro Níveis de Título

Nível	Formato de Numeração	Sintaxe Markdown	Observação
1	`1\.`, `2\.`, `3\.` ...	Setext H1: texto do título em uma linha, linha seguinte com `===`	O ponto final após o número DEVE ser escapado com barra invertida, por exemplo, `2\. Instalação e Configuração`
2	`1.1`, `1.2`, `2.1` ...	Setext H2: texto do título em uma linha, linha seguinte com `---`	Não é necessário escapar, por exemplo, `1.1 Método de Instalação`
3	`1.1.1`, `1.1.2` ...	ATX H3: `### 1.1.1 Texto`
4	`1.1.1.1`, `1.1.1.2` ...	ATX H4: `#### 1.1.1.1 Texto`	É fácil errar, pois cada nível adiciona um número. Verifique cada um.

⚠️ Por que o ponto final do nível 1 DEVE ser escapado:

Se você escrever 2. Instalação e Configuração (sem escapar), o Markdown interpretará essa linha como um "item de lista ordenada", e a linha seguinte, ===, não formará um título Setext. Todo o título ficará com formato incorreto. Ao escrever 2\. Instalação e Configuração, o HackMD removerá a barra invertida ao renderizar, e o leitor verá "2. Instalação e Configuração", mas o título será analisado corretamente.

O nível 2 (1.1) não está no formato "número + ponto + espaço", portanto não será interpretado erroneamente como uma lista, e não precisa ser escapado.

2. Instalação e Configuração        ← Errado: será interpretado como item de lista, === será ignorado
===

2\. Instalação e Configuração       ← Correto: ponto escapado, título Setext analisado corretamente
===

4-3 Regras de Linhas em Branco

O texto do título e a linha de sublinhado (=== ou ---) devem estar em duas linhas consecutivas, sem linhas em branco entre elas. Caso contrário, o Markdown as interpretará como dois blocos de conteúdo não relacionados.
Após a linha de sublinhado, deve haver uma linha em branco antes de começar o próximo parágrafo, título ou linha horizontal.

4-4 Regras para Linhas Horizontais

Para criar uma separação visual clara entre as seções, uma linha horizontal independente --- deve ser adicionada acima de alguns títulos:

Título	Quando adicionar a linha horizontal
Nível 1 (`1\.`)	Sempre. A única exceção é o primeiro título de nível 1 do documento (imediatamente após os metadados YAML).
Nível 2 (`1.1`)	Se o elemento imediatamente acima (ignorando linhas em branco) for o `===` de um título de nível 1, não adicione. Se o elemento acima for texto explicativo, bloco de código, caixa de dica ou outro conteúdo, adicione.
Níveis 3 e 4 (`###`, `####`)	Nunca adicione.

Deve haver uma linha em branco antes e depois de cada linha horizontal. Se --- estiver logo abaixo de uma linha de texto, o Markdown a interpretará como o sublinhado Setext H2 dessa linha, e não como uma linha horizontal. Isso quebrará todos os níveis de título subsequentes.

Exemplo correto: Fim do parágrafo anterior → linha em branco → linha única com --- → linha em branco → próximo título.

...fim da seção anterior...

---

1.2 Por que Precisamos Disso
---

...conteúdo desta seção...

4-5 Outras Regras Estritas

Cada nível de numeração adiciona exatamente um número (1 → 1.1 → 1.1.1 → 1.1.1.1), sem pular níveis. A numeração dentro do mesmo nível deve ser contínua (após 2.1 vem 2.2, não 2.4).
Os níveis 1 e 2 usam sublinhados Setext (=== / ---), não # / ##. Os níveis 3 e 4 usam ### / ####. Não misture; # 1\. Introdução está errado.
Não ultrapasse o nível 4. Se precisar de mais níveis, significa que a seção deve ser dividida ou reorganizada.
Nem toda seção precisa de quatro níveis. Seções curtas podem ter apenas 1\. xxx mais o texto do corpo, sem subseções.
Todos os títulos que começam com # no documento devem ter numeração. A única exceção é a etiqueta de descrição do bloco de código dentro de um container :::success (consulte a seção 5-1), que tem o formato #### `Exemplo de Código: Breve Descrição`. Fora isso, nenhum título não numerado é permitido.
O texto do título deve estar sempre em chinês tradicional, independentemente do idioma usado pelo usuário ao dar instruções.

4-6 Exemplo de Estrutura Completa

---
title: Tutorial de Introdução ao Vite
tags: Vite, Front-end, Tutorial
---

1\. Introdução
===

1.1 O que é Isso
---

Conteúdo explicativo...

---

1.2 Por que Precisamos Disso
---

Conteúdo explicativo...

---

2\. Instalação
===

Antes de começar a instalação, verifique os seguintes pré-requisitos:

---

2.1 Requisitos de Sistema
---

### 2.1.1 Suporte a Sistemas Operacionais

Conteúdo explicativo...

### 2.1.2 Pacotes Dependentes

Conteúdo explicativo...

---

2.2 Passos de Instalação
---

### 2.2.1 Instalar Usando Gerenciador de Pacotes

#### 2.2.1.1 Ambiente Windows

Conteúdo explicativo...

#### 2.2.1.2 Ambiente macOS

Conteúdo explicativo...

Este exemplo demonstra:

1.1 vem imediatamente abaixo de === de 1\. Introdução, portanto, sem linha horizontal.
O elemento acima de 2.1 é texto explicativo, portanto, com linha horizontal.
2\. Instalação não é o primeiro título de nível 1, portanto, com linha horizontal acima.

Passo 5: Estilos de Bloco do HackMD

5-1 Blocos de Código

Cada bloco de código no artigo deve ser envolvido por um container :::success do HackMD, seguindo estas regras:

A primeira linha dentro do container deve ser uma etiqueta de descrição no formato #### `Exemplo de Código: Breve Descrição`: use um título ####, o texto da etiqueta entre crases, sem emoji e sem numeração. Esta é a única exceção à regra 4-5 de que todos os títulos devem ser numerados.
Entre a etiqueta de descrição e o bloco de código, deixe uma linha em branco.
O bloco de código deve sempre especificar a linguagem (bash, html, csharp, json, etc.).
Quando o código tiver 3 linhas ou mais, adicione = após o nome da linguagem para exibir números de linha (por exemplo, ```html=). Para comandos curtos de 1 a 2 linhas, não adicione = para evitar poluição visual.
Os exemplos devem ser copiáveis e executáveis diretamente. Abaixo do bloco de código (fora do container), explique em uma ou duas frases o que o leitor verá após a execução.

Exemplo de bloco de código com várias linhas:

:::success
#### `Exemplo de Código: Criar o Primeiro Projeto Vite`

```bash=
npm create vite@latest my-app
cd my-app
npm install
npm run dev
```
:::

Após a execução, o terminal exibirá um endereço local (por exemplo, `http://localhost:5173`). Abra-o no navegador para ver a página de exemplo.

Exemplo de comando curto:

:::success
#### `Exemplo de Código: Verificar a Versão do Node.js`

```bash
node -v
```
:::

5-2 Dicas Importantes

Para conteúdo que precisa de atenção especial do leitor (erros comuns de iniciantes, conceitos que devem ser memorizados), use o seguinte formato de caixa de dica. A caixa de dica deve ser precedida e seguida por uma linha horizontal ---. As linhas horizontais também devem seguir a regra de "uma linha em branco antes e depois":

...fim do parágrafo anterior...

---

>[!Warning] 💡 **Dica Importante**
>
>---
> Se você não sabe nada, **lembre-se apenas deste comando**.
> Após cada passo, o plug-in dirá o que inserir em seguida.

---

...próximo parágrafo...

Use a caixa de dica apenas para pontos realmente importantes, no máximo um ou dois por seção. Usar demais reduzirá o efeito de destaque.
Se a caixa de dica for imediatamente seguida por um título de nível 1 ou 2 que precise de uma linha horizontal, a linha --- no final da caixa de dica também servirá como a linha horizontal para esse título. Use apenas uma linha ---; não coloque duas linhas --- consecutivas.

Passo 6: Auto-Verificação Antes da Entrega

Antes de entregar, verifique cada item do artigo. Corrija os problemas antes de enviar:

Passo 7: Produzir o Resultado Final

Por padrão, entregue o artigo como um arquivo .md, com o nome do tópico, por exemplo, Vite-Tutorial-Introducao.md. Tutoriais geralmente são longos; salvá-los como arquivo facilita a cópia completa para o HackMD pelo usuário e evita que blocos de código sejam truncados. Na conversa, apenas resuma brevemente o conteúdo do artigo.
Se o usuário solicitar que o conteúdo seja colado diretamente na conversa, ou se o ambiente atual não tiver ferramentas para criar arquivos, produza o texto completo na conversa. Como o artigo contém blocos de código com ```, o texto completo deve ser envolvido por quatro crases ou ~~~ para evitar que os blocos de código internos interrompam o bloco externo, causando quebra de conteúdo.
Após a entrega, liste brevemente as principais fontes de referência usadas (links para documentação oficial, artigos de referência importantes) para que o usuário possa verificar ou se aprofundar.

johnsonshsu/claudecodedemo

O que é claudecodedemo?

Perguntar na sua IA favorita

Documentação