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 a ele precisa adivinhar qual página importa, extrair fatos do texto e não tem como agir com base no que leu. O Docsbook publica a mesma documentação por meio de quatro superfícies que uma máquina consome diretamente — para que um agente possa encontrar o método, ler o corpus, navegar por sua estrutura e alterá-lo.
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 competências 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
310 ferramentas tipadas pelo Model Context Protocol: ler páginas, fazer commit delas, ler análises, alterar configurações e iniciar 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 expostas 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 obtém | O que custa |
|---|---|---|---|
| Catálogo SKILL.md | "Como este trabalho é feito corretamente?" | Um fluxo de trabalho com salvaguardas, etapas ordenadas e critérios de aceitação, obtido do GitHub | Nada — o catálogo é público e find_skill nunca é cobrado |
| Servidor MCP | "O que posso chamar e em qual projeto?" | 310 ferramentas, um bloco instructions no momento da conexão, erros estruturados que indicam a próxima ação |
Cobrado por chamada com base no 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 o controle entre si#
As transferências são o design, não uma coincidência.
- Uma habilidade nomeia uma necessidade, o servidor MCP responde a ela. As habilidades do Docsbook indicam 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 é deliberado: uma habilidade que codifica nomes de ferramentas diretamente 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 aparentemente idêntico.
- O servidor MCP pode executar a habilidade por você.
run_docs_analyze,run_docs_create,run_docs_manageerun_docs_automateexecutam uma das quatro habilidades do orquestrador nas máquinas do Docsbook, em seu workspace, e retornam um ID de execução em vez de um resultado. - 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 GET HTTP sobre o site publicado.
Por que esta é a maneira correta (evidências)#
| Regra | Por que funciona na máquina que a consome | Fonte |
|---|---|---|
| Publique o método como um arquivo que o agente carrega sob demanda, não como prosa em um prompt do sistema | O design de Agent Skills da Anthropic carrega uma habilidade em etapas — "até que uma Skill seja acionada, apenas seu nome e descrição ocupam o contexto" | Visão geral de 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 a um modelo de catálogo grande uma estrutura que ele possa pesquisar, em vez de uma lista plana | A Anthropic mede que "a capacidade do Claude de escolher a ferramenta certa se deteriora quando você ultrapassa 30–50 ferramentas disponíveis" | Ferramenta de pesquisa de ferramentas |
| Forneça à recuperação um grafo, 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 mensurada, em vez de um slogan. A recuperação em um grande registro de ferramentas foi avaliada independentemente: 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% de referência" 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 pré-seleção adaptativa em comparação com uma lista fixa das cinco ferramentas mais prováveis (arXiv 2605.24660). Ambos são preprints não revisados por pares; considere a tendência bem respaldada 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 grafo e o llms.txt são gratuitos em todos os planos. As chamadas de ferramentas MCP são contabilizadas por chamada e descontadas do saldo do projeto, e os dois recursos que consomem o orçamento de modelo do Docsbook — execuções do agente (
run_docs_*,agent_*) e o chat de IA voltado ao leitor — começam no plano Pro. Os valores atuais estão na página de preços; esta documentação deliberadamente não cita nenhum, porque um preço copiado em 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 obtida, 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 é mensurável.
- A contagem de ferramentas muda. 310 é o número de nomes de ferramentas registrados por esta compilação. A contagem oficial é 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 avançá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 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 contém seu texto de orientação eminitialize, que é uma colocação anterior a2026-07-28. Um cliente que fale somente2026-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 de SEO e GEO
- Referência de ferramentas MCP — todas as ferramentas com seus parâmetros e classe de cobrança
- Webhooks — a metade de envio: ser informado quando algo acontece, em vez de perguntar
- Chat de IA — o assistente com quem seus leitores conversam, que lê o mesmo grafo