{"id":50596281,"url":"https://github.com/mixcode/agent-friendly-guide","last_synced_at":"2026-06-05T14:31:01.850Z","repository":{"id":362260045,"uuid":"1258035042","full_name":"mixcode/agent-friendly-guide","owner":"mixcode","description":"A practical method (+ Claude Code skill) for making codebases agent-friendly.","archived":false,"fork":false,"pushed_at":"2026-06-03T09:40:18.000Z","size":39,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-03T11:18:56.849Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":null,"has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/mixcode.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-06-03T08:12:19.000Z","updated_at":"2026-06-03T09:40:22.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/mixcode/agent-friendly-guide","commit_stats":null,"previous_names":["mixcode/agent-friendly-guide"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/mixcode/agent-friendly-guide","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mixcode%2Fagent-friendly-guide","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mixcode%2Fagent-friendly-guide/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mixcode%2Fagent-friendly-guide/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mixcode%2Fagent-friendly-guide/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mixcode","download_url":"https://codeload.github.com/mixcode/agent-friendly-guide/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mixcode%2Fagent-friendly-guide/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33946818,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-05T02:00:06.157Z","response_time":120,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-06-05T14:31:01.254Z","updated_at":"2026-06-05T14:31:01.837Z","avatar_url":"https://github.com/mixcode.png","language":null,"funding_links":[],"categories":[],"sub_categories":[],"readme":"# agent-friendly-guide\n\n[![Agent-Ready](https://img.shields.io/badge/Agent--Ready-passed-success)](GUIDELINE.md)\n[![llms.txt](https://img.shields.io/badge/llms.txt-compliant-blue)](llms.txt)\n\n\u003e [!NOTE]\n\u003e **AI agents**: start with [llms.txt](llms.txt); the full method/manual is\n\u003e [GUIDELINE.md](GUIDELINE.md).\n\nA practical, reusable method for making codebases **agent-friendly** — repos that\nLLM coding agents can use, extend, and not break, without a human in the loop.\n\nIt is distilled from a real conversion (the `github.com/mixcode/binarystruct` Go\nlibrary) and validated by having a fresh agent build a non-trivial tool against\nthe result.\n\n## Contents\n\n- **[GUIDELINE.md](GUIDELINE.md)** — the method: seven pillars, an audit\n  checklist, anti-patterns, and language/ecosystem notes. Start here.\n- **[templates/](templates/)** — fill-in skeletons for `llms.txt`,\n  `llms-full.txt`, `llms-full-cli.txt` (the CLI/tool-facing manual), and `AGENTS.txt`.\n- **[evaluation/](evaluation/clean-agent-eval.md)** — the clean-agent evaluation\n  harness: a reusable prompt and how to run it.\n- **[case-study/binarystruct.md](case-study/binarystruct.md)** — the before/after\n  worked example.\n- **[skills/agent-ready/](skills/agent-ready/SKILL.md)** — an Agent Skill (this\n  repo is also a Claude Code plugin) that runs the audit, scaffolds the\n  artifacts, and offers the clean-agent evaluation.\n\n## The skill: `agent-ready`\n\nThis repo is a Claude Code **plugin** that ships one skill, `agent-ready`. Run it\ninside any repository to make it agent-friendly:\n\n- **`/agent-ready`** — full run: audit → scaffold (`llms.txt`/`llms-full.txt`/\n  `AGENTS.txt`) → offer a clean-agent evaluation.\n- **`/agent-ready --scaffold`** — audit + scaffold, stop before the evaluation.\n- **`/agent-ready --audit-only`** — just the prioritized gap report.\n\n(When installed as a plugin the command is namespaced: `/agent-friendly-guide:agent-ready`.)\n\nThe skill never fabricates API facts — it fills the templates only with what it\ncan verify from the repo and leaves clearly-marked `{TODO}` placeholders for the\nrest.\n\n### Install\n\n**As a plugin (recommended — bundles the templates + eval harness):**\n```\n/plugin marketplace add mixcode/agent-friendly-guide\n/plugin install agent-friendly-guide@agent-friendly-guide\n```\nLocal development install: `claude --plugin-dir /path/to/agent-friendly-guide`.\n\n**As a standalone skill** (audit works everywhere; scaffolding needs the plugin\nassets):\n```\ncp -r skills/agent-ready ~/.claude/skills/\n```\n\n## The short version\n\n1. Ship a machine-readable manual **in the repo** (`llms.txt` + `llms-full.txt`),\n   discoverable from the README and the in-language doc comment.\n2. Keep **one source of truth**; let docs and code never drift.\n3. **Name the traps** with the *why* and a rule — don't hide them.\n4. Give **copy-pasteable recipes** for the common paths.\n5. **Design the API** so misuse is hard (remove manual bookkeeping; fail loud\n   with precise errors). The deepest lever.\n6. Add an **`AGENTS.txt`** for agents that modify the code (invariants + checklist).\n7. **Measure** with a clean-agent evaluation on the *published* artifact; fix the\n   friction; repeat.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmixcode%2Fagent-friendly-guide","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmixcode%2Fagent-friendly-guide","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmixcode%2Fagent-friendly-guide/lists"}