Docsbook
Visão geral

docs-skills: capacidades modulares para agentes de IA em docs

Em 2026, os agentes de IA não apenas leem a documentação — eles agem sobre ela. Eles publicam um site de docs, corrigem links quebrados, geram llms.txt, escrevem páginas faltantes, auditam acessibilidade. A maneira como eles sabem como realizar essas ações é através de "habilidades" — descrições de capacidade empacotadas, descobertas e declarativas.

Este post explica o que são habilidades, o que o catálogo de código aberto do Docsbook contém hoje e como a camada se encaixa entre o MCP e seu conteúdo.

TL;DR#

  • Uma "habilidade" é um SKILL.md arquivo com frontmatter que descreve uma capacidade — o que faz, quando acioná-la, quais ferramentas precisa
  • Agentes de IA (Claude Code, Cursor) leem habilidades e as executam de forma autônoma
  • docs-skills é um catálogo de habilidades de documentação de código aberto
  • Docsbook MCP expõe find_skill para que os agentes descubram habilidades por consulta em tempo de execução
  • Você pode instalar habilidades localmente (npx docs-skills install) ou usá-las através do MCP

Como é uma habilidade#

Um mínimo SKILL.md:

---
name: docs-pr-check
description: Validate documentation changes in a pull request — check for broken links, missing frontmatter, accessibility issues, and SEO regressions. Use when reviewing docs PRs.
category: automation
mode: agent
keywords: [pull request, broken links, frontmatter, review]
requires_docsbook_mcp: true
version: 1
---
 
# docs-pr-check
 
When the user opens a docs PR, run this skill to validate the change.
 
Steps:
 
1. Run `doc_search_unresolved` to find broken links in changed files
2. Verify YAML frontmatter on every new or modified `.md` file
3. Check that internal links resolve
4. Suggest improvements
 
Tools used: `doc_search_unresolved`, `doc_outline`, `doc_resolve_link` (Docsbook MCP)

A habilidade acima é uma ilustração do formato, não uma entrada no catálogo — as quatro habilidades reais estão listadas mais abaixo. Os campos de frontmatter são aqueles que o esquema realmente define: name, description, category, mode, keywords, requires_docsbook_mcp e version.

O frontmatter é o contrato. O corpo é o prompt.

Por que isso é importante para a documentação#

Três problemas que as habilidades resolvem:

1. Descobribilidade de capacidades#

Sem habilidades, um agente de IA lendo seus documentos MCP tem que adivinhar o que fazer. Com habilidades, o agente chama find_skill("audit my docs") e recebe um SKILL.md com instruções exatas.

2. Reutilização modular#

Uma habilidade escrita para um projeto funciona em qualquer projeto. docs-manage é o manual para escrever uma página e executar o site em que ela reside, e se aplica a qualquer repositório de documentação, no Docsbook ou não.

3. Composição#

As habilidades se compõem em vez de se multiplicar. Cada uma carrega um references/ diretório de documentos focados que carrega apenas quando a tarefa precisa deles — docs-manage sozinho mantém referências separadas para recuperação, conversão e regras de escrita. O agente lê a habilidade, então lê a única referência que importa, em vez de carregar um catálogo.

O catálogo de habilidades#

O que há no catálogo de habilidades dos documentos?#

docs-skills é um catálogo de código aberto de quatro habilidades, cada uma cobrindo um trabalho que um agente faz com documentação. Anteriormente, era uma longa lista de habilidades específicas; foi consolidado porque um agente que escolhe entre cinquenta descrições quase sinônimas escolhe mal, e quatro trabalhos são distinguíveis.

Habilidade O trabalho que faz
docs-create Criar documentação que não existia — a partir de um site de produto, um repositório de código, outra plataforma de documentos da qual você está migrando, ou nada além de um nome de produto
docs-analyze Encontrar o que está errado com a documentação que já existe e corrigi-la, começando pelas posições de busca, sinais de resposta de IA, comportamento do leitor e funis
docs-manage O manual para escrever uma página e para gerenciar o site em que ela reside — tipo de página, estrutura, estilo, público, recuperação, conversão
docs-automate Configurar as coisas que devem continuar acontecendo sem que ninguém se lembre — guardas de desvio, gatilhos de tradução, anúncios de lançamento

Cada habilidade é um SKILL.md independente no repositório do GitHub, com um diretório references/ que o agente lê sob demanda. O índice legível por máquina é index.json no mesmo repositório; as contagens acima foram lidas a partir dele em 2026-09-03.

Duas maneiras de usar habilidades#

Instalação local#

npx docs-skills install

Copia o catálogo para .claude/skills/, .cursor/rules/ ou AGENTS.md (dependendo da ferramenta detectada). Funciona offline. Atualiza com docs-skills update.

Este padrão: as habilidades das suas ferramentas vivem no seu repositório, controlado por versão.

Descoberta em tempo de execução via MCP#

Se você tiver o Docsbook MCP conectado, seu agente chama:

find_skill({ query: "audit my docs for SEO and accessibility" })

Ele retorna as habilidades mais correspondentes com raw_url para cada SKILL.md. O agente busca e segue as instruções.

Esse padrão: sem instalação local, sempre a versão mais recente, funciona em diferentes máquinas.

Como os agentes de IA usam habilidades na prática#

Três fluxos de trabalho reais que vimos:

Fluxo 1: Revisão de PR#

Um desenvolvedor abre um PR que toca docs/. O código Claude (ou Cursor) invoca docs-pr-check. A habilidade:

  1. Lista os arquivos .md alterados
  2. Chama doc_search_unresolved em cada um
  3. Verifica a completude do frontmatter
  4. Relata as descobertas como um comentário de PR

O desenvolvedor vê o relatório antes de um revisor humano. Muitos problemas de documentação nunca chegam à equipe.

Fluxo 2: Detecção de conteúdo obsoleto#

A cron semanal na configuração do usuário invoca docs-stale-watcher. A habilidade:

  1. Consulta a análise do Docsbook para páginas com tráfego, mas sem edições em mais de 90 dias
  2. Cruzamento com o gráfico de documentos
  3. Lista candidatos para atualização

A saída é uma lista de páginas a serem atualizadas — lacunas de conteúdo com sinal de receita.

Fluxo 3: Ajuste de chat AI#

O usuário diz "meu chat AI está alucinado sobre a funcionalidade X." O agente invoca docs-tune-ai-chat. A habilidade:

  1. Chama get_ai_questions para ver consultas recentes não respondidas
  2. Chama get_negative_feedback para ver padrões de desaprovação
  3. Identifica conteúdo ausente ou fraco
  4. Sugere uma nova página ou alteração no prompt do sistema

Este é o loop "agente melhora agente".

Habilidades + MCP: a arquitetura#

As habilidades dizem ao agente o que fazer. As ferramentas MCP dizem ao agente como fazer isso.

  • Uma habilidade diz "auditar acessibilidade para cada página"
  • O corpo da habilidade lista etapas como "chamar doc_list_pages, então doc_outline em cada uma"
  • MCP expõe as ferramentas reais que a habilidade invoca

Nenhuma delas é suficiente sozinha. Juntas, elas formam um ciclo completo: descoberta (find_skill) → instruções (SKILL.md) → execução (ferramentas MCP).

Como isso se parece para seus próprios documentos#

Se você lançar um produto voltado para desenvolvedores e quiser que agentes de IA interajam bem com seus documentos, três etapas:

  1. Publique em uma plataforma com llms.txt — Docsbook gera um automaticamente por espaço de trabalho
  2. Exponha um servidor MCP ou confie na plataforma — Docsbook MCP está incluído
  3. Instale as habilidades de documentos relevantes localmente — npx docs-skills install

Depois disso, qualquer agente (Claude Code, Cursor, ChatGPT com HTTP MCP) pode trabalhar autonomamente com seus documentos.

Crie sua própria habilidade#

Se você tem um fluxo de trabalho de documentação que não está no catálogo, contribua com um. O formato SKILL.md é simples, o catálogo é público, as contribuições são publicadas em dias.

Uma habilidade útil é:

  • Específica (um trabalho, bem feito)
  • Componível (chama ferramentas MCP existentes)
  • Acionada por uma intenção clara do usuário
  • Documentada com exemplos

O repositório tem um SKILL.md modelo e um guia de contribuição.

Docsbook oferece suporte a docs-skills: a ferramenta MCP find_skill para descoberta em tempo de execução, e npx docs-skills install para uma cópia local. Publique um espaço de trabalho e o endpoint MCP vem com ele — os passos de configuração estão em docsbook.io/mcp.

Comece grátis — sem cartão de crédito

Próximos passos#

Updated

Esta página foi útil?

Desenvolvido por Docsbook