polish-academic-mcp agents.instructions.md

Custom Agent File Guidelines

Instructions for creating effective and maintainable custom agent files that provide specialized expertise for specific development tasks in GitHub Copilot.

Project Context

• Target audience: Developers creating custom agents for GitHub Copilot
• File format: Markdown with YAML frontmatter
• File naming convention: lowercase with hyphens (e.g., test-specialist.agent.md)
• Location: .github/agents/ directory (repository-level) or agents/ directory (organization/enterprise-level)
• Purpose: Define specialized agents with tailored expertise, tools, and instructions for specific tasks
• Official documentation: https://docs.github.com/en/copilot/how-tos/use-copilot-agents/coding-agent/create-custom-agents

Required Frontmatter

Every agent file must include YAML frontmatter with the following fields:

---
description: 'Brief description of the agent purpose and capabilities'
name: 'Agent Display Name'
tools: ['read', 'edit', 'search']
model: 'Claude Sonnet 4.5'
target: 'vscode'
---

Core Frontmatter Properties

description (REQUIRED)

• Single-quoted string, clearly stating the agent's purpose and domain expertise
• Should be concise (50-150 characters) and actionable
• Example: 'Focuses on test coverage, quality, and testing best practices'

name (OPTIONAL)

• Display name for the agent in the UI
• If omitted, defaults to filename (without .md or .agent.md)
• Use title case and be descriptive
• Example: 'Testing Specialist'

tools (OPTIONAL)

• List of tool names or aliases the agent can use
• Supports comma-separated string or YAML array format
• If omitted, agent has access to all available tools
• See "Tool Configuration" section below for details

model (STRONGLY RECOMMENDED)

• Specifies which AI model the agent should use
• Supported in VS Code, JetBrains IDEs, Eclipse, and Xcode
• Example: 'Claude Sonnet 4.5', 'gpt-4', 'gpt-4o'
• Choose based on agent complexity and required capabilities