agent-conventions

Agent Conventions

Apply these conventions when creating or modifying AI agent definitions.

Dispatch

$ARGUMENTS	Action
Active (auto-invoked when working on agent files)	Apply all conventions below
Empty	Display convention summary
check	Run validation checks only

References

File	Purpose
references/readme-template.md	Template for agent README.md index entries

Conventions

Required Frontmatter

Every agent file must include these fields in YAML frontmatter:

• name -- kebab-case, must match filename without .md
• description -- non-empty, describes the agent's purpose

Optional Frontmatter

• tools -- comma-separated tool allowlist (default: all)
• disallowedTools -- comma-separated tool denylist
• model -- sonnet | opus | haiku | inherit (default: inherit)
• permissionMode -- default | acceptEdits | delegate | dontAsk | bypassPermissions | plan
• maxTurns -- integer cap on agentic turns
• skills -- list of skills preloaded into agent context
• mcpServers -- list of MCP servers available to this agent
• memory -- user | project | local
• hooks -- lifecycle hooks scoped to this agent

Memory field conventions:

• Choose the narrowest memory scope: local for temporary insights, project for shared patterns, user for cross-project preferences
• Keep memory entrypoint files under 200 lines — content beyond this is truncated at load time
• Organize memory by topic (e.g., debugging.md, api-patterns.md), not chronologically
• Use MEMORY.md as the index file; create separate topic files for detailed notes

Naming

• All agent names use kebab-case: ^[a-z0-9][a-z0-9-]*$
• Filename (without .md) must match the name frontmatter field exactly
• No consecutive hyphens, no leading/trailing hyphens

README Index Requirement

When defining a new agent at any level:

• ~/.{gemini|copilot|codex|claude}/agents/
• .claude/agents/ (project-level)
• Project-local agent directories

Update the corresponding README.md index in the same directory:

1. Add a row to the index table with agent name, description, and key fields
2. Add a description section with usage details
3. Keep the table sorted alphabetically by name

Body Content

• Write the system prompt in imperative voice ("Check the logs" not "Checks the logs")
• Keep agent definitions focused on a single responsibility
• Reference skills by name rather than inlining their content

Critical Rules

1. Always update the README.md index when adding or modifying an agent
2. Name every agent in kebab-case matching its filename exactly
3. Include both name and description in frontmatter -- they are required
4. Never duplicate agent functionality -- check existing agents first
5. Keep agent system prompts under 500 lines for maintainability
6. Run wagents validate after any agent frontmatter change
7. Use imperative voice throughout the agent body text

Canonical terms (use these exactly):

• agent -- an AI agent definition file in agents/ directory
• frontmatter -- YAML metadata between --- delimiters
• system prompt -- the markdown body after frontmatter
• index table -- the markdown table in README.md listing all agents
• kebab-case -- lowercase words separated by hyphens