Este arquivo é destinado aos consumidores da habilidade, não aos contribuidores. Consulte AGENTS.md para o contexto de desenvolvimento — como esta habilidade é construída, iterada e testada.
O que Inicialização de Workspace de Documentação faz?
Esta habilidade ensina um agente de IA a inicializar um workspace de documentação do zero em um diretório vazio (ou quase vazio). O resultado é uma base de conhecimento versionada, baseada em sistema de arquivos, totalmente autossuficiente — de propriedade do usuário, gratuita, sem dependência de fornecedor e estruturada para que o agente que trabalha nela nunca precise pensar sobre organização, formatação ou ferramentas.
A ideia central
Um workspace inicializado contém seu próprio AGENTS.md — uma "mini-habilidade congelada" por workspace e específica para o tópico, que o agente lê ao entrar. O AGENTS.md é criado a partir de um modelo que esta habilidade fornece. Uma vez que o workspace existe, o agente segue o AGENTS.md, não esta habilidade. Este é o ponto central: pré-definir as regras uma vez e nunca mais queimar tokens rederivando-as.
Quando usar esta habilidade
Use esta habilidade apenas quando:
- O usuário explicitamente deseja criar / configurar / inicializar / estruturar um workspace de documentação, pasta de docs ou base de conhecimento.
- O diretório de destino está vazio ou quase vazio (ou o usuário optou explicitamente por prosseguir apesar de arquivos existentes).
- O diretório de destino não contém um
AGENTS.md(o que significaria que já está inicializado).
Se AGENTS.md já existir no destino: não execute esta habilidade. Leia o AGENTS.md existente e siga-o. O usuário já está em um workspace inicializado.
Quando NÃO usar esta habilidade
- O usuário deseja adicionar um documento, editar um documento, vincular documentos ou reorganizar dentro de um workspace existente — o próprio
AGENTS.mddo workspace governa isso. - O usuário deseja fazer push para o GitHub, renderizar o workspace em um navegador ou configurar hospedagem — preocupações diferentes, habilidades diferentes.
- O usuário está fazendo uma pergunta genérica sobre documentação, escrita ou anotações — nenhuma habilidade é necessária.
O que a habilidade produz
Quando invocada, esta habilidade cria um workspace contendo:
| Arquivo / Diretório | Propósito |
|---|---|
AGENTS.md | A "mini-habilidade congelada" por workspace. 95% regras, 5% resumo do tópico. O agente lê isso ao entrar. |
README.md | Visão geral do workspace. Introdução mais rica, índice gerado automaticamente, ponteiro para AGENTS.md. |
index.yaml | Ordenação de documentos para o diretório raiz. Vazio por padrão. |
.gitignore | Padrões sensatos: backups, lixo do SO, arquivos de editor, Node. |
package.json | Dependências de desenvolvimento: prettier, markdownlint-cli, js-yaml. Scripts npm para ferramentas. |
.prettierrc | Configuração do Prettier: linha de 120 caracteres, proseWrap preserve. |
.markdownlint.json | Configuração do markdownlint com regras de nitpick desabilitadas. |
scripts/ | Scripts auxiliares: format.js, validate.js, hash.js, reindex.js. |
assets/ | Diretório vazio para ativos compartilhados. Criado na raiz do workspace. |
Um repositório Git é inicializado no workspace se git estiver disponível. As dependências de desenvolvimento são instaladas se Node e npm estiverem disponíveis.
Fluxo de trabalho de inicialização
Siga estes passos em ordem. Confirme com o usuário em cada etapa onde indicado. Nunca presuma.
Passo 1 — Confirmar localização de destino
Pergunte ao usuário: "Inicializarei o workspace de documentação em <cwd>. Isso está correto? (sim / não / especifique um caminho)"
- Se
sim: prossiga com cwd como destino. - Se
não: peça o caminho correto, confirme e prossiga. - Se o usuário disse "nesta pasta" ou similar: assuma cwd, mas ainda assim confirme.
Passo 2 — Confirmar que o destino está vazio (ou obter aceitação)
Liste o conteúdo do diretório de destino (excluindo arquivos ocultos como .git).
Se vazio: prossiga para o Passo 3.
Se não vazio:
- Mostre ao usuário o que está lá.
- Explique: "Este diretório não está vazio. Por padrão, esta habilidade se recusa a inicializar em um diretório não vazio. Posso (a) abortar, (b) você confirma que deseja que eu prossiga de qualquer forma e deixarei os arquivos existentes intactos, ou (c) você especifica um subdiretório para criar o workspace."
- Aguarde confirmação explícita. Se o usuário não der afirmação positiva estrita, aborte.
- Se o usuário disser "vá em frente" ou "sim, prossiga" — registre isso como aceitação e continue.
Se AGENTS.md já existir no destino: pare. O workspace já está inicializado. Informe o usuário e ofereça-se para ler o AGENTS.md existente.
Se o git já estiver inicializado no destino: pule a etapa git init posteriormente, mas prossiga.
Passo 3 — Coletar o resumo do tópico
Pergunte ao usuário: "Para que é este workspace de documentação? Descreva o tópico em 1–2 parágrafos curtos. Isso se tornará o resumo do tópico no AGENTS.md e a introdução no README.md."
Regras do resumo do tópico:
- 1 parágrafo (preferido), no máximo 2 parágrafos
- Prosa simples, sem formatação, sem listas
- Declaração clara do que o workspace documenta
Se o usuário der uma única frase: tudo bem, use-a. Se o usuário der uma descrição mais longa: condense-a (com confirmação do usuário) ou use no máximo 2 parágrafos. Se o usuário disser "você decide" ou "ainda não sei": peça pelo menos uma frase — o resumo do tópico é a única parte específica do tópico no AGENTS.md, e o workspace precisa de alguma âncora.
Passo 4 — Executar o script de inicialização
Depois de ter:
- O caminho de destino
- A confirmação de que o diretório é apropriado
- O resumo do tópico
...execute o script de inicialização:
node /assets/skill-scripts/bootstrap.js --target --topic ""
O script irá:
- Verificar a disponibilidade do Node.js (pular artefatos dependentes de Node e avisar se não estiver disponível)
- Verificar a disponibilidade do git (pular
git initse não estiver disponível) - Criar a estrutura de diretórios
- Instanciar todos os modelos de
<skill-dir>/assets/templates/com{{TOPIC_SUMMARY}}e{{CREATED}}substituídos - Copiar os scripts fornecidos com o workspace (
format.js,validate.js,hash.js,reindex.js) para<target>/scripts/ - Executar
npm install(se Node + npm estiverem disponíveis) - Executar
git init(se git estiver disponível) - Imprimir um resumo do que foi criado
Se o script falhar (por exemplo, permissões, ferramenta ausente), recorra à criação manual de arquivos usando os modelos em <skill-dir>/assets/templates/. Copie manualmente cada modelo para o destino, substitua os placeholders e crie o diretório de scripts copiando de <skill-dir>/assets/workspace-scripts/.
Passo 5 — Informar o usuário sobre o que foi criado
Após o script terminar, resuma:
- Quais arquivos e diretórios foram criados
- Se
git initfoi executado (ou pulado, com um lembrete) - Se
npm installfoi executado (ou pulado, com um lembrete) - Que
AGENTS.mdagora é o documento governante para este workspace - Que o workspace está pronto para uso
Depois pergunte: "Gostaria de começar a trabalhar na documentação ou prefere revisar a estrutura primeiro?"
Modelos
Todos os arquivos de modelo estão em <skill-dir>/assets/templates/. O script de inicialização os copia e substitui.
| Modelo | Produz |
|---|---|
AGENTS.md.template | AGENTS.md |
README.md.template | README.md |
index.yaml.template | index.yaml |
_gitignore_.template | .gitignore (com underscore vira prefixo de ponto) |
package.json.template | package.json |
_prettierrc_.template | .prettierrc |
_markdownlint.json_.template | .markdownlint.json |
Placeholders usados:
{{TOPIC_SUMMARY}}— substituído pela descrição do tópico do usuário{{CREATED}}— substituído pela data de hoje (AAAA-MM-DD)
O script de inicialização lida automaticamente com a convenção de underscore (um arquivo nomeado _foo_.template se torna .foo na saída).
Scripts fornecidos com o workspace
Após a inicialização, o workspace tem estes scripts auxiliares em scripts/:
| Script | Propósito |
|---|---|
scripts/format.js | Executa o Prettier em todos os arquivos .md/.html/.json/.yaml |
scripts/validate.js | Executa markdownlint em todos os arquivos .md |
scripts/hash.js | Calcula o hash SHA-256 de um arquivo, opcionalmente escreve em assets/ e atualiza o manifesto |
scripts/reindex.js | Regenera a seção de índice automático no README.md |
Todos são invocáveis via npm:
npm run formatnpm run validatenpm run hashnpm run reindex
Referências
Para contexto mais profundo sobre tópicos específicos, consulte o diretório references/:
references/asset-management.md— Como adicionar, vincular e migrar ativos (armazenamento endereçado por conteúdo, manifesto, por documento vs compartilhado)references/document-promotion.md— Como promover um documento de arquivo único para uma pasta quando ele ganha subdocumentos
Estes são carregados no contexto apenas quando relevantes. O AGENTS.md principal cobre os casos comuns; as referências são para os menos comuns.
Lembretes para o agente (durante a inicialização)
- O resumo do tópico é o único conteúdo específico do tópico que o usuário fornece. Todo o resto é modelado. Não pergunte sobre nomeação de arquivos, estilos de link, campos de frontmatter, estilo de mensagem de commit ou qualquer outra regra — elas estão incorporadas nos modelos.
- Se o usuário pedir algo que os modelos não suportam, traga à tona. Não invente novas convenções silenciosamente. A ação correta é (a) anotar para uma revisão futura do modelo, ou (b) implementar como uma exceção com confirmação explícita.
- Após a inicialização, esta habilidade está concluída. Na próxima vez que o usuário quiser fazer qualquer coisa no workspace, o agente lê
AGENTS.mde o segue. Esta habilidade não é executada novamente a menos que o usuário peça explicitamente para inicializar outro workspace ou reinicializar o existente.