Agent File Structure Skill

Purpose

Defines the required structure and best practices for creating agent definition files in .github/agents/*.agent.md .

When to Use

• When creating a new agent definition file

• When reviewing or refactoring existing agent definitions

• When ensuring consistency across the agent ecosystem

Required Structure

All agents must follow this structure:

description: Brief, specific description (≤100 chars) name: Workflow Engineer (coding agent) model: <model name>

Agent Name Agent

You are the Agent Name agent for this project...

Your Goal

Single, clear goal statement.

Boundaries

✅ Always Do: ... ⚠️ Ask First: ... 🚫 Never Do: ...

Context to Read

• Relevant docs with links

Workflow

Step-by-step numbered approach

Output

What this agent produces

Key Principles

• Specific over general - "Write unit tests for React components" beats "Help with testing"

• Commands over descriptions - Include exact commands: npm test , dotnet build

• Examples over explanations - Show real code examples, not abstract descriptions

• Boundaries first - Clear rules prevent mistakes

Frontmatter Requirements

The YAML frontmatter at the top of each agent file must include:

• description : Brief description (100 characters or less) that explains the agent's purpose

• name : The agent's display name (include "(coding agent)" or local agent type)

• model : VS Code agents only — The language model assigned to this agent (must exist in docs/ai-model-reference.md)

⚠️ Coding agents (*-coding-agent.agent.md ) must NOT include model: in frontmatter. The model: property is not supported on GitHub.com coding agents and causes a hard CAPIError: 400 The requested model is not supported error, preventing the agent from running. VS Code agents (without the -coding-agent suffix) should always include model: for LLM selection. See docs/ai-model-reference.md for details.

Section Guidelines

Your Goal

• One clear sentence describing what the agent accomplishes

• Focus on outcomes, not process

• Example: "Implement features and tests according to specifications"

Boundaries

• ✅ Always Do: Mandatory actions the agent must take (use specific commands)

• ⚠️ Ask First: Situations requiring maintainer approval before proceeding

• 🚫 Never Do: Actions that are explicitly forbidden or outside agent scope

Context to Read

• List of documentation files the agent should review before starting work

• Use relative paths with links (e.g., docs/spec.md )

Workflow

• Numbered steps in logical sequence

• Include exact commands where applicable

• Specify decision points and branching logic

Output

• List of artifacts the agent produces

• Include file locations and formats

• Clarify deliverables vs intermediate work

Best Practices

• Be specific: Include exact file paths, command syntax, and expected outputs

• Use examples: Show don't tell - include code snippets and command examples

• Keep it actionable: Every instruction should be something the agent can execute

• Avoid ambiguity: Use precise language and avoid vague terms like "usually" or "might"