AI Agent Handbook CLI
AI Agent Handbook scores an agent project on five reliability pillars and points to chapters of a 31-chapter guide
- 73 ★ on the repository
- Last commit
- MIT
Minimal access
Why this level
- Reads project code statically and prints a report, and `handbook new` creates skeleton agent files in the chosen folder
Install
- Works in
Manual install
uvx agent-handbook doctor .Runs without installing. Alternatives: pipx run agent-handbook doctor . or pip install agent-handbook.
Access and checks
How we reviewMinimal accessThe tool runs nothing and makes no network calls.
- Reads project code statically and prints a report, and `handbook new` creates skeleton agent files in the chosen folder
This is third-party code. Review the repository files before installing.
What it does
The repository combines a 31-chapter guide in Chinese and a command line tool. `uvx agent-handbook doctor .` statically scans the project code and scores it from 0 to 10 on five pillars the guide calls essential for taking an agent to production: task boundaries, context management, state persistence, failure recovery and a permission system. The report says which pillar is missing and which chapter to read. The tool does more than check. `handbook doctor . --md` prints the report as a Markdown table for an issue or README, `handbook search` searches the text of all chapters and gives the chapter, line and snippet, `handbook new my-agent` generates an agent skeleton with the five pillars, and `handbook list`, `handbook stars` and `handbook open 25` list chapters and open one. It has no dependencies, uses only the standard library and works offline because the chapters ship with the package. Chapters cover topics such as ReAct and LangGraph, CrewAI, MCP, memory management, token cost, evaluation and writing `SKILL.md`. For CI there is a GitHub Action: `Xwh630/ai-agent-handbook@main` with a `min-score` threshold posts the report to a pull request comment and fails the step on a low score. The repository also includes a skill package `skills/agent-handbook/SKILL.md` that connects the guide to an agent, and 11 runnable examples.
Who it is for. Developers whose agent works in a demo but is unreliable in production, and readers who want a practical guide to agent systems in Chinese.
Good fit when
- The agent fails on real data and you want a quick checklist on five pillars with a score and chapter numbers
- In CI you want to reject changes that lower the agent's reliability score and get a report right in the pull request
- You need the part on context compaction or token cost in 31 chapters without reading everything
- You need a new agent skeleton that already has the five pillars
Not a fit when
- You need a code security report: the tool scores an agent's architectural pillars and does not hunt for vulnerabilities
- You need materials in Russian or English: the guide is Chinese, and the English translation covers 4 of 31 chapters
- The project is not about agents: scoring is built for agent projects
Example request
Run uvx agent-handbook doctor . in this project, show the score on five pillars and recommend chapters for the weakest oneLimitations
- The guide is in Chinese, the English translation covers 4 of 31 chapters at the time of the README, and there is no Russian.
- Scoring is static: the tool reads code and looks for signs of the pillars and does not test the agent's runtime behavior.
- The five pillars reflect the guide author's view and are not an industry standard.
- Running without install needs uv, otherwise use `pipx run` or `pip install agent-handbook`.
How to disable. If you installed with pip, run pip uninstall agent-handbook. Running through `uvx` installs nothing permanent. Remove the GitHub Action step from the workflow. The `skills/agent-handbook/` skill is removed by deleting its folder from the agent's skills directory.
FAQ
How do I check an agent project with doctor?
Run `uvx agent-handbook doctor .` at the project root. The tool scores 0 to 10 on five pillars and suggests which chapter to read. No install is needed, and `pipx run agent-handbook doctor .` works too.
What are the five pillars?
Task boundaries, context management, state persistence, failure recovery and a permission system. They are described in detail in chapter 25 on Harness Engineering.
How do I add the check to CI?
Add a `uses: Xwh630/ai-agent-handbook@main` step with `min-score: 6` to the workflow. The step fails below the threshold, and the report lands in a pull request comment and the Job Summary.
Can I search the guide's chapters?
Yes, `handbook search` searches the text of all 31 chapters and shows the chapter, line and snippet. The tool works offline and the chapters ship inside the package.
Is there a skill for an agent?
Yes, `skills/agent-handbook/SKILL.md` holds a package that connects the guide to an agent. Copy the folder into the agent's skills directory so it can consult the chapters.
Discussion
No questions or reviews yet.
Related
CLI toolsA multi-agent harness that verifies results by artifacts: stop hooks, an independent judge and an event log for Claude Code, Codex, Cursor and more
A catalog of nearly two hundred skills: code delivery, review, debugging, AI governance, product work and agent coordination.
The /better-harness command reviews how an AI agent's work is set up in a project: goals, checks, delivery and memory, and returns a prioritized fix report
An open coding agent for the terminal, browser and desktop that works with models from OpenAI and Claude to Ollama
A LangWatch command-line tool that creates the scaffold of a new AI agent project and hands it to a coding assistant
Awesome Agent Skills (libukai)
awesome-agent-skills-libukai
A guide to Agent Skills from start to tools in Chinese and English with selected skills. No license
README in short
The README presents the project as a Chinese-language guide of 31 chapters plus a tool that scores an agent project. A 30-second section shows running `doctor`, a table of commands and a CI action. A table of situations then maps problems such as exploding token costs to chapters, with three reading paths and a full table of contents. A weekly radar, running examples, contribution rules and notes on a student-run project close the page.