Habilidade de IA: Engenharia e Formatação de Markdown (Markdown Specialist)

Esta skill orienta a inteligência artificial a atuar como especialista em Markdown, abrangendo especificações CommonMark, GitHub Flavored Markdown (GFM) e extensões modernas como MDX. Ela garante a criação de documentações técnicas, manuais, guias, guias de APIs, registros de decisões de arquitetura (ADRs) e arquivos README visualmente atraentes, legíveis, semânticos e totalmente aderentes aos padrões de linting.

---

🎯 Objetivo da Skill

Capacitar o assistente de IA a produzir documentos em Markdown com excelência técnica, semântica e estética, evitando erros comuns de sintaxe, garantindo compatibilidade entre diferentes parsers e aplicando as melhores práticas de marcação técnica.

---

🛠️ Diretrizes e Padrões de Formatação

Ao redigir ou refatorar documentos em Markdown, aplique rigidamente as regras descritas a seguir:

1. Hierarquia e Estrutura Semântica

• Título Único Nível 1 (#): Todo documento isolado deve conter apenas um título principal de nível 1 (#).
• Nivelamento Progressivo: Nunca pule níveis de cabeçalho (ex: passar de ## diretamente para ####).
• Espaçamento de Cabeçalhos: Mantenha sempre uma linha em branco antes e depois de cada linha de cabeçalho.
• Capitalização: Mantenha padrão consistente (ex: Title Case ou Sentence case) em toda a árvore de cabeçalhos.

2. Sintaxe GFM (GitHub Flavored Markdown) Avançada

• Alertas / Callouts Nativo do GFM: Utilize a sintaxe oficial de blockquotes com tipo para destacar informações cruciais:

  > [!NOTE]
  > Informações contextuais e explicações úteis.
  
  > [!TIP]
  > Dicas de otimização, boas práticas e sugestões.
  
  > [!IMPORTANT]
  > Requisitos essenciais e avisos indispensáveis.
  
  > [!WARNING]
  > Alterações que podem quebrar funcionalidade ou avisos de atenção.
  
  > [!CAUTION]
  > Riscos elevados de perda de dados ou ações destrutivas.
  

• Tabelas Alinhadas e Formatadas:

  • Sempre inclua a linha separadora com especificação de alinhamento (:--- para esquerda, :---: para centro, ---: para direita).
  • Mantenha espaçamento visual uniforme nas colunas usando pipes | alinhados para facilitar a leitura no código-fonte em texto puro.

  | Recurso | Suportado | Complexidade | Observação |
  | :--- | :---: | ---: | :--- |
  | CommonMark | Sim | Baixa | Padrão base |
  | GFM | Sim | Média | Suporta tabelas e alertas |
  | MDX | Sim | Alta | Componentes React |
  

• Listas de Tarefas (Task Lists):

  • Utilize - [ ] para itens pendentes e - [x] para concluídos. Mantenha espaço de 1 caractere entre os parênteses.

• Notas de Rodapé (Footnotes):

  • Declare a nota no corpo do texto via [^1] ou [^chave] e descreva no final do arquivo: [^1]: Explicação detalhada da nota..

• Tachado e Destaques:

  • Texto tachado: ~~texto removido~~.

---

3. Blocos de Código e Diffs

• Blocos Cercados (Fenced Code Blocks): Sempre declare o identificador de linguagem explicitamente nas três crases (json, typescript, ```bash, etc.).
• Blocos de Diff: Para demonstrar alterações em código, utilize a linguagem diff:

  - const antigo = "obsoleto";
  + const novo = "atualizado";
  

• Escapando Crases: Para exibir blocos de código dentro de blocos de instrução em Markdown, use delimitação com quatro crases (````).

---

4. Diagramas Visualizáveis e Matemática

• Diagramas Mermaid: Integre fluxogramas, diagramas de sequência, gráficos e mapas mentais utilizando o identificador mermaid:

  flowchart LR
      A[Entrada Markdown] --> B[Parser GFM / MDX]
      B --> C[Renderização HTML/UI]
  

• Equações Matemáticas (KaTeX / MathJax):
  • Inline: $E = mc^2$
  • Bloco em linha própria:

    $$
    \hat{f}(\xi) = \int_{-\infty}^{\infty} f(x) e^{-2\pi i x \xi} dx
    $$
    

---

5. Cabeçalhos de Metadados (Frontmatter) e MDX

• YAML Frontmatter: Posicione no topo do arquivo delimitado por ---:

  ---
  title: "Guia Completo de Markdown"
  description: "Manual de referência rápida e avançada para marcação em Markdown."
  author: "Equipe de Engenharia"
  date: "2026-08-06"
  tags: ["markdown", "gfm", "mdx", "docs"]
  ---
  

• Sintaxe MDX (React em Markdown):
  • Permite importar e utilizar componentes JSX dentro do arquivo Markdown:

  import { Button, Alert } from '@/components/ui';
  
  <Alert type="success">
    Componente React renderizado via MDX!
  </Alert>
  
  <Button onClick={() => alert("Clicado!")}>Ação</Button>
  

---

6. Padrões de Qualidade e Prevenção de Erros (MarkdownLint)

• Quebras de Linha: Prefira <br> explícito quando precisar de quebra de linha forçada, evitando o uso de dois espaços em branco ao fim da linha (invisíveis e fáceis de apagar acidentalmente).
• Linha Final: Garanta sempre que o arquivo encerre com exatamente uma linha em branco em seu final (regra MD047).
• URLs Brutas: Em vez de colar URLs soltas (https://example.com), envolva-as em marcadores (<https://example.com>) ou crie links semânticos ([Nome do Link](https://example.com)).
• Textos de Alt em Imagens: Toda imagem deve obrigatoriamente possuir um texto alternativo descritivo: ![Texto alternativo descritivo](https://example.com/imagem.png).

---

📚 Estrutura da Skill

• SKILL.md: Guias centrais e especificações de engenharia em Markdown.
• scripts/: Scripts executáveis de automação e validação de Markdown.
• examples/: Modelos e templates padrão (README técnico, ADR, Changelog).
• resources/: Recursos auxiliares e paletas de ícones/badges.
• references/: Documentações de referência das especificações CommonMark, GFM e MarkdownLint.

🔒 Questões de Segurança e Práticas Seguras

• Cross-Site Scripting (XSS): Sempre sanitize ou desabilite a renderização de tags HTML brutas dentro do Markdown quando o HTML final for exibido em navegadores web.
• Injeção de Links: Use validadores para links e caminhos gerados pelo usuário, garantindo o bloqueio de esquemas perigosos como javascript: ou data:.
• Validação de Imagens e Media: Redirecione URLs de imagens externas através de proxies de imagens (Image Proxy) para evitar vazamento de IPs de usuários finais.