Agent Definition Frontmatter: Every Field Explained

What is agent definition frontmatter?

Every agent definition starts with YAML frontmatter — structured metadata at the top of the Markdown file, delimited by ---. This metadata tells registries, AI tools, and users what the agent is, what it does, and how to categorize it.

---
id: "code-reviewer"
name: "Code Reviewer"
description: "Reviews code for bugs, security issues, and style violations."
version: "1.0.0"
category: "coding"
tags: ["code-review", "pull-request", "quality"]
license: "MIT"
---

# Code Reviewer

Your agent instructions go here...

The frontmatter is parsed by tools and registries. The Markdown body below it contains the actual agent instructions. This guide covers every frontmatter field in detail.

Required fields

These five fields must be present in every agent definition. Publishing to Agent Shelf will fail without them.

id

id: "code-reviewer"

What it is: A lowercase slug that uniquely identifies your agent within your account.

Validation rules:

• Must match the pattern [a-z0-9][a-z0-9._-]{1,63}
• Starts with a lowercase letter or digit
• Can contain lowercase letters, digits, dots, underscores, and hyphens
• Between 2 and 64 characters total

How it's used: When you publish to Agent Shelf, your GitHub username is prepended to form the full agent ID: yourusername/code-reviewer. This full ID is what users reference when installing your agent.

Tips:

• Choose something descriptive and memorable
• Use hyphens to separate words: api-tester, not apitester or api_tester
• Don't include your username in the ID — it's added automatically
• The ID is permanent. Once published, changing it creates a new agent rather than updating the existing one.

Good IDs: code-reviewer, react-component-generator, security-auditor, changelog-writer

Bad IDs: My_Agent (uppercase, spaces), v2 (too vague), johns-awesome-tool (includes username)

name

name: "Code Reviewer"

What it is: The display name shown in search results, agent cards, and detail pages.

Validation rules:

• Between 3 and 80 characters
• Can include any characters (spaces, capitalization, punctuation)

Tips:

• Make it descriptive and readable: "Code Reviewer" not "cr" or "code_reviewer"
• Include the domain when relevant: "React Component Generator" is better than "Component Generator"
• Avoid generic names like "Helper" or "Assistant" — be specific about what the agent does

description

description: "Reviews pull requests for bugs, security issues, and performance problems. Provides actionable inline feedback with severity levels."

What it is: A short summary shown in search results and agent cards. This is the most important field for discoverability — it's what users read when deciding whether to click on your agent.

Validation rules:

• Between 10 and 240 characters

Tips:

• Lead with what the agent does, not what it is: "Reviews code for security vulnerabilities" not "A security-focused code review agent"
• Mention the specific outputs: "Produces structured findings with severity levels and remediation steps"
• Include key differentiators: what makes this agent better than a generic prompt?
• Write for scanning — users read dozens of descriptions when browsing. Front-load the important information.

version

version: "1.0.0"

What it is: The semantic version number for this release of the agent.

Validation rules:

• Must be valid SemVer format: MAJOR.MINOR.PATCH
• Pre-release suffixes are supported: 1.0.0-beta.1, 2.0.0-rc.1
• Build metadata is supported: 1.0.0+build.123

How versioning works on Agent Shelf:

• Each published version is stored as an immutable snapshot
• You cannot overwrite a published version — you must bump the version number
• Users can pin specific versions or always use the latest
• The versions tab on your agent's page shows the full history

When to bump which number:

• MAJOR (1.0.0 → 2.0.0): Breaking changes. The agent's behavior, output format, or persona changed significantly. Users who depend on specific behavior should review before upgrading.
• MINOR (1.0.0 → 1.1.0): New capabilities. Added new checks, expanded coverage, or added a new section to the output. Backward-compatible — existing behavior unchanged.
• PATCH (1.0.0 → 1.0.1): Fixes. Corrected a rule, improved wording, fixed a false positive. No new capabilities, no changed behavior.

Starting version: Use 1.0.0 for your first public release. Use 0.x.y if the agent is experimental and you expect breaking changes.

category

category: "coding"

What it is: The primary category for your agent. Determines which category page it appears on and helps users filter search results.

Valid values (14 categories):

| Category | What it covers | |----------|----------------| | coding | Code review, testing, debugging, refactoring, code generation | | marketing | SEO, content marketing, email campaigns, copywriting, analytics | | writing | Documentation, technical writing, changelogs, README generation | | automation | Workflow automation, scaffolding, boilerplate generation, CI/CD | | data-analysis | Data exploration, statistics, visualization, reporting | | research | Literature review, competitive analysis, market research | | support | Customer support, troubleshooting, FAQ generation | | design | UI/UX review, design systems, accessibility auditing | | productivity | Project management, onboarding, knowledge management | | education | Tutorials, code explanation, learning assistance | | finance | Financial analysis, budgeting, forecasting, reporting | | devops | Docker, Kubernetes, CI/CD, Terraform, infrastructure | | security | Security auditing, vulnerability scanning, compliance | | other | Anything that doesn't fit the above categories |

Tips:

• Choose the most specific category that fits. An agent that reviews code for security issues could be coding or security — choose security if security is the primary focus.
• Use other sparingly. If you find yourself using it often, your agent might benefit from a more descriptive name and description that help users find it through search instead.

Optional fields

These fields are not required but improve discoverability and provide useful context.

tags

tags: ["code-review", "pull-request", "quality", "security"]

What it is: An array of lowercase tags for fine-grained discoverability. Users can filter by tags when searching.

Validation rules:

• Each tag must match [a-z0-9][a-z0-9_-]{0,31} (lowercase, hyphens, underscores)
• Maximum 20 tags per agent

Tips:

• Use tags for specifics that the category doesn't cover: frameworks (react, django), languages (typescript, python), specific tasks (pull-request, unit-tests)
• Include synonyms and related terms: if your agent handles "linting," also tag it with code-quality
• Don't duplicate the category as a tag — it's redundant
• Look at popular tags on Agent Shelf to see what users search for

Good tags: react, typescript, unit-tests, owasp, terraform, documentation

Bad tags: best (subjective), AI (everything is AI here), new (will become stale)

license

license: "MIT"

What it is: The SPDX license identifier for your agent definition.

Validation rules:

• Between 2 and 120 characters
• Should be a valid SPDX identifier (e.g., MIT, Apache-2.0, GPL-3.0-only)

Tips:

• MIT is the most common choice for agent definitions — it allows anyone to use, modify, and redistribute
• If you don't specify a license, users may be uncertain about whether they can modify or redistribute your agent
• For company-internal agents, you can omit this field or use a custom identifier

Extension fields

The frontmatter schema allows additional fields beyond the required and optional ones. Any key not in the schema is passed through as-is. This is useful for custom metadata:

---
id: "code-reviewer"
name: "Code Reviewer"
description: "Reviews code for bugs and security issues."
version: "1.0.0"
category: "coding"
x-team: "platform-engineering"
x-requires-mcp: ["playwright", "database"]
x-min-context: "100k"
---

Extension fields are stored with the agent but aren't used by Agent Shelf for search or display. They can be useful for internal tooling, automation, or custom integrations.

Common mistakes

Description that's too vague

# Bad
description: "An AI assistant for coding."

# Good
description: "Reviews TypeScript code for type safety issues, unused imports, and React anti-patterns. Produces findings with severity levels and fix suggestions."

ID with invalid characters

# Bad — uppercase and spaces
id: "Code Reviewer"

# Bad — starts with hyphen
id: "-code-reviewer"

# Good
id: "code-reviewer"

Version that's not SemVer

# Bad
version: "1"
version: "v1.0.0"
version: "latest"

# Good
version: "1.0.0"
version: "0.1.0-beta"

Too many or too few tags

# Bad — no tags, harder to discover
tags: []

# Bad — tag spam, dilutes relevance
tags: ["code", "review", "ai", "best", "tool", "assistant", "helper", "coding", "programming", "development", "software", "engineering"]

# Good — specific and relevant
tags: ["code-review", "typescript", "react", "security"]

Full example

Here's a complete, well-structured frontmatter block:

---
id: "react-component-generator"
name: "React Component Generator"
description: "Scaffolds React components with TypeScript types, tests, stories, and barrel exports. Follows your project's existing patterns and conventions."
version: "1.2.0"
category: "coding"
tags: ["react", "typescript", "scaffolding", "components", "testing"]
license: "MIT"
---

Learn more

• How to Write Effective Agent Definitions — complete guide to the Markdown body
• 5 Common Mistakes When Writing Agent Definitions — what to avoid
• Agent Definition Templates — ready-to-use starter templates
• Full documentation — the complete Agent Shelf specification