Agent-Friendly Guide
mixcode/agent-friendly-guide
Prepare seus repositórios para agentes IA com auditoria e documentação automática
Ver no GitHubMétodo prático e skill do Claude Code para tornar repositórios agent-friendly. Audita codebases, gera documentação estruturada (llms.txt/AGENTS.txt) e executa avaliações limpas de agentes IA. Baseado em conversões reais de bibliotecas de produção.
Instalação
npx convez-ai mixcode/agent-friendly-guide1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.
Métricas
Casos de uso
- Preparar repositórios para serem compreendidos e estendidos por agentes IA
- Gerar documentação estruturada (llms.txt/AGENTS.txt) automaticamente
- Auditar monorepos e mapear readiness de pacotes para agentes
- Validar se uma codebase permite operações de agentes sem quebras
Veredito

Ferramenta madura e bem documentada, nascida de casos reais de produção. Preenche gap importante na preparação de repos para agentes, mas exige compreensão técnica para aproveitar melhor. Recomendado para equipes construindo com agents a longo prazo.
README
A tradução para o português deste README ainda está na fila.
agent-friendly-guide
[!NOTE] AI agents: start with llms.txt; the full method/manual is GUIDELINE.md.
A practical, reusable method for making codebases agent-friendly — repos that LLM coding agents can use, extend, and not break, without a human in the loop.
It is distilled from real-world conversions of production libraries and CLI tools, validated by having fresh agents build non-trivial things against the results, and tested across ten language ecosystems.
Contents
- GUIDELINE.md — the method: a contract-legibility diagnostic, the work in leverage order, an audit checklist, anti-patterns, and language/ecosystem notes. Start here.
- templates/ — fill-in skeletons for
llms.txt,llms-full.txt,llms-full-cli.txt(the CLI/tool-facing manual),llms-monorepo.txt(a monorepo root's package map), andAGENTS.txt. - evaluation/ — the clean-agent evaluation harness: a reusable prompt and how to run it.
- languages/ — per-ecosystem specifics (signals, doc surface, distribution model, traps) for Go, Python, JavaScript, C, Rust, JVM, Shell, Swift, PHP, Ruby.
- skills/agent-ready/ — an Agent Skill (this repo is also a Claude Code plugin) that runs the audit, scaffolds the artifacts, and offers the clean-agent evaluation.
The skill: agent-ready
This repo is a Claude Code plugin that ships one skill, agent-ready. Run it
inside any repository to make it agent-friendly:
/agent-ready(or--full) — full run: audit → scaffold (llms.txt/llms-full.txt/AGENTS.txt) → offer a clean-agent evaluation.--fullis the default when no switch is given./agent-ready --scaffold— audit + scaffold, stop before the evaluation./agent-ready --audit-only— just the prioritized gap report./agent-ready --monorepo— monorepo survey: point it at a workspace root and it enumerates every member package, triages each, and writes a root monorepo map (llms.txt) showing where each package's manual lives and how agent-ready it is. Deep per-package work still runs one package at a time (/agent-ready packages/foo).
(When installed as a plugin the command is namespaced: /agent-friendly-guide:agent-ready.)
The skill never fabricates API facts — it fills the templates only with what it
can verify from the repo and leaves clearly-marked {TODO} placeholders for the
rest.
Install
As a plugin (recommended — bundles the templates + eval harness):
/plugin marketplace add mixcode/agent-friendly-guide
/plugin install agent-friendly-guide@agent-friendly-guide
Local development install: claude --plugin-dir /path/to/agent-friendly-guide.
Standalone (not recommended): copying just the skill directory
(cp -r skills/agent-ready ~/.claude/skills/) makes the /agent-ready command
available, but the skill reads its checklist, templates, language guides, and
evaluation harness from the plugin via ${CLAUDE_PLUGIN_ROOT} — a bare copy
won't find them. Install as the plugin above instead.
Other agent harnesses
The method (GUIDELINE.md) is vendor-neutral — it reasons about "an agent," not a
specific product, and has been validated on more than one model family (Claude and
Gemini both apply it correctly). The skill is packaged as a Claude Code plugin, but
it runs on any harness that can (1) load a skill and (2) let that skill read the plugin's
support files (GUIDELINE.md, templates/, languages/, evaluation/). Harnesses that
import only the skill component need those files placed alongside the skill.
From v0.3.10 the skill self-recovers: if a harness imported only the skill component and you have web access, it fetches the missing support files directly from the published release, version-pinned to the skill (so the guide always matches). The clone+symlink below is then only needed for offline / no-web harnesses.
Worked example — Antigravity (agy), running on a Gemini model:
# 1. import the skill from the official repo
agy plugin install https://github.com/mixcode/agent-friendly-guide
# 2. agy keeps only the skill component, so make the support files reachable:
git clone https://github.com/mixcode/agent-friendly-guide ~/agent-friendly-guide
for f in GUIDELINE.md templates languages evaluation; do
ln -sfn ~/agent-friendly-guide/$f ~/.gemini/config/plugins/agent-friendly-guide/$f
done
# 3. run it
agy -p "/agent-ready --scaffold" --model "Gemini 3.1 Pro (High)" --dangerously-skip-permissions
(Paths are agy-specific; adapt the plugin dir to your harness. git pull the clone to
track new releases.)
The short version
- The law. A manual's value = what the task needs − what's already legible to the agent (from the code, the API names, and its training prior). Spend effort on the residue — the project-specific knowledge that's in none of those — and not where the agent already sees the contract.
- Diagnose before you invest. Is the contract legible from what the agent actually reads? Legible (an ordinary source-shipped library) → invest in the source and kill drift, don't write a manual. Not legible (a CLI, service, or indirection-heavy code) → write a manual aimed at the residue, shipped so it travels per the ecosystem's distribution model.
- Keep the read surface true — and on the path the agent actually reads. Drift is worse than absence (a wrong doc fails silently); prioritize the unverifiable conventions an agent can't re-derive from adjacent code. Verify which surface a clean agent opens and inline the decisive traps + recipe there — don't assume it reads a separate manual.
- Design the API so misuse is hard — remove manual bookkeeping; fail loud with precise errors. The deepest lever.
- Name the traps (with the why + a rule) and give copy-pasteable recipes for the common paths.
- Always: a selection surface (a one-line "use when / not for") and an
AGENTS.txtfor agents that modify the code (invariants + checklist). - Measure with a clean-agent evaluation on the published artifact — pass-rate first, tokens second; fix the friction; repeat.