agentleFS
Sign inStart free
MicrosoftKnown publishermicrosoft/amplifier-smart-tool-reality-check/AGENTS.md

amplifier-smart-tool-reality-check

AGENTS.md2 starsChanged 9 days agoMITView on GitHub

This is a Smart Tool that must conform to Microsoft's Amplifier Smart Tool Spec.

  • Where files are headingNew AGENTS.md files have more rules about keeping secrets out of the code, and fewer about code style.

    Of the AGENTS.md files we read, the 31,774 first seen in the last six months, against the older ones: the kind of rule that gained most share, and the kind that lost most. About files like this in general, not this one, and an estimate, since a kind is a pattern in the words.

  • In this repository6 other files it gives its agents.

The file

Show its rules and text

We split this AGENTS.md into the rules it gives an agent

20 rules. About 0 are common, 11 are distinctive, and 9 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈11

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 9

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    If not already, set up the environment by following docs/DEVELOPMENT.md.

    line 5
  2. Very specific:

    After making changes, prek run --all-files and uv run pytest must pass before the work is done.

    line 6
  3. Distinctive:

    Never modify this file unless explictly told.

    line 14
  4. Distinctive:

    When adding to existing documents, add only what's needed.

    line 19
  5. Distinctive:

    Do not restructure or rewrite existing content unless asked.

    line 20
  6. Distinctive:

    Always prefer code blocks and other formatting over tables.

    line 21
  7. Distinctive:

    Never write em dashes

    line 23
  8. Distinctive:

    Don't generate characters that a user could not type on a standard keyboard like fancy arrows (layout trees are fine)

    line 31
  9. Distinctive:

    Follow the Google Python Style Guide.

    line 34
  10. Very specific:

    NEVER add imports to __init__.py files.

    line 35
  11. Very specific:

    Always prefer pathlib for dealing with files.

    line 36
  12. Very specific:

    When using pathlib, always Use .parents[i] syntax to go up directories instead of using .parent multiple times.

    line 37
  13. Distinctive:

    When writing tests, use pytest and pytest-asyncio.

    line 38
  14. Distinctive:

    Prefer using loguru for logging instead of the built-in logging module.

    line 39
  15. Very specific:

    NEVER use # type: ignore. It is better to leave the issue and have the user work with you to fix it.

    line 40
  16. Distinctive:

    Don't put types in quotes unless it is absolutely necessary to avoid circular imports and forward references.

    line 41
  17. Very specific:

    When adding new dependencies, you must use uv add <package>.

    line 42
  18. Very specific:

    Run prek run --all-files when you are done with code changes and fix everything it reports.

    line 44
  19. Very specific:

    NEVER add a bare *, keyword-only marker to a function signature.

    line 45
  20. Distinctive:

    Make sure to have in your context or read these files before planning and before making any final changes.

    line 49

≈ “Common” is an estimate: at least 1 in 5 of the 40,246 AGENTS.md files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
AGENTS.md

This is a Smart Tool that must conform to Microsoft's Amplifier Smart Tool Spec.

Orientation

  • If not already, set up the environment by following docs/DEVELOPMENT.md. It also has every command for linting, formatting, type checking, testing, and running the conformance kit.
  • After making changes, prek run --all-files and uv run pytest must pass before the work is done.
  • docs/00-vision.md is the source of truth for what this tool is and is not, and docs/01-library.md for what it exposes. Then README.md and docs/DEVELOPMENT.md, then the rest of docs/. Both are written for people and stay concise. When work changes any of them, propose the doc updates at the end and call out contradictions.
  • The library is the tool. Every capability lives in the library and is reachable from lib.py. The CLI and any other surface are thin wrappers: argument parsing and I/O conventions, then a call into the library. Capability that exists only in a wrapper is a defect.
  • Each domain capability lives in capabilities/<name>/, with its prompts and templates beside its code. lib.py imports it and is the only place that does. core/ holds only what every smart tool has: the manifest and the skill.
  • Deterministic capabilities run with no model provider configured. Model-backed capabilities go through the Intelligence interface, never an SDK directly, and their help text says they are model-backed. They take agent_provider, model, and reasoning_effort as parameters and resolve the implementation and model with select_intelligence, so the model defaults to the agent provider's entry in DEFAULT_INTELLIGENCE_MODELS from schemas.py; never hardcode a model name.
  • A capability is its code, a row in CAPABILITIES, and a SKILL.md beside that code carrying its arguments, a worked invocation, and its expected result. <command> --help renders that skill, <command> -h stays the terse generated summary, and the tool's own skill stays a router pointing at both.
  • Failures name what went wrong and how to fix it. These should be surfaced when the library or other surface is used. Listing all possible failures in skills or docs is not appropriate. The caller is usually an agent.
  • The Repository URL under [project.urls] in pyproject.toml is the tool's canonical source: --help carries it, so an agent that can run the tool but not read its files still finds the docs, and every install instruction in README.md, SMART_TOOL.md, and the skill is built on it. If it is still the <owner> placeholder, replace it everywhere it appears once the remote exists.
  • Never modify this file unless explictly told.

Writing Style

  • Be concise. The user will not read walls of text.
  • When adding to existing documents, add only what's needed.
  • Do not restructure or rewrite existing content unless asked.
  • Always prefer code blocks and other formatting over tables.
  • Match the tone and density of what's already in the file.
  • Never write em dashes

Python Development Instructions

  • This is a production-grade Python project using uv as the package and project manager. You must always follow best Python practices.
    • To figure out how uv works, start by using uv --help.
  • Make sure any comments in code are necessary. A necessary comment captures intent that cannot be encoded in names, types, or structure. Comments should be reserved for the "why", only used to record rationale, trade-offs, links to specs/papers, or non-obvious domain insights. They should add signal that code cannot.
  • The current code in the package should be treated as an example of high quality code. Make sure to follow its style and tackle issues in similar ways where appropriate.
  • Don't generate characters that a user could not type on a standard keyboard like fancy arrows (layout trees are fine)
  • Anything is possible. Do not blame external factors after something doesn't work on the first try. Instead, investigate and test assumptions through debugging through first principles.
  • ty by Astral is used for type checking. Always add appropriate type hints such that the code would pass ty's type check.
  • Follow the Google Python Style Guide.
  • NEVER add imports to init.py files. Leave them empty unless absolutely necessary.
  • Always prefer pathlib for dealing with files. Use Path.open instead of open.
  • When using pathlib, always Use .parents[i] syntax to go up directories instead of using .parent multiple times.
  • When writing tests, use pytest and pytest-asyncio.
  • Prefer using loguru for logging instead of the built-in logging module. Do not add logging unless requested.
  • NEVER use # type: ignore. It is better to leave the issue and have the user work with you to fix it.
  • Don't put types in quotes unless it is absolutely necessary to avoid circular imports and forward references.
  • When adding new dependencies, you must use uv add <package>. AFTER that, update the pyproject.toml to follow the convention for versions like the other dependencies.
  • To learn about how packages work, you should read from the relevant source code. This is especially important when determining which types to use.
  • Run prek run --all-files when you are done with code changes and fix everything it reports; it runs the lock, lint, format, and type checks.
  • NEVER add a bare *, keyword-only marker to a function signature. Write plain positional-or-keyword parameters and call them by keyword.

Key Files

Make sure to have in your context or read these files before planning and before making any final changes.

@docs/DEVELOPMENT.md @docs/00-vision.md

References

reference/ holds the repositories to read rather than recall while developing this tool. They are shallow clones of the main branch only, always gitignored, and never discovered by tests, formatters, or type checks. uv run setup-for-dev.py clones any that are missing, so a fresh clone of this repository recovers them. The repositories are (add to the list as more are needed, the one exception to modifying this file):

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

Check your setup, free