agents-md-generator

name	agents-md-generator
description	Generate and maintain AGENTS.md files that document project instructions, build commands, testing procedures, and conventions for AI coding agents. Use when you need to create or update AGENTS.md that describes a repository's structure, setup, testing, code style, deployment, or other agent-relevant guidance. Works with any repository structure.

AGENTS.md Generator

This skill generates and maintains AGENTS.md files—a standard Markdown format used by 60k+ open-source projects to guide AI coding agents through project-specific workflows, conventions, and requirements.

Overview

AGENTS.md serves as the agent-focused counterpart to README.md. While README.md targets human developers, AGENTS.md specifically addresses the needs of AI agents working on your project, including:

• Build and test commands
• Project structure and conventions
• Code style and patterns
• Setup and development environment
• Security considerations
• PR/commit guidelines
• Testing procedures

What the Skill Does

Given a repository directory, this skill:

1. Analyzes the repository - Scans all files to understand the project structure and configuration
2. Extracts relevant information - Identifies build systems, test frameworks, dependencies, and conventions
3. Generates AGENTS.md - Creates or updates an AGENTS.md file with practical guidance for agents
4. Preserves existing content - If AGENTS.md already exists, intelligently merges in new information

How to Use

Creating a new AGENTS.md

Ask Claude to generate AGENTS.md by providing the repository directory:

Please generate an AGENTS.md file for the /path/to/my/repo directory. 
Analyze all files to understand the project structure and conventions.

Claude will:

• Walk through the repository structure
• Identify key files (package.json, Makefile, setup.py, Dockerfile, etc.)
• Extract build, test, and development commands
• Infer code style patterns from existing code
• Generate a comprehensive AGENTS.md

Updating an existing AGENTS.md

To improve or expand an existing AGENTS.md:

Update the AGENTS.md for /path/to/my/repo to include better testing 
instructions and add security considerations section.

Claude will preserve existing content while enhancing with new sections.

Key Sections for AGENTS.md

While AGENTS.md is flexible (no required fields), commonly useful sections include:

Setup and Development

• Install dependencies
• Start dev/test servers
• Environment configuration

Build and Compile

• Build commands
• Compilation steps
• Output artifacts

Testing

• Run tests (all, specific, by pattern)
• CI/CD pipeline overview
• Test coverage tools
• Performance tests

Code Style

• Language-specific conventions
• Linting/formatting tools being used
• Import organization
• Naming conventions

Project Structure

• Major directories and their purpose
• Configuration file locations
• Key entry points

Deployment and Releases

• Deployment procedures
• Release process
• Environment-specific configs
• Versioning strategy

Security

• Security concerns to be aware of
• Authentication/authorization patterns
• Dependency scanning
• Secret management

Monorepo Specific

• How to navigate packages
• Running commands for specific packages
• Cross-package dependencies
• Testing in context of monorepo

Tips for Effective AGENTS.md

1. Be Specific - Include actual command names and flags, not generic descriptions
2. Include Context - Explain why certain steps are needed, not just what to do
3. Show Examples - Include real command examples developers can copy-paste
4. Keep it Current - Update AGENTS.md when development workflows change
5. Use Nested Files - For monorepos, create AGENTS.md files in subdirectories
6. Reference Existing Docs - Link to detailed guides for complex topics
7. Order by Frequency - Put most-used information first