agent-conventions
Agent definition conventions. Validate frontmatter, update indexes. Use when creating or modifying agents. NOT for skills, MCP servers, or CLAUDE.md.
How do I install this agent skill?
npx skills add https://github.com/wyattowalsh/agents --skill agent-conventionsIs this agent skill safe to install?
- Gen Agent Trust Hubpass
The skill provides a set of conventions and local validation tools for managing AI agent definition files. No security risks were identified.
- Socketpass
No alerts
- Snykpass
Risk: LOW · No issues
- Runlayerpass
5 files scanned · No issues
What does this agent skill do?
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:
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.mddescription-- non-empty, describes the agent's purpose
Optional Frontmatter
tools-- comma-separated tool allowlist (default: all)disallowedTools-- comma-separated tool denylistmodel--sonnet|opus|haiku|inherit(default:inherit)permissionMode--default|acceptEdits|delegate|dontAsk|bypassPermissions|planmaxTurns-- integer cap on agentic turnsskills-- list of skills preloaded into agent contextmcpServers-- list of MCP servers available to this agentmemory--user|project|localhooks-- lifecycle hooks scoped to this agent
Memory field conventions:
- Choose the narrowest memory scope:
localfor temporary insights,projectfor shared patterns,userfor 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 thenamefrontmatter 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:
- 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
nameanddescriptionin frontmatter -- they are required - Never duplicate agent functionality -- check existing agents first
- Keep agent system prompts under 500 lines for maintainability
- Run
python scripts/validate_agent.py --check-indexafter any agent frontmatter change - Use imperative voice throughout the agent body text
Canonical terms (use these exactly):
agent-- an AI agent definition file inagents/directoryfrontmatter-- YAML metadata between---delimiterssystem prompt-- the markdown body after frontmatterindex table-- the markdown table in README.md listing all agentskebab-case-- lowercase words separated by hyphens
Validation Contract
Before declaring changes to this skill complete, run:
python skills/agent-conventions/scripts/check.py
Completion criteria:
scripts/check.pyexits 0.- Agent frontmatter changes pass
scripts/validate_agent.py --check-index.
How can the creator link this skill?
Add the canonical catalog link to the repository README so users can inspect current installs and available audits. The publishing guide covers the complete discovery path.
<a href="https://skillzs.dev/skills/wyattowalsh/agents/agent-conventions">View agent-conventions on skillZs</a>