Managing agents md

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

Battle-tested skills for disciplined AI-assisted development. Task tracking, code review, parallel exploration, and more.

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.

What its author says it does

Copied from the file, not written here

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

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.

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

Counted across 1,637 of the 3,044 authors here whose files we hold, read 2026-08-06

announce the skill at startin 54 of 1637, across 21 files
convert legacy doc files before editingin 45 of 1637, across 7 files
predict questions readers might askin 42 of 1637, across 3 files
Generate clarifying questions for initial contextin 42 of 1637, across 3 files
Create document scaffold with placeholder textin 42 of 1637, across 3 files
Brainstorm content options for each sectionin 42 of 1637, across 3 files
Test document with fresh context-less instancein 42 of 1637, across 3 files
ask interview questions one at a timein 42 of 1637, across 26 files
include exact file paths in every taskin 42 of 1637, across 15 files
Apply surgical edits during refinementin 41 of 1637, across 2 files
Offer structured workflow or freeformin 40 of 1637, across 1 file
Ask for document meta-contextin 40 of 1637, across 1 file

Said here and by no other author read

create AGENTS.md for significant new feature directories
create AGENTS.md for extensible or polymorphic systems
use a hierarchical approach for monorepos
add specificity at each directory tier
create a CLAUDE.md importing AGENTS.md

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.