Conteúdo pronto para agentes
Um site de documentação criado apenas para pessoas é uma parede de HTML para todo o resto. Um agente que chega até ele precisa adivinhar qual página importa, extrair informações do texto e não tem como agir com base no que leu. O Docsbook publica a mesma documentação por meio de quatro interfaces que uma máquina consome diretamente — para que um agente possa encontrar o método, ler o corpus, navegar pela estrutura e alterá-la.
As quatro não são alternativas. Elas respondem a quatro perguntas diferentes que um agente faz em sequência: como este trabalho é feito, o que posso chamar, onde isso está e o que existe, afinal.
o catálogo SKILL.md: quatro habilidades de orquestração que ensinam a qualquer agente como o trabalho de documentação é realmente feito, além de como elas são descobertas, versionadas e executadas
140 ferramentas tipadas por meio do Model Context Protocol: consulte o agente docsbook_expert e receba instruções, leia páginas, faça commit delas, leia análises, altere configurações e inicie execuções de agentes
o grafo de documentos: páginas, títulos, links e âncoras como nós e arestas que um agente pode percorrer em vez de pesquisar com grep
o modelo de autenticação, os escopos dos tokens, o que o servidor armazena e as lacunas de conformidade apresentadas claramente
o índice legível por máquina do site publicado, para um agente sem token e sem checkout
O que cada superfície oferece#
| Superfície | A pergunta do agente | O que ele obtém | O que isso custa |
|---|---|---|---|
| Catálogo SKILL.md | "Como este trabalho é feito corretamente?" | Um fluxo de trabalho com proteções, etapas ordenadas e critérios de aceitação, obtido do GitHub | Nada — o catálogo é público e find_skill nunca é medido |
| Servidor MCP | "O que posso chamar e em qual projeto?" | 140 ferramentas por trás de um agente docsbook_expert, um bloco instructions no momento da conexão, erros estruturados que indicam o próximo passo |
Medido por chamada e descontado do saldo do projeto; as chamadas de descoberta são gratuitas |
| Grafo de documentos | "Onde este conceito está e o que aponta para ele?" | Páginas e títulos como namespaces de nós separados, quatro tipos de aresta, links quebrados e colisões de âncoras | Gratuito em todos os planos — é criado a partir do seu próprio markdown |
| llms.txt | "O que existe neste site?" | Um índice simples e acessível de todas as páginas publicadas, sem autenticação | Gratuito e legível sem uma conta do Docsbook |
Como as superfícies transferem informações entre si#
As transferências são o design, não uma coincidência.
- Uma skill nomeia uma necessidade; o servidor MCP responde a ela. As skills do Docsbook especificam quais evidências uma etapa exige ("leia os números antes de ler uma página") e permitem que o modelo escolha a ferramenta. Isso é intencional: uma skill que codifica nomes de ferramentas deixa de funcionar no momento em que uma ferramenta é renomeada, e a falha é silenciosa — o agente escolhe algo semelhante e improvisa um método diferente por trás de um relatório visualmente idêntico.
- O servidor MCP informa ao seu agente como executar a skill. Quatro ferramentas eram usadas para executar uma delas nas máquinas do Docsbook e devolver um id de execução (
run_docs_*); elas foram removidas em 12.09.2026.docsbook_expertresponde com o método, as etapas e a ferramenta de cada uma, e seu próprio agente — já com o repositório em mãos — as executa. - O grafo é o que as ferramentas de conteúdo leem.
search_docs,read_doceget_doc_outlinenão fazem grep nos arquivos; elas consultam umRichDocGraphcriado a partir do markdown do seu repositório e armazenado em cache no servidor. - llms.txt é o fallback para um agente que não tem nenhum dos dois. Sem token, sem checkout, sem cliente MCP — apenas um HTTP GET sobre o site publicado.
Por que esta é a maneira certa (evidências)#
| Regra | Por que funciona na máquina que o consome | Fonte |
|---|---|---|
| Publique o método como um arquivo que o agente carrega sob demanda, não como prosa em um prompt de sistema | O design de Agent Skills da Anthropic carrega uma habilidade em etapas — "até que uma Skill seja acionada, apenas seu nome e sua descrição ocupam o contexto" | Visão geral do Agent Skills |
| Mantenha a superfície de ferramentas tipada e nomeada, não um único endpoint de "fazer documentação" | As ferramentas MCP são "projetadas para serem controladas pelo modelo", descobertas e invocadas pelo modelo a partir de tools/list |
Especificação MCP 2026-07-28, Ferramentas |
| Não carregue tudo na janela de contexto de uma só vez | "O contexto, portanto, deve ser tratado como um recurso finito com retornos marginais decrescentes" | Engenharia eficaz de contexto |
| Forneça uma estrutura de catálogo grande que o modelo possa pesquisar, em vez de uma lista simples | A Anthropic mede que "a capacidade do Claude de escolher a ferramenta certa se deteriora quando você ultrapassa de 30 a 50 ferramentas disponíveis" | Ferramenta de pesquisa de ferramentas |
| Forneça um grafo para a recuperação, não um conjunto de páginas | A recuperação em contextos longos se deteriora no meio: o desempenho "se deteriora significativamente quando os modelos precisam acessar informações relevantes no meio de contextos longos" (Liu et al., TACL 2024) | Perdido no meio |
Duas delas merecem sua forma medida, em vez de um slogan. A recuperação em um grande registro de ferramentas foi avaliada independentemente: o RAG-MCP (preprint do arXiv 2505.03275, Gan e Sun, maio de 2025) relata uma precisão de seleção de ferramentas de "43,13% contra 13,62% na linha de base" quando as ferramentas são recuperadas em vez de todas serem listadas, reduzindo os tokens do prompt "em mais de 50%". Um preprint de 2026 que avalia registros "variando de 20 a 3.251 ferramentas" relata uma precisão de seleção de 93,1% contra 87,1% para a seleção adaptativa de uma lista curta em comparação com uma lista fixa de cinco ferramentas (arXiv 2605.24660). Ambos são preprints não revisados por pares; considere a direção como bem fundamentada e os números exatos como uma medição de uma equipe.
Limites e questões em aberto#
- As quatro superfícies não custam todas o mesmo. O catálogo de habilidades, o gráfico e o llms.txt são gratuitos em todos os planos. As chamadas de ferramentas MCP são contabilizadas por chamada em relação ao saldo do projeto, e o chat de IA voltado ao leitor, que consome o orçamento de modelos do Docsbook, começa no plano Pro. Os valores atuais estão na página de preços; esta documentação deliberadamente não informa nenhum, porque um preço copiado para uma página fica desatualizado silenciosamente.
- “Pronto para agentes” é uma afirmação sobre formato, não sobre classificação. O Docsbook pode mostrar que uma página pode ser buscada, que suas seções são independentes e que seus âncoras são resolvidos. Se algum assistente específico então a cita não é algo que este produto mede para você, e nenhuma fonte pública estabelece uma taxa geral. Consulte GEO para saber o que pode ser medido.
- A contagem de ferramentas muda. 140 é o número de nomes de ferramentas registrados nesta versão. A contagem autoritativa é o que
tools/listretorna para o seu token, e a seção MCP do seu painel de administração a lê em tempo real, em vez de usar uma cópia registrada por escrito. - A especificação MCP mudou enquanto a implementávamos. A revisão
2026-07-28tornou o MCP sem estado e removeu completamente o handshakeinitialize— “Não há handshake de negociação” (Versionamento e compatibilidade). O servidor do Docsbook é servido por meio de um transporte HTTP sem estado, mas ainda fala as revisões baseadas em inicialização compatíveis com seu SDK — a mais recente é2025-11-25— e mantém seu texto de orientação eminitialize, que é um posicionamento anterior a2026-07-28. Um cliente que fale apenas2026-07-28não se conectará. Consulte segurança do servidor MCP para ver o restante da lista de lacunas. - Nenhuma superfície aqui substitui uma documentação correta. Um agente que consiga navegar perfeitamente por um corpus ainda relata o que o corpus diz.
Relacionado#
- GEO — sendo citado por um assistente que nunca se conecta a nada
- llms.txt — a quarta superfície, documentada com a família SEO e GEO
- Referência de ferramentas MCP — todas as ferramentas com seus parâmetros e classe de cobrança
- Webhooks — a metade push: ser informado quando algo aconteceu, em vez de perguntar
- Chat com IA — o assistente com quem seus leitores conversam, que lê o mesmo grafo