AGENTS.md Generator

You’re setting up GitHub Copilot agents for your repository and want to give them clear, consistent instructions without writing the markdown by hand. Or you’re standardizing how AI agents behave across multiple repositories. This generator lets you define agent roles, allowed tools, constraints, and code style preferences through a visual form and outputs a ready-to-commit AGENTS.md file.

What Is AGENTS.md?

AGENTS.md is a convention for defining how AI coding agents should behave when working in a repository. Placed at the root of your project, it provides agents with structured context about their role, what tools they can use, what they must not do, and how they should write code.

The convention was popularized with the rise of autonomous coding agents — tools that can read files, write code, run tests, and make commits without per-step human approval. Without guidance, these agents make arbitrary decisions about style, scope, and behavior. AGENTS.md gives them a project-specific rulebook.

The GitHub Copilot Agent System

GitHub Copilot Workspace and Copilot agents read repository context files to calibrate their behavior. When you add AGENTS.md to your repository, agents use it to understand:

• What their job is — are they reviewing code, fixing bugs, adding features, or writing docs?
• What tools they can use — file system access, running tests, installing packages, making commits
• What they must not do — protecting production configs, avoiding certain directories, requiring human approval for destructive actions
• How to write code — your project’s style conventions, TypeScript strictness, testing framework, naming patterns

This is similar to how .cursorrules, CLAUDE.md, and system prompts work for other AI coding tools — each establishes a shared understanding between human and AI about how work should be done.

Configuration Patterns That Work Well

Role specificity

Vague: “You are a helpful coding assistant.” Specific: “You are a code review agent. Your job is to review pull requests for security vulnerabilities, performance issues, and deviation from the patterns in src/.”

The more specific the role, the more consistent the agent’s behavior.

Layered constraints

Start with what the agent is allowed to do (opt-in), then add explicit prohibitions. This prevents the agent from making well-intentioned but unwanted changes:

## Allowed Tools & Actions
- Read and write files in src/ and tests/
- Run npm test to verify changes
- Search the codebase

## Constraints
- Do NOT modify files in config/ without human approval
- Do NOT change package.json dependencies
- Do NOT make commits — stage changes only

Testing requirements

Agents that write tests without clear requirements often produce coverage theater — tests that pass but don’t actually verify behavior. Be explicit:

## Testing Requirements
- Write tests using Vitest, matching the patterns in tests/
- Add a regression test for every bug fix
- Test error paths, not just happy paths
- Run npm test before considering a task complete

Frequently Asked Questions

Where should I place AGENTS.md? Place it at the root of your repository (same level as package.json or README.md). Some tools also support directory-level AGENTS.md files for monorepos — check your specific tool’s documentation.

Is AGENTS.md the same as CLAUDE.md or .cursorrules? They serve the same purpose but for different tools. CLAUDE.md is read by Claude Code, .cursorrules by Cursor, and AGENTS.md by GitHub Copilot Workspace agents. The conventions overlap — clear role definition, allowed actions, and constraints are useful regardless of the tool. You can maintain multiple files with similar content if you use multiple AI coding tools.

Should I commit AGENTS.md to version control? Yes. Committing AGENTS.md ensures all contributors (human and AI) use the same agent configuration. It also makes the agent’s expected behavior reviewable and auditable as your project evolves.

How specific should constraints be? As specific as necessary to prevent the failures you’ve actually seen. Start minimal — a role definition and a short constraints list — then add more detail when an agent does something unexpected. Over-constraining can make agents less useful; under-constraining causes inconsistency. Iterate based on real usage.