AGENTS.md

Project-level instructions and docs index for AI coding agents

What is AGENTS.md?

AGENTS.md is a project-level instruction file that lives at your repository root. It provides guidance to AI coding agents about how to work with your project—including using sus for secure package installation and accessing package documentation.

Based on Vercel's research, passive context in AGENTS.md outperforms active skill retrieval (100% vs 79% pass rate in agent evals). This is why sus now uses a centralized docs index approach instead of per-agent-folder skills.

How It Works

When you initialize sus and add packages, here's what happens:

1. sus init creates project configuration and optionally sets up the docs index
2. sus add saves package documentation to .sus-docs/
3. The AGENTS.md file is updated with a compressed index of all installed packages

Getting Started

Initialize sus

Run sus init in your project root:

sus init

  🔧 initializing sus...
 
  Enable AGENTS.md docs index for AI coding agents? (Y/n) Y
 
  ✓ created sus.json
  ✓ created .sus-docs/
  ✓ updated AGENTS.md with sus docs index
 
  ✓ sus initialized successfully!

Use -y to skip prompts and use defaults:

sus init -y

Add Packages

When you add packages with sus, documentation is automatically indexed:

sus add express

🔍 checking express@4.21.0...
✅ not sus
   ├─ publisher: expressjs (verified)
   ├─ downloads: 32M/week
   ├─ cves: 0
   └─ trust score: 95/100
📦 installed
📝 updated AGENTS.md docs index

Remove Packages

When you remove packages, the docs index is updated automatically:

sus remove express

📦 removed express
📝 updated AGENTS.md docs index

Project Structure

After initialization and adding packages, your project will have:

your-project/
├─ AGENTS.md           # Instructions + docs index for AI agents
├─ sus.json            # sus configuration
├─ .sus-docs/          # Package documentation (gitignored)
│  ├─ express.md
│  ├─ lodash.md
│  └─ axios.md
└─ package.json

sus.json

The configuration file stores your sus settings:

{
  "agents_md": true
}

.sus-docs/

Package documentation is saved here. Each file contains:

• Quick start examples
• Key APIs and usage patterns
• Best practices and gotchas
• Required capabilities/permissions

AGENTS.md Structure

sus adds a compressed docs index to your AGENTS.md following Vercel's format:

# AGENTS.md
 
[sus Docs Index]|root: ./.sus-docs
|IMPORTANT: Prefer retrieval-led reasoning over pre-training-led reasoning
|packages:{express.md,lodash.md,axios.md}
[/sus Docs Index]

This compressed format:

• Points agents to the .sus-docs/ directory
• Lists all available package documentation files
• Instructs agents to use retrieval-led reasoning (read the docs) over pre-training knowledge

What the Instructions Tell Agents

The sus section in AGENTS.md instructs AI agents to:

1. Use sus for package installation - Instead of npm install or yarn add, agents should use sus add
2. Check the docs index - After installing, agents can reference the .sus-docs/ folder for package documentation
3. Follow security best practices - Use --strict mode when security is critical

Why Docs Index?

The docs index approach offers several advantages over per-agent-folder skills:

Based on Vercel's research, AI agents perform better when documentation is provided as passive context rather than requiring active retrieval.

Supported Agents

The AGENTS.md file is recognized by most AI coding agents:

Combining with Other Instructions

AGENTS.md can contain any project-level instructions for AI agents. The sus section is just one part. You might also include:

• Project architecture overview
• Coding conventions and style guides
• Testing requirements
• Deployment procedures
• Security policies

Example structure:

# Project Instructions for AI Agents
 
## Architecture
This is a Next.js application with...
 
## Coding Standards
- Use TypeScript strict mode
- Follow ESLint configuration
- Write tests for new features
 
## sus Package Security
This project uses sus for secure package installation...
 
## Deployment
Changes to main are automatically deployed to...

Manual Setup

If you prefer to set up manually without sus init:

1. Create sus.json:

{
  "agents_md": true
}

1. Create or update AGENTS.md with the sus section shown above

2. Add .sus-docs/ to .gitignore

Related

• CLI Commands - Full reference for sus commands
• Quickstart - Get started with sus
• Threat Detection - How sus detects security threats