---
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/