AutoGineer
Generated banner for Agents Md
Generated logo for Agents Md

Agents Md

SentryOfficialPublished by Sentry

  • Skill
  • Content generator
  • Software development
  • Apache-2.0
  • No issues found
Download ZIP

From the author

Creates and maintains concise AGENTS.md and CLAUDE.md project instruction files. Use when asked to create AGENTS.md, update AGENTS.md, maintain agent docs, set up CLAUDE.md, document repository agent conventions, or keep coding-agent instructions minimal and reference-backed.
— the description by Sentry

AutoGineer summary

Written by AutoGineer from the skill’s own files, not by the author

This skill provides a structured approach to creating and maintaining AGENTS.md and CLAUDE.md files. It focuses on keeping agent instructions minimal, actionable, and reference-backed to ensure coding agents operate efficiently within a repository. By prioritizing existing documentation and using standardized tables for commands and references, it prevents instruction bloat and ensures consistency across project subdirectories.

What it does

  • Generates concise AGENTS.md files for repository-wide agent configuration.
  • Creates symlinks for CLAUDE.md to maintain a single source of truth.
  • Structures agent instructions using tables for commands and external references.
  • Enforces a strict limit of 100 lines to ensure instructions remain readable.
  • Promotes referencing existing project documentation instead of duplicating content.
  • Standardizes commit attribution requirements for AI-generated code.

When to use it

  • When setting up a new repository that requires specific instructions for coding agents.
  • When existing agent instructions have become bloated or outdated.
  • When you need to define project-specific commands for testing, linting, or building.
  • When you want to ensure agents follow specific repository conventions or security policies.

Advantages

  • Reduces agent hallucination by providing clear, file-scoped command references.
  • Prevents instruction drift by using symlinks for multi-agent compatibility.
  • Improves agent performance by keeping context windows focused on essential rules.
  • Maintains a clean repository structure by avoiding redundant documentation.

Usage examples

“Create an AGENTS.md file for this project.”
The agent inspects the repository structure, identifies the package manager and key commands, and generates a concise AGENTS.md file with tables for commands and references.
“Update our AGENTS.md to include the new linting command.”
The agent updates the existing commands table in AGENTS.md with the specific linting command while maintaining the established formatting and line limits.

Install

  1. Download the skill as a ZIP:

    https://autogineer.com/agent-skills/getsentry/agents-md/download

  2. Unzip it into the cross-client skills folder of your project:

    mkdir -p .agents/skills && unzip agents-md.zip -d .agents/skills

Documentation by Sentry

Maintaining AGENTS.md

Goal: concise, actionable agent instructions. Target under 60 lines; never exceed 100.

Workflow

  1. Inspect before writing:

    • package manager: lock files and manifests

    • commands: package.json, Makefile, task runners, CI workflows

    • docs/specs/policies: README.md, CONTRIBUTING.md, docs/, specs/, policies/, SECURITY.md, .github/

    • conventions: current code patterns, test layout, generated files, legacy areas to avoid

  2. Choose scope:

    • root AGENTS.md: repo-wide defaults

    • nested AGENTS.md: only when a subtree has different commands or rules

    • closest instruction file wins; keep narrower files shorter than root files

  3. Write the smallest useful file.

  4. Verify exact paths and commands exist.

File Setup

  • Create AGENTS.md at the repository root.

  • If a Claude-compatible entrypoint is required, symlink CLAUDE.md to AGENTS.md.

  • Do not maintain divergent AGENTS.md and CLAUDE.md copies.

Default Sections

Use only sections that add non-obvious value.

# Agent Instructions

## Package Manager
- Use **pnpm**: `pnpm install`

## Commands
| Task | Command |
|------|---------|
| Test file | `pnpm vitest run path/to/file.test.ts` |
| Lint file | `pnpm eslint path/to/file.ts` |

## External References
| Need | File |
|------|------|
| Setup | `CONTRIBUTING.md` |
| Architecture | `docs/architecture.md` |
| Security policy | `SECURITY.md` |

## Key Conventions
- Generated files: update with `pnpm generate`; do not edit by hand.

## Commit Attribution
AI commits MUST include:
```
Co-Authored-By: (the agent's name and attribution byline)
```

Writing Rules

  • Use headings, bullets, and tables; avoid paragraphs.

  • Use repo-relative paths; avoid vague references like "see docs".

  • Reference existing docs/specs/policies instead of copying them.

  • List exact external files for setup, architecture, API specs, security, release, and policy docs when they exist.

  • Prefer file-scoped test/lint/typecheck commands; include full builds only when no narrower command exists.

  • Put commands in tables when there is more than one.

  • Keep one rule per bullet.

  • Keep rationale out unless it prevents a likely mistake.

  • Do not restate linter, formatter, or typechecker config.

  • Do not list installed skills or plugins.

  • Do not include generic quality slogans.

External Reference Rules

Good:

## External References
| Need | File |
|------|------|
| API contract | `docs/api.md` |
| Release process | `docs/releasing.md` |

Anti-Patterns

  • welcome text, intros, conclusions, or pleasantries

  • long prose explaining why instructions matter

  • duplicated content from README.md, CONTRIBUTING.md, or policy docs

  • project-wide commands when file-scoped commands are available

  • nested AGENTS.md files that repeat root instructions

Files

SPEC.md

AGENTS.md Specification

Intent

agents-md creates and maintains compact repository instruction files for coding agents.

It should turn scattered repo norms into a short AGENTS.md index: commands, non-obvious conventions, and exact links to existing docs/specs/policies.

Scope

In scope:

  • Root AGENTS.md files.

  • Nested AGENTS.md files for subtree-specific overrides.

  • CLAUDE.md compatibility symlinks when needed.

  • Concise command tables, external reference tables, and commit attribution rules.

  • Removing duplicated prose from existing agent docs.

Out of scope:

  • Rewriting the referenced docs themselves.

  • Replacing README.md, CONTRIBUTING.md, policy docs, or architecture docs.

  • Listing installed skills/plugins.

  • Encoding linter or formatter rules already enforced by config.

  • Maintaining divergent tool-specific copies of the same instructions.

Users And Trigger Context

  • Primary users: engineers and agents maintaining repository-level agent instructions.

  • Should trigger for: create AGENTS.md, update AGENTS.md, maintain agent docs, set up CLAUDE.md, document repo agent conventions, reduce agent instruction prose.

  • Should not trigger for: general docs writing, PR descriptions, code review, or creating reusable agent skills.

Runtime Contract

  • Inspect repo commands, configs, docs, specs, and policies before writing.

  • Prefer exact repo-relative paths and command tables.

  • Enumerate external files for setup, architecture, API specs, security, release, and policy docs when present.

  • Keep root guidance broad and nested guidance narrow.

  • Keep AGENTS.md under 60 lines when practical and under 100 lines always.

  • Preserve the commit attribution section when the repo requires AI co-authorship.

  • Use a CLAUDE.md symlink only for compatibility; avoid divergent copies.

Source And Evidence Model

Authoritative sources:

  • Repository instructions, especially root AGENTS.md.

  • README.md, CONTRIBUTING.md, package manifests, CI workflows, and settings files.

  • Existing project docs, specs, security docs, and policy files.

  • Official AGENTS.md format guidance and OpenAI Codex discovery behavior.

Useful improvement sources:

  • Repositories with concise, path-backed agent docs.

  • Review feedback about stale commands, duplicated docs, or overlong instructions.

  • Agent failures caused by missing exact file paths, command ambiguity, or nested instruction conflicts.

Do not store secrets, private customer data, or long copied policy text in examples.

Reference Architecture

  • SKILL.md contains the runtime checklist, template, and anti-patterns.

  • SPEC.md contains this maintenance contract.

  • SOURCES.md stores provenance, decisions, coverage, and gaps.

  • references/, scripts/, and assets/ are unused until repeated failures require focused lookup material.

Evaluation

  • Lightweight validation: check the generated file for line count, exact commands, exact external paths, no duplicated policy prose, and no vague "see docs" references.

  • Trigger QA: verify create/update/CLAUDE.md requests trigger this skill, while generic docs and skill-authoring tasks do not.

  • Holdout examples: one simple single-package repo, one monorepo with nested overrides, one repo with existing docs/specs/policies to enumerate.

  • Acceptance gates: the resulting AGENTS.md is short, command-backed, path-backed, and free of redundant style rules.

Known Limitations

  • The skill relies on local file inspection; it cannot know private policy docs that are not present or supplied.

  • Some agent tools have provider-specific discovery behavior; keep compatibility notes concise and avoid making one provider the default.

  • Very large monorepos may need several nested files instead of a longer root file.

Maintenance Notes

  • Update SKILL.md when runtime sections, templates, or anti-patterns change.

  • Update SPEC.md when scope, evaluation, or evidence policy changes.

  • Update SOURCES.md when AGENTS.md discovery behavior or source-backed decisions change.

  • Add focused references only when repeated failures cannot be fixed with the compact runtime checklist.

Requirements and compatibility

Works with: Claude Code, Claude apps, OpenAI Codex, GitHub Copilot, Cursor, Gemini CLI, Kiro, OpenCode, Goose, Amp, Roo Code, JetBrains Junie, Factory Droid, Devin (ex-Windsurf), Mistral Vibe, OpenHands, Letta

“Works with” means the tool reads the open Agent Skills format; a skill written for one tool may use features others lack.

Needs: Needs Node.js

Security

No issues found by our static scan· No issues found

A static scan is not a guarantee. Skills are third-party content: review a skill before you let an agent use it.

Attribution and licence

Published by
Sentry
Publisher
Sentry (Official)
Source
getsentry/skills · skills/agents-md · commit e94f222
Licence
Apache License 2.0 (redistribution allowed)
  • LICENSE (added by AutoGineer from LICENSE)
  • ATTRIBUTION.md (written by AutoGineer)
Synced

AutoGineer is not affiliated with or endorsed by Sentry or Sentry.

Download ZIP

The ZIP holds the skill’s files, its licence files and an ATTRIBUTION.md. Download agents-md.zip