How to write a great agents.md: Lessons from over 2,500 repositories (github.blog)

GitHub announced a Copilot feature that lets repositories define custom assistant personas via agents.md files, enabling teams to create specialist agents like @docs-agent, @test-agent and @security-agent instead of a single general helper. Each agents.md (stored under .github/agents/) uses YAML frontmatter plus explicit instructions to declare the agent’s persona, tech stack, file structure, executable commands it may run, code-style examples, and three-tier boundaries (always/ask first/never). The feature is practical and low-friction: Copilot can even scaffold agent.md files, and recommended early use-cases include documentation generation, test writing, lint fixes, API work, and dev-only deployments. An analysis of 2,500+ public agents.md files surfaced clear patterns for success: make agents specialists (specific role and stack with versions), put executable commands up front (npm test, npm run build, pytest -v, npm run docs:build, npx markdownlint docs/ with flags), show real code examples rather than long prose, and set strict boundaries (never commit secrets, don’t edit vendor or prod configs, require approval for schema or deploy changes). Cover six core areas—commands, testing, project structure, code style, git workflow, and boundaries—and start minimal, iterate when the agent misbehaves. The takeaway: well-specified agents unlock safe automation and faster workflows, while vague prompts fail; the balance of specificity and operational guardrails is key to reliable repo automation.