Managing agents md

Skill oryanmoshe/agent-skills/skills/managing-agents-md

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".From its SKILL.md

Install

npx -y skills add oryanmoshe/agent-skills --skill managing-agents-md

Assembled from the repository path, not quoted from the project. Check it against their README if it does not work.

2 things to look at

no licenseNo license file was found in the repository. Code published without one is not open source by default, so using it at work is a question for whoever answers licensing questions where you are.
2 stars2 stars. Stars are a popularity signal and not a quality one, but at this level it is likely that nobody has read this closely except its author, and you would be relying on your own review.

SKILL.md

3.2 KB, 646 tokens by cl100k_base, as published. Nobody here has run it

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:

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

# 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:

@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.

What ships with it

Read from the repository

Just SKILL.md. No reference files, no scripts.

Gives 0 of the 12 instructions most docs writing skills give in 646 tokens

Counted across 1,951 of the 3,904 authors here whose files we hold, read 2026-09-06

Use third-person for skill descriptionsin 54 of 1951, across 35 files
Start descriptions with Use whenin 43 of 1951, across 29 files
Run baseline scenarios before writing any skillin 40 of 1951, across 26 files
Use active voicein 40 of 1951, across 36 files
Map file responsibilities before defining tasksin 36 of 1951, across 29 files
Use checkbox syntax for tracking stepsin 35 of 1951, across 27 files
Ask one question at a timein 35 of 1951
Offer execution options after saving the planin 33 of 1951, across 24 files
Include complete code in every stepin 33 of 1951, across 27 files
Design units with clear boundaries and interfacesin 31 of 1951, across 23 files
Announce the skill usage at the startin 30 of 1951
Verify agent compliance after adding the skillin 29 of 1951, across 17 files

Said here and by no other author read

Update AGENTS.md when project structure changes
Use hierarchical AGENTS.md files for large projects
Focus content on agent navigation and modification needs
Include commands and architectural patterns in documentation
Define boundaries for always, never, and ask first

Grouped from the skills themselves: near-identical wordings counted once, and counted by distinct author, so one author publishing three of these counts once. Length counted with cl100k_base; the agent that loads this file may tokenize it differently.