AgentSkillsCN

managing-agents-md

创建并维护 AGENTS.md 文档文件，引导 AI 编码代理在代码库中高效导航。当您新增重大功能或目录、改变项目架构、搭建新项目或单体仓库，或注意到代码库中尚无 AGENTS.md，又或在经历重大重构、改变项目结构之后，可选用此技能。此外，当您需要“为代理记录相关内容”、“更新 agents.md”或“创建 agents.md”时，此技能也会触发。

SKILL.md
--- frontmatter
name: managing-agents-md
description: Creates and maintains AGENTS.md documentation files that guide AI coding agents through a codebase. Use when adding a significant new feature or directory, changing project architecture, setting up a new project or monorepo, noticing a codebase has no AGENTS.md, or after major refactors that change project structure. Also triggers on "document this for agents", "update agents.md", or "create agents.md".

Managing AGENTS.md

Overview

AGENTS.md is a README for AI agents. It tells any AI coding tool — Claude Code, Copilot, Cursor, Codex — how to navigate and work with your codebase. Keep it updated as the project evolves.

When to Create or Update

Create AGENTS.md when:

  • •Setting up a new project or monorepo
  • •Adding a significant new feature directory (5+ related files)
  • •Introducing an extensible or polymorphic system
  • •A codebase has no AGENTS.md and you're doing substantial work in it

Update AGENTS.md when:

  • •Changing architectural patterns or project structure
  • •Adding new build/test/deploy commands
  • •Modifying base classes, registries, or extension points
  • •Adding significant new directories

Do NOT create for:

  • •Simple utility directories
  • •Single-purpose modules
  • •Non-extensible features
  • •Directories with fewer than 5 related files

Tier Structure

For monorepos or large projects, use a hierarchical approach:

code
Root AGENTS.md         → Project overview, tech stack, global conventions
├── app/AGENTS.md      → App-specific architecture, commands, patterns
│   └── feature/AGENTS.md → Feature-specific extension points

Each tier adds specificity. Agents read from root down to the most relevant file.

Template

markdown
# AGENTS.md — [Project or Directory Name]

Brief one-line description of this part of the codebase.

## Commands

\`\`\`bash
npm run dev      # Start development server
npm test         # Run tests
npm run build    # Production build
\`\`\`

## Project Structure

\`\`\`
src/
├── api/          # REST endpoints (~12 files)
├── services/     # Business logic (~8 files)
├── models/       # Data models (~6 files)
└── utils/        # Shared utilities (~4 files)
\`\`\`

## Key Patterns

[Describe the main architectural patterns, data flow, or conventions]

## Boundaries

### Always
- [Pattern to always follow]
- [Convention to always use]

### Never
- [Anti-pattern to avoid]
- [Dangerous operation]

### Ask First
- [Risky change that needs confirmation]

CLAUDE.md Companion

If the project also uses Claude Code, create a CLAUDE.md that imports the AGENTS.md:

markdown
@AGENTS.md

## Claude-Specific
- [Any Claude Code-specific instructions, hooks, or skill references]

This avoids duplicating content while adding Claude-specific configuration.

Anti-Patterns

Stale documentation: An outdated AGENTS.md is worse than none. Update it when the code changes.

Too granular: Don't create AGENTS.md for every directory. Only for significant architectural boundaries.

Duplicating README: AGENTS.md is for AI agents, not humans. Focus on what an agent needs to navigate and modify code correctly — commands, patterns, boundaries.