Guides · Python
How to write an AGENTS.md for a Python project
Measured across 214 of the most-starred Python repositories on GitHub. The median scores 60 out of 100.
What Python repos get wrong
Python's defining problem is the runtime. 84% of Python repositories pin no version at all, which means an agent picks whatever python resolves to and gets failures that have nothing to do with the change it made. A .python-version file costs one line and removes an entire class of confusion. The second problem is the same one everywhere: two thirds ship no agent instructions, and most of the rest never name a command.
Most common failures
share of 214 Python repositories scoring zero on each
Lower is better here. These are failures, not scores.
A working example
Commands first, conventions second, none of the persuasion a README carries. The test is whether a capable stranger could make a small change and verify it using only this file.
Save it at the root of the repository
as AGENTS.md. Tool-specific files like CLAUDE.md or .cursorrules still work, but
AGENTS.md is the one every tool reads.
# AGENTS.md ## Setup uv sync ## Commands uv run pytest # full suite, must pass before any commit uv run ruff check . # lint uv run mypy src # type check ## Conventions - Tests live in tests/, named test_*.py. - Dependencies are managed with uv. Do not pip install into the environment. ## Gotchas - Requires Python 3.12. See .python-version.
The two lines that matter most
If you write nothing else, write these. An agent that cannot install the project cannot start, and one that cannot run the tests cannot tell whether it broke something.
# installuv sync# verifypytest
Have it drafted instead
Point the tool at a repository and it writes the file from what is already there, rather than from a template.
For private code, the same rubric runs on your machine and sends nothing anywhere:
$ npx agentreadme --write-agents
Other ecosystems