Just like the transformer paper Attention Is All You Need proved, working with AI agents has taught me: Files is all you need. Simplicity is your greatest ally. The ecosystem offers many sophisticated tools—MCP (Model Context Protocol) servers for structured tool access, Skills frameworks for capability registration, Memory systems for persistent context. While powerful, these add layers of abstraction and ceremony that can obscure what the agent actually needs to do.

After experimenting with these approaches, I’ve found that a simpler pattern often works better: plain files, executable scripts, and clear references. This keeps token usage low, workflows predictable, and debugging straightforward. You get the benefits of structure without the overhead of complex registration systems or protocol layers.

TL;DR

  • AGENTS.md - A single entry point file that documents only the important points and references detailed docs on demand
  • Scripts - Executable scripts for deterministic workflows which also serve as documentation
  • Quality Gate - A comprehensive verification script the agent runs to ensure changes haven’t broken anything

AGENTS.md - The index

Every project should have an AGENTS.md file at its root. This serves as the single entry point from which the agent understands the codebase. But keep it lean: only document the important points that truly matter for getting oriented. Think of it as a table of contents rather than an encyclopedia.

For detailed information, include references to other documentation files that the model can load on demand. This approach gives you the benefits of “skills”—modular, discoverable knowledge—without the ceremony of complex registration systems.

Here’s an example of what a good AGENTS.md looks like:

# Project: TaskTracker

A simple CLI tool for managing daily tasks.

## Quick Navigation

- Source code: `src/` - Main application logic
- Tests: `tests/` - Unit and integration tests
- Docs: `docs/` - Detailed documentation

## Key Commands

Run `./scripts/dev.sh` to start the development environment.
Run `./scripts/quality-gate.sh` before committing changes.

## Architecture

See `docs/architecture.md` for system design details.
See `docs/api.md` for internal API documentation.

Notice how it references other files rather than including everything. The agent can read docs/architecture.md only when it needs to understand the system design.

Scripts - Deterministic workflow

The most powerful pattern I’ve found is putting as much as possible into executable scripts. These scripts serve double duty: humans can run them directly, and agents can invoke them to perform tasks. This keeps token usage low (no need to describe complex procedures in natural language) and makes workflows predictable, scripts are deterministic, after all.

Keep these scripts deliberately simple. Skip elaborate error handling; if something fails, the output will guide you. Use environment variables for configuration rather than complex argument parsing. Most importantly, embed documentation directly in the scripts themselves. The agent can use the scripts directly for the common cases, but when it needs to understand the internals, it can read the script as living documentation.

Here’s a typical development script:

#!/usr/bin/env nix-shell
#!nix-shell -i bash -p nodejs
# dev.sh - Start development environment
#
# Usage: ./scripts/dev.sh
# Environment: PORT (default: 3000)
#
# This script:
# 1. Installs dependencies if needed
# 2. Starts the dev server on the configured port
# 3. Watches for file changes
#
# The nix shebang ensures nodejs and npm are available,
# making this script work on any system with nix installed.

set -e

cd "$(dirname "$0")/.."

# Install deps if node_modules missing
[ -d node_modules ] || npm install

# Start dev server with hot reload
PORT=${PORT:-3000}
npm run dev -- --port "$PORT"

The comments at the top serve as documentation. An agent scanning this gets the gist immediately, but can read the actual implementation if it needs to know exactly how dependencies are checked or how the port is configured.

Quality Gate - Guardrails for the Model

Finally, provide a quality gate script that the agent can run to verify everything works. This should be comprehensive—running tests, linters, formatters, and any other verification your project needs. It gives the agent confidence that its changes haven’t broken anything, and it gives you confidence in the agent’s work.

A complete quality gate script might look like this:

#!/usr/bin/env nix-shell
#!nix-shell -i bash -p nodejs nodePackages.prettier nodePackages.typescript
# quality-gate.sh - Run all quality checks
#
# Usage: ./scripts/quality-gate.sh
# Environment: SKIP_TESTS (set to "1" to skip slow tests)
#
# This script runs the full verification pipeline:
# 1. Format check (prettier)
# 2. Linting (eslint)
# 3. Type checking (tsc)
# 4. Unit tests
# 5. Integration tests (unless SKIP_TESTS=1)
#
# The nix shebang ensures all required tools (nodejs, prettier, tsc)
# are automatically available, regardless of what's installed on the host.

set -e

cd "$(dirname "$0")/.."

prettier --check .
npm run lint
tsc --noEmit
npm run test:unit

if [ "$SKIP_TESTS" != "1" ]; then
    npm run test:integration
fi

The agent can run it after making changes and get a clear pass/fail result; if something fails, the error output shows exactly what went wrong.

The beauty of this approach is that it respects both human and machine intelligence: clear enough for people to maintain, structured enough for agents to navigate effectively. It also works with any agent harness that can work with files and execute commands.