agents-md-best-practices

Skill: agents-md-best-practices

Base directory: .opencode/skill/agents-md-best-practices

What I do

I create or update AGENTS.md files so they are short, actionable, and focused on agent success:

• Keep content under 100 lines when possible
• Include only critical commands and workflows
• Emphasize progressive discovery via links to deeper docs
• Capture gotchas and verification steps over time

When to use me

Use this when:

• Starting a new AGENTS.md
• Refactoring an overly long or confusing AGENTS.md
• Adding missing build/test commands or workflow steps
• Capturing newly discovered gotchas or verification steps

How I work

Step 1: Understand project essentials

I identify:

• Project type and stack
• Key folders and entry points
• Build and test commands
• Any agent-specific constraints

Step 2: Draft the short guide

I include only these sections (with the docs index at the top):

• Docs index (deep dives)
• Project overview and structure
• Build/run commands
• Test commands
• Agent workflow (plan -> implement -> verify)

Step 3: Capture feedback loops

I ensure the guide:

• Lists verification commands (linters/tests)
• Notes any known gotchas or slow commands
• Encourages updating the guide when surprises occur

Output format

I produce a concise AGENTS.md with:

• Clear headings
• Short bullet lists
• Minimal examples
• Links to deeper docs

Example output structure

# AGENTS.md - project guide (short)

## Docs index (deep dives)
- [docs/architecture.md](docs/architecture.md)
- [docs/frontend.md](docs/frontend.md)

## Overview
- One line on what the project is
- One line on the stack

## Build and verify
- `pnpm dev`
- `pnpm test`

## Workflow
- Update plan or PRD first
- Implement with small diffs
- Run tests and note any gotchas

Validation checklist

Before finalizing, I ensure:

• File is under 100 lines when feasible
• Commands are correct and minimal
• Verification steps are included
• Progressive discovery links are present
• No redundant or conflicting guidance
• Language matches the project (e.g., German UI notes)