agent-conventions

Original：🇺🇸 English

Translated

1 scriptsChecked / no sensitive code detected

Agent definition conventions. Use when creating or modifying agents at any level (~/.claude/agents/, .claude/agents/, or project-local). Validate frontmatter, update README.md index. NOT for creating skills, MCP servers, or modifying CLAUDE.md.

3installs

Sourcewyattowalsh/agents

Added on2026-03-06

NPX Install

npx skill4agent add wyattowalsh/agents agent-conventions

SKILL.md Content

View Translation Comparison →

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:

```
~/.claude/agents/
```
```
.claude/agents/
```
(project-level)
Project-local agent directories

Update the corresponding

README.md

index in the same directory:

Add a row to the index table with agent name, description, and key fields
Add a description section with usage details
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

Always update the README.md index when adding or modifying an agent
Name every agent in kebab-case matching its filename exactly
Include both
```
name
```
and
```
description
```
in frontmatter -- they are required
Never duplicate agent functionality -- check existing agents first
Keep agent system prompts under 500 lines for maintainability
Run
```
wagents validate
```
after any agent frontmatter change
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