Agents Md

Maintaining AGENTS.md

AGENTS.md is the canonical agent-facing documentation. Keep it minimal—agents are capable and don't need hand-holding. Target under 60 lines; never exceed 100. Instruction-following quality degrades as document length increases.

File Setup

1. Create AGENTS.md at project root
2. Create symlink: ln -s AGENTS.md CLAUDE.md

Before Writing

Analyze the project to understand what belongs in the file:

1. Package manager — Check for lock files (pnpm-lock.yaml, yarn.lock, package-lock.json, uv.lock, poetry.lock)
2. Linter/formatter configs — Look for .eslintrc, biome.json, ruff.toml, .prettierrc, etc. (don't duplicate these in AGENTS.md)
3. CI/build commands — Check Makefile, package.json scripts, CI configs for canonical commands
4. Monorepo indicators — Check for pnpm-workspace.yaml, nx.json, Cargo workspace, or subdirectory package.json files
5. Existing conventions — Check for existing CONTRIBUTING.md, docs/, or README patterns

Writing Rules

• Headers + bullets — No paragraphs
• Code blocks — For commands and templates
• Reference, don't embed — Point to existing docs: "See CONTRIBUTING.md for setup" or "Follow patterns in src/api/routes/"
• No filler — No intros, conclusions, or pleasantries
• Trust capabilities — Omit obvious context
• Prefer file-scoped commands — Per-file test/lint/typecheck commands over project-wide builds
• Don't duplicate linters — Code style lives in linter configs, not AGENTS.md

Required Sections

Package Manager

Which tool and key commands only:

## Package Manager
Use **pnpm**: `pnpm install`, `pnpm dev`, `pnpm test`

File-Scoped Commands

Per-file commands are faster and cheaper than full project builds. Always include when available:

## File-Scoped Commands
| Task | Command |
|------|---------|
| Typecheck | `pnpm tsc --noEmit path/to/file.ts` |
| Lint | `pnpm eslint path/to/file.ts` |
| Test | `pnpm jest path/to/file.test.ts` |

Commit Attribution

Always include this section. Agents should use their own identity:

## Commit Attribution
AI commits MUST include:

Co-Authored-By: (the agent model's name and attribution byline)

Example: `Co-Authored-By: Claude Sonnet 4 <noreply@example.com>`

Key Conventions

Project-specific patterns agents must follow. Keep brief.

Optional Sections

Add only if truly needed:

• API route patterns (show template, not explanation)
• CLI commands (table format)
• File naming conventions
• Project structure hints (point to critical files, flag legacy code to avoid)
• Monorepo overrides (subdirectory AGENTS.md files override root)

Anti-Patterns

Omit these:

• "Welcome to..." or "This document explains..."
• "You should..." or "Remember to..."
• Linter/formatter rules already in config files (.eslintrc, biome.json, ruff.toml)
• Listing installed skills or plugins (agents discover these automatically)
• Full project-wide build commands when file-scoped alternatives exist
• Obvious instructions ("run tests", "write clean code")
• Explanations of why (just say what)
• Long prose paragraphs

Example Structure

# Agent Instructions

## Package Manager
Use **pnpm**: `pnpm install`, `pnpm dev`

## Commit Attribution
AI commits MUST include:

Co-Authored-By: (the agent model's name and attribution byline)

## File-Scoped Commands
| Task | Command |
|------|---------|
| Typecheck | `pnpm tsc --noEmit path/to/file.ts` |
| Lint | `pnpm eslint path/to/file.ts` |
| Test | `pnpm jest path/to/file.test.ts` |

## API Routes
[Template code block]

## CLI
| Command | Description |
|---------|-------------|
| `pnpm cli sync` | Sync data |

AGI Framework Integration

Adapted for @techwavedev/agi-agent-kit Original source: antigravity-awesome-skills

Memory-First Protocol

Retrieve prior documentation structure and content to maintain consistency. Cache generated docs to avoid regenerating unchanged sections.

# Check for prior documentation context before starting
python3 execution/memory_manager.py auto --query "documentation patterns and prior content for Agents Md"

Storing Results

After completing work, store documentation decisions for future sessions:

python3 execution/memory_manager.py store \
  --content "Documentation: API reference generated from OpenAPI spec, deployment guide updated with new env vars" \
  --type technical --project <project> \
  --tags agents-md documentation

Multi-Agent Collaboration

Share documentation changes with all agents so they reference the latest guides and APIs.

python3 execution/cross_agent_context.py store \
  --agent "<your-agent>" \
  --action "Documentation updated — API reference, deployment guide, and CHANGELOG all current" \
  --project <project>

Agent Team: Documentation

This skill pairs with documentation_team — dispatched automatically after any code change to keep docs in sync.