Agent Tracks Specification

The complete format specification for Agent Tracks.

TRACK.md Format

Every track must contain a TRACK.md file at its root. This file uses YAML frontmatter for metadata followed by Markdown instructions.

---
name: code-review
description: Review code changes for quality, security, and best practices
---

# Code Review Track

## Instructions

When reviewing code, follow these steps:

1. Check for security vulnerabilities
2. Verify error handling
3. Assess code readability
4. Look for performance issues
...

Required Frontmatter

Field	Type	Description
`name`	string	Unique identifier for the track (kebab-case recommended)
`description`	string	Brief description of what the track does (used for discovery)

Optional Frontmatter

Field	Type	Description
`version`	string	Semantic version for the track
`author`	string	Track author name or organization
`tools`	array	List of tools the track requires
`env`	object	Required environment variables

Directory Structure

my-track/
├── TRACK.md              # Required: metadata + instructions
├── scripts/              # Optional: executable code
│   └── validate.sh
├── references/           # Optional: documentation
│   └── style-guide.md
├── assets/               # Optional: templates, resources
│   └── template.md
└── tests/                # Optional: track tests
    └── test-track.md

Instructions

The body of TRACK.md (after the frontmatter) contains the instructions that agents will read when the track is activated. Write clear, step-by-step instructions that an AI agent can follow.

Best practices for instructions:

Use numbered lists for sequential steps
Be specific about expected outputs
Include examples where helpful
Reference bundled files using relative paths

Track Metadata

Track names should be:

Unique within a project
Written in kebab-case (e.g., code-review, data-pipeline)
Descriptive but concise

Descriptions should:

Clearly state what the track does
Mention when it should be used
Be between 10-200 characters