AGENTS.md

AGENTS.md is the project context file for AI coding sessions.

It is not the same thing as Agent Skills.

Use AGENTS.md for always-on project guidance. Use Agent Skills for optional, task-specific playbooks.

What AGENTS.md Is

Think of AGENTS.md as a teammate handoff file for future sessions.

It should help an AI quickly understand:

• How to build, test, and validate changes
• Project architecture and boundaries
• Team conventions that matter every session
• Important repo-specific constraints

Reference standard: agents.md

What /init Actually Does

/init

/init does more than output a blank template.

It analyzes your codebase and project docs, then creates or updates a usable AGENTS.md in your project root.

Typical output includes:

• Build/test/lint commands
• High-level architecture notes
• Practical conventions found in your repository
• Useful guidance carried from existing project docs

If AGENTS.md already exists, /init updates it rather than starting from scratch.

What to Include in AGENTS.md

Good content:

• Real commands the project uses (build, test, lint, local run)
• Architecture map (modules/services/boundaries)
• Repo-specific coding and review rules
• Critical workflows (release steps, migration process, CI expectations)

Keep it practical and project-specific.

What Not to Include

Avoid:

• Generic software advice that applies everywhere
• Long file-by-file inventories that can be discovered automatically
• Sensitive secrets or private credentials
• Vague policy text with no actionable guidance

AGENTS.md vs Agent Skills (Different Tools)

Reference standard: agentskills.io

Best Practice: Startup Skill Preferences

Even though AGENTS.md and Skills are different systems, they work well together.

A practical pattern is to record preferred startup skills in AGENTS.md so each new session knows what to load first when relevant.

Example section you can keep in AGENTS.md:

## Session Startup Preferences

- For deep debugging/architecture tasks, load `deep-think`.
- For creating or improving skills, load `skill-editor`.
- For release prep tasks, load `release-checklist` skill if available.
- Ask before loading any externally imported skill.

This keeps startup behavior explicit and consistent across sessions.

Recommended Workflow

1. Run /init at project start (or when docs drift)
2. Review and refine AGENTS.md
3. Keep specialized procedures in Agent Skills
4. Refresh skills with /skills-refresh after edits
5. Use /skills to load only the skill needed for the current task

Next Steps

• Agent Skills — full skills guide
• Commands — slash command reference
• Settings — configuration and behavior controls