Inside The Machine
Tools
Scaffolds / Recipes

AGENTS.md

A README written for AI agents.

Clear instructions help small models act smarter.

—PENDING
Gap ScorePending test on Mac Studio
Where it sits
Want it installed?Hand this page to your agent.
.md .json
Let your agent do itNot run · docs checked
curl -fsSL https://insidethemachine.ai/install/agents-md.sh | bash
macOS and Linux
Plan, check, undo

Add -s -- plan to print every step and run nothing, verify to only check, rollback --yes to undo. Not run: commands checked against the official docs only. Commands checked against the official docs on 2026-10-15. Not run end to end.

Read the script.md.jsonAll installs

Homepage Repo 24,944 MIT

AGENT VIEW · text/markdown · or send Accept: text/markdown
---
schema: "https://insidethemachine.ai/schema/listing.schema.json"
slug: "agents-md"
name: "AGENTS.md"
category: "Scaffolds / Recipes"
stack_layer: "harness"
homepage: "https://agents.md/"
repo: "https://github.com/agentsmd/agents.md"
docs: "https://agents.md/"
license: "MIT"
platforms: ["macos-apple-silicon", "linux", "windows"]
mac_studio_fit: "Primary"
stars: 24944
stars_as_of: "2026-10-15"
last_push: "2026-09-10"
gap_score: null
gap_score_status: "pending test on Mac Studio"
benchmarks_status: "pending test on Mac Studio"
verified_on: "2026-10-15"
sponsored: false
---

# AGENTS.md

> A simple open format, basically a README for coding agents, that tells them how to work in your repo.

**What:** A README written for AI agents. **Why:** Clear instructions help small models act smarter.

**Stack layer:** harness (model → runtime → harness → memory → tools)

A convention: put an AGENTS.md file at the repo root with dev environment tips, test instructions and PR rules so coding agents behave predictably.

**Gap role:** Context engineering: clear instructions let smaller local models punch above their weight in a codebase.

## Gap Score

null (pending test on Mac Studio)

## Prerequisites

- A git repository

## Install

### macOS (Apple Silicon)

1. section headings follow the official example:

```bash
cat > AGENTS.md <<'EOF'
# AGENTS.md

## Dev environment tips
- <how to install deps / run the app>

## Testing instructions
- <exact test command>

## PR instructions
- Always run lint and tests before committing.
EOF
```

## Configure

1. Run:

```bash
# point your agent at the repo; agents that support AGENTS.md read it automatically
```

## Verify

1. Expect: file exists at the repo root

```bash
test -f AGENTS.md && head -5 AGENTS.md
```

## Rollback

1. Run:

```bash
git rm AGENTS.md   # or: rm AGENTS.md
```

## One-command install

Status: docs-checked (Not run: commands checked against the official docs only). The wrapper scripts are generated from the site data. Every .sh passed bash -n and shellcheck and ran in plan mode on Linux (Debian 13). Every .ps1 passed the PowerShell parser and chat.ps1 ran in plan, verify and rollback mode under PowerShell 7 on Linux with Windows calls mocked. Not run on macOS or real Windows.

```bash
curl -fsSL https://insidethemachine.ai/install/agents-md.sh | bash            # install, then check
curl -fsSL https://insidethemachine.ai/install/agents-md.sh | bash -s -- plan    # print only
curl -fsSL https://insidethemachine.ai/install/agents-md.sh | bash -s -- rollback --yes
```

Details and Windows: https://insidethemachine.ai/install/agents-md.md

## Caveats

- Support varies by agent; check your agent's docs.

## Benchmarks

Status: pending test on Mac Studio. Rig: Mac Studio, Apple Silicon, 128GB unified memory. No results published yet.

## Works with

- aider (https://insidethemachine.ai/setups/aider.md)
- mcp-servers (https://insidethemachine.ai/setups/mcp-servers.md)

## Sources

- https://github.com/agentsmd/agents.md
- https://agents.md/