Best Practices

Tips for writing effective Agent Tracks.

Write clear instructions

Tracks work best when instructions are specific and actionable. Avoid vague directives.

Bad "Review the code for issues"

Good "Check for SQL injection vulnerabilities, verify all database queries use parameterized statements, and ensure error messages don't leak internal details"

Structure your tracks

Organize instructions logically:

• Context: What the agent needs to know upfront
• Steps: Sequential actions to perform
• Output: Expected format for results
• Examples: Sample inputs and outputs when helpful

Write good descriptions

The description field is used for discovery. It should clearly indicate when the track should be activated.

Bad "A track for code stuff"

Good "Review code changes for security vulnerabilities, error handling, and performance issues before merging"

Keep tracks focused

Each track should do one thing well. Instead of one massive track, create multiple focused tracks:

• security-review — Security-focused code review
• performance-review — Performance analysis
• api-design — API design review
• documentation — Documentation generation

Version your tracks

Use semantic versioning in your frontmatter:

---
name: code-review
description: Review code changes for quality and security
version: 1.2.0
---

Test your tracks

Before sharing, test your track with real tasks:

1. Create a sample project with known issues
2. Activate the track and verify the agent follows instructions
3. Check that the output format is correct
4. Refine instructions based on results