Generate AGENTS.md

Extract operational content from CLAUDE.md to create a universal AGENTS.md file for cross-tool compatibility with Cursor, Codex, Copilot, and other AI agents.

Overview

This workflow extracts the Operations and Boundaries sections from CLAUDE.md to generate a minimal, universal AGENTS.md file that works across 20+ AI coding tools.

Why generate instead of symlink?

• Symlinks may not work on all systems (Windows)

• AGENTS.md can be customized without affecting CLAUDE.md

• Some teams prefer explicit files over symlinks

• Allows for tool-specific adjustments

When to Use

✅ Use this workflow when:

• Team uses multiple AI tools (Cursor + Claude Code, Codex + Claude)

• Deploying to systems where symlinks don't work well

• Want a standalone AGENTS.md for open-source projects

• Need to customize AGENTS.md separately from CLAUDE.md

❌ Use symlink instead when:

• Only team uses Claude Code and one other tool

• System supports symlinks reliably

• Want single source of truth with no drift

Symlink command: ln -s CLAUDE.md AGENTS.md

Process

Step 1: Analyze CLAUDE.md

AI reads CLAUDE.md and identifies:

• Operations section - Setup, Testing, Build, Code Style commands

• Boundaries section - Protected files, never commit, ask before

• Project-specific customizations (if any)

Step 2: Generate AGENTS.md

Create AGENTS.md with AGENTS.md standard structure:

AGENTS.md

Auto-generated from CLAUDE.md. For full methodology, see CLAUDE.md. Last generated: [DATE]

Project Overview

[Brief description - AI extracts from README or project.md if available]

Setup Commands

[Extracted from CLAUDE.md Operations section]

Testing

[Extracted from CLAUDE.md Operations section]

Build & Deploy

[Extracted from CLAUDE.md Operations section]

Code Style

[Extracted from CLAUDE.md Operations section]

Boundaries

[Extracted from CLAUDE.md Boundaries section]

For detailed guardrails, 4D methodology, and workflows, see CLAUDE.md

Step 3: Verify and Save

• AI presents generated AGENTS.md for review

• User approves or requests changes

• Save to project root: ./AGENTS.md

AGENTS.md Template

AGENTS.md

Auto-generated from CLAUDE.md | Last updated: YYYY-MM-DD Full documentation: CLAUDE.md

Project Overview

[PROJECT_NAME] - [BRIEF_DESCRIPTION]

Tech Stack: [PRIMARY_TECHNOLOGIES] Language: [PRIMARY_LANGUAGE]

Setup Commands

# Install dependencies
[INSTALL_COMMAND]

# Start development server
[DEV_COMMAND]

# Environment setup
cp .env.example .env

Testing

# Run all tests
[TEST_COMMAND]

# Run with coverage (target: >80% business logic)
[COVERAGE_COMMAND]

# Watch mode
[WATCH_COMMAND]

Build & Deploy

# Production build
[BUILD_COMMAND]

# Type check
[TYPECHECK_COMMAND]

# Lint
[LINT_COMMAND]

Code Style

# Format code
[FORMAT_COMMAND]

# Lint and fix
[LINT_FIX_COMMAND]

Conventions:

- [STYLE_RULE_1]

- [STYLE_RULE_2]

- [STYLE_RULE_3]

Boundaries

Do Not Modify

- Lock files (package-lock.json
, yarn.lock
, Cargo.lock
)

- Environment files (.env
, .env.local
)

- CI/CD configurations (.github/workflows/
)

- Applied database migrations

Never Commit

- Secrets, API keys, credentials

- .env
 files (use .env.example
)

- Build artifacts, node_modules/
, target/

Ask Before Changing

- Authentication/authorization logic

- Database schemas

- Public API contracts

- Major dependencies

Additional Context

For detailed development guidelines, see:

- Full Methodology: CLAUDE.md

- Skills: .claude/skills/

This file follows the AGENTS.md standard.

---

## Customization Guide

### Project-Specific Adjustments

When generating AGENTS.md, AI should:

1. **Detect tech stack** from:
   - `package.json` (Node.js)
   - `requirements.txt` / `pyproject.toml` (Python)
   - `go.mod` (Go)
   - `Cargo.toml` (Rust)

2. **Extract actual commands** from:
   - `package.json` scripts
   - `Makefile`
   - `justfile`
   - CI/CD workflows

3. **Include project-specific boundaries** from:
   - `CLAUDE.md` (if exists)
   - Existing `.gitignore` patterns

### Monorepo Support

For monorepos, generate nested AGENTS.md files:

project/
├── AGENTS.md              # Root-level (general)
├── CLAUDE.md              # Full methodology
├── packages/
│   ├── api/
│   │   └── AGENTS.md      # API-specific commands
│   └── web/
│       └── AGENTS.md      # Web-specific commands

Each nested AGENTS.md should:
- Focus on that package's commands
- Reference root AGENTS.md for general guidelines
- Include package-specific boundaries

---

## Maintenance

### When to Regenerate

Regenerate AGENTS.md when:
- CLAUDE.md Operations section changes
- New build/test commands added
- Project structure changes significantly
- Tech stack updated

### Keeping in Sync

**Option A: Manual regeneration**
```bash
# Load this skill periodically when CLAUDE.md changes
.claude/skills/generate-agents-md/SKILL.md

Option B: Pre-commit hook

# .husky/pre-commit or similar
# Check if CLAUDE.md changed, regenerate AGENTS.md

Option C: CI/CD check

# .github/workflows/check-agents-md.yml
- name: Verify AGENTS.md is up to date
  run: |
    # Compare timestamps or checksums

Example Usage

Request

Generate AGENTS.md for this project using the generate-agents-md skill

AI Response

I'll analyze your project and generate an AGENTS.md file.

**Detected:**
- Tech stack: TypeScript, React, Node.js
- Package manager: npm
- Test framework: Vitest
- Linter: ESLint + Prettier

**Generated AGENTS.md:**
[Shows preview]

**Save to:** ./AGENTS.md

Approve? [Yes/No/Edit]

Integration with CLAUDE.md

How They Work Together

File
Purpose
Audience

CLAUDE.md

Full methodology + guardrails
Claude Code

AGENTS.md

Operational commands
All AI tools

Reading Priority (Claude Code)

- Claude Code reads CLAUDE.md
 (primary)

- If CLAUDE.md
 not found, reads AGENTS.md
 (fallback)

- Both can coexist (different purposes)

For Other Tools

Most tools (Cursor, Codex, Copilot) read:

- AGENTS.md
 (primary)

- May also read CLAUDE.md
 if present

Troubleshooting

Issue: AGENTS.md and CLAUDE.md out of sync

Solution: Regenerate AGENTS.md or set up sync mechanism

Issue: Other tools not reading AGENTS.md

Solution: Ensure file is in project root, named exactly AGENTS.md

Issue: Symlink not working

Solution: Use this skill to generate actual file instead

Issue: Need different commands for different tools

Solution: Generate AGENTS.md with common subset, add tool-specific comments

Remember: AGENTS.md is for operational commands. Keep it minimal and actionable. Full methodology stays in CLAUDE.md.