cursor-agents-md_skill

Overview

This skill explains how to write clear, practical AGENTS.md files for Cursor projects. It provides structure, examples, and maintenance strategies so agents follow consistent, project-specific instructions placed at the repository root. Use it to create or update AGENTS.md as a lightweight alternative to .cursor/rules.

How this skill works

The skill inspects AGENTS.md placement, section headings, code examples, commands, and boundaries to ensure clarity and correctness. It recommends a simple markdown structure, enforces single-file global scope, and guides when to prefer .cursor/rules for scoped or complex policies. It also includes guidance for integrating changes, tracking a changelog, and validating commands and examples.

When to use it

• Creating a new AGENTS.md file at the project root
• Improving or clarifying existing AGENTS.md instructions
• Defining project-specific code style, architecture, testing, and commands
• Writing a single-file, global instruction set instead of multiple scoped rules
• Correcting or updating outdated or inconsistent AGENTS.md content

Best practices

• Always place AGENTS.md in the project root and keep it plain markdown with no YAML frontmatter
• Start with essential sections: Code Style, Architecture, File Structure, Testing, Commands, Boundaries
• Prefer concrete code examples and exact commands (include flags and config file references) over vague guidance
• State exact stack versions and key dependencies when relevant
• Use a changelog or inline update notes for significant changes to preserve context
• Before editing, verify Cursor documentation and test any commands or examples being added

Example use cases

• Add concise code style rules and examples (naming, line length, formatter command) for a Python project
• Document architecture patterns such as service layers and DI with concrete file locations
• Specify test framework, coverage target, and test file locations with command examples
• Replace vague tool names with executable commands and config file references
• Convert a small, global rule set into AGENTS.md and move scoped rules to .cursor/rules when needed