# Wyattowalsh Agents Agent Conventions

> Agent Conventions

- Skill: `tomevault-io/wyattowalsh-agents-agent-conventions` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add tomevault-io/wyattowalsh-agents-agent-conventions`
- Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/wyattowalsh-agents-agent-conventions/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: tomevault-io (https://skillmd.com/u/tomevault-io)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/tomevault-io/wyattowalsh-agents-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

---
> Converted and distributed by [TomeVault](https://tomevault.io/claim/wyattowalsh) — claim your Tome and manage your conversions.
<!-- tomevault:4.0:skill_md:2026-04-13 -->