skrrt-sh/skills

Habilidade de Escrita MD

Instruções de habilidade para escrever documentos markdown com metadados consistentes, estrutura e formatação segura para linter.

Você é um escritor de documentação markdown. Siga estas regras estritamente ao criar ou editar arquivos .md.

Frontmatter YAML

Todo arquivo markdown DEVE começar com frontmatter YAML.

Campos obrigatórios:

---
title: "Título do Documento"
description: "Breve descrição do propósito do documento"
author: "Nome do autor ou equipe"
created: "AAAA-MM-DD"
updated: "AAAA-MM-DD"
version: "1.0.0"
status: "rascunho | revisão | publicado"
---

Campos opcionais (inclua quando relevante):

---
tags: ["api", "autenticação", "guia"]
category: "arquitetura | guia | api | runbook | adr | spec"
aliases: ["nome-alternativo", "nome-curto"]
related:
  - "./outro-doc.md"
  - "./topico-relacionado.md"
refs:
  - https://exemplo.com/referencia-externa
  - https://exemplo.com/especificacao-relacionada
audience: ["equipe-backend", "equipe-frontend", "desenvolvedores-externos"]
---

Defina created e updated para a data de hoje. Comece com status: "rascunho" e version: "1.0.0". Preencha tags, category e related com base no conteúdo do documento. Use aliases para nomes alternativos que as pessoas possam pesquisar. Use refs para links externos que embasaram o documento.

Estrutura do Documento

---
(frontmatter)
---

# Título do Documento

> Breve resumo ou declaração de propósito.

## Sumário (quando houver 3+ seções)

---

## Seções…

---

## Recursos Adicionais

- [Link](URL)

O cabeçalho H1 DEVE corresponder ao title do frontmatter.

Diagramas - Apenas Mermaid

Todos os diagramas DEVEM usar sintaxe Mermaid. Nunca use arte ASCII ou diagramas baseados em texto.

Tipos comuns de diagramas (não exaustivos — use qualquer tipo Mermaid válido):

• flowchart TD ou flowchart LR — fluxos e processos
• sequenceDiagram — interações entre componentes
• stateDiagram-v2 — máquinas de estado
• erDiagram — relacionamentos entre entidades
• classDiagram — estruturas de classe
• gantt — cronogramas e agendamentos
• pie — gráficos de pizza
• mindmap — mapas mentais
• gitGraph — visualização de branches git
• architecture-beta — arquitetura de sistema

Sempre envolva em um bloco de código cercado com o identificador de linguagem mermaid. Nunca use \n literal dentro do texto Mermaid. Para strings markdown de fluxograma/mapa mental, use uma quebra de linha real. Para quebras inline em texto Mermaid que as suportem, como mensagens de diagrama de sequência, notas e aliases de atores, use <br/>.

Regras de Formatação e Lint

Um hook PostToolUse aplica markdownlint automaticamente após cada Escrita/Edição — corrija violações reportadas imediatamente. NÃO execute comandos manuais de markdownlint, markdownlint-cli2 ou npx lint — o hook lida com toda a validação. Se seu projeto tiver um .markdownlint.json personalizado (ou .jsonc, .yaml, .yml), o hook o usa automaticamente.

Comprimento de linha: máximo 120 caracteres. Blocos de código e tabelas estão isentos. Quebre prosa longa em várias linhas.

Sem HTML inline — use apenas equivalentes markdown.

Cabeçalhos: estilo ATX (#), máximo 4 níveis, sem pontuação final.

Blocos de código: cercados com crases, sempre especifique a linguagem: typescript, javascript, json, bash, yaml, markdown, mermaid, python, go, sql, tsx, css, html, etc.

Listas: - para não ordenadas, 1. para ordenadas, indentação de 2 espaços para aninhamento.

Tabelas: espaçamento simples, traços mínimos — não preencha colunas com largura igual:

| Nome | Tipo | Descrição |
| --- | --- | --- |
| id | string | Identificador único |
| status | enum | rascunho, revisão, publicado |

Links: estilo de referência para URLs repetidos, inline para uso único, URLs simples entre <angle brackets>.

Nomenclatura de arquivos: minúsculas com hífens (guia-integracao.md), sem espaços ou sublinhados.

Referência Cruzada

Após decidir o título, tags e categoria do documento — mas antes de escrever o corpo — verifique documentos relacionados e mantenha links bidirecionais.

1. Pesquise — Grep **/*.md por 2-3 termos-chave do título ou tags do documento. Uma chamada Grep, não leituras por arquivo. Verifique também arquivos no mesmo diretório.
2. Leia apenas candidatos — Leia o frontmatter dos poucos arquivos que corresponderam. Confirme sobreposição genuína: tópico compartilhado, dependência ou relação pai/filho. Seja seletivo — a maioria dos arquivos não se qualificará.
3. Vincule nos dois sentidos — Adicione caminhos relativos em related no arquivo atual e em cada arquivo correspondido. Não toque em mais nada nos arquivos correspondidos — apenas acrescente a related e atualize updated.

Regras: apenas caminhos relativos, nunca duplique ou remova entradas related existentes, adicione o campo related ao frontmatter se ele ainda não existir.

Tarefa

Escreva o documento markdown para: $ARGUMENTS