agent-conventions

agent-conventions545 wordsMITRepo-owned

Agent definition conventions. Validate frontmatter, update indexes. Use when creating or modifying agents. NOT for skills, MCP servers, or CLAUDE.md.

Quick Start

Install:

npx skills add github:wyattowalsh/agents --skill agent-conventions -y -g --agent antigravity --agent claude-code --agent codex --agent crush --agent cursor --agent gemini-cli --agent github-copilot --agent grok --agent opencode

Use: /agent-conventions

Research context (evidence, not authority)

Problem: Agent definition conventions. Validate frontmatter, update indexes. Use when creating or modifying agents. NOT for skills, MCP servers, or CLAUDE.md. Stack / assumptions: portable skill scripts under scripts/; on-demand references; eval fixtures Comparable alternative: A general-purpose agent instruction without a scoped skill contract

Works with Claude Code, Gemini CLI, OpenCode, and other agentskills.io-compatible agents.

Repo skill (hand-maintained)

Composed compose-custom-wave-1 from skills/agent-conventions/SKILL.md with full SKILL disclosure. Do not run wagents docs generate on this file (HAND-MAINTAINED sentinel).

What It Does

Apply these conventions when creating or modifying AI agent definitions.

Note

This is an auto-invoke skill — it activates automatically when the agent detects relevant context. It is not visible in the / slash command menu.

Modes

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

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 python skills/agent-conventions/scripts/validate_agent.py --check-index 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

Scaffolding

Create new agent definitions with:

python skills/agent-conventions/scripts/scaffold_agent.py <name>

Validation Contract

Before declaring changes to this skill complete, run:

python skills/agent-conventions/scripts/check.py

Completion criteria:

1. scripts/check.py exits 0.
2. Agent frontmatter changes pass scripts/validate_agent.py --check-index.

Public Metadata

Field	Value
Source Type	repo-owned
Display Source	github:wyattowalsh/agents
Source Kind	repo
Installability	portable command
Review State	reviewed
Target Agents	antigravity, claude-code, codex, crush, cursor, gemini-cli, github-copilot, grok, opencode

General

Field	Value
Name	agent-conventions
License	MIT
Version	1.0.0
Author	wyattowalsh

Claude Code

Field	Value
User Invocable	No

View Full SKILL.md

SKILL.md

---
name: agent-conventions
description: >-
  Agent definition conventions. Validate frontmatter, update indexes. Use when
  creating or modifying agents. NOT for skills, MCP servers, or CLAUDE.md.
user-invocable: false
disable-model-invocation: false
license: MIT
metadata:
  author: wyattowalsh
  version: "1.0.0"
---

# 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 |

## Scaffolding

Create new agent definitions with:

```bash
python skills/agent-conventions/scripts/scaffold_agent.py <name>
```

## 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 `python skills/agent-conventions/scripts/validate_agent.py --check-index` 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

## Validation Contract

Before declaring changes to this skill complete, run:

```bash
python skills/agent-conventions/scripts/check.py
```

Completion criteria:

1. `scripts/check.py` exits 0.
2. Agent frontmatter changes pass `scripts/validate_agent.py --check-index`.

Download from GitHub

Resources

Skill Catalog Browse custom and external skills.

CLI Reference Install and manage skills.

agentskills.io The open ecosystem for cross-agent skills.

---

View source on GitHub