---
name: agent-authoring
description: How to design, structure, and validate custom Copilot agents for this workspace.
---
# Agent Authoring Skill
Guidelines for creating and maintaining custom GitHub Copilot agents (.agent.md) tailored to this repository.
## When to Use
- You need a new Copilot agent focused on a workflow (e.g., Storybook tests, log triage).
- You want to adjust tools/persona for existing agents.
- You are adding workspace-level agents under .github/agents or profile-level agents for reuse.
## Quick Start
1) Create `.github/agents/<agent-name>.agent.md` (VS Code auto-detects this folder/extension).
2) Add YAML frontmatter with only supported fields: `name`, `description`, `tools`, `target`, `infer`, `mcp-servers`, `handoffs`.
3) In the body, write concise instructions: task focus, guardrails, run/validate steps, and handoffs.
4) Keep it under ~200-300 lines; link out to docs instead of pasting everything.
## Frontmatter Cheatsheet
- `name`: Display name; defaults to file name if omitted.
- `description`: Placeholder text in chat input; keep short.
- `tools`: List allowed tools. For MCP servers, use `<server>/*` to include all tools or enumerate specific ones.
- `target`: `github-copilot` for Copilot agents (default), `vscode` for VS Code target.
- `infer`: Allow subagent use (default true). Set false if you want to restrict subagents.
- `mcp-servers`: For Copilot agents, point to MCP server configs (paths to server JSON). Use only if you need to pin servers.
- `handoffs`: Optional array of next-step buttons `{ label, agent, prompt?, send? }`.
## Body Structure (recommended)
- **Purpose and scope**: What this agent does and what it must not do.
- **Operating defaults**: Where to run commands, what to inspect first, preferred scripts.
- **Playbooks**: Ordered steps for common flows (run, debug, fix, validate).
- **Guardrails**: Safe-edit rules (scope, no unrelated changes, ask before destructive ops).
- **Validation**: How to verify work (tests/linters), how to summarize outputs.
- **Links**: Point to repo docs or skills for deeper detail.
## Tool Selection Patterns
- Editing agent: include `workspace`, `terminal`, `search`; add `fetch` for docs; add MCP toolsets only if required.
- Read-only agent: omit editing tools; keep `fetch`/`search`.
- Narrow the tool list to prevent unsafe actions (e.g., no `terminal` for planning-only agents).
## Handoffs
Use handoffs to guide sequential flows (e.g., Plan -> Implement -> Review). Keep labels short and make prompts actionable. Use `send: false` unless you want auto-submit.
## Quality Bar
- Minimal, task-focused instructions; avoid boilerplate.
- No unsupported frontmatter fields (reject `argument-hint`, etc.).
- Prefer scoped commands over global installs; mention working directory if non-root.
- Add guardrails for destructive commands (never propose `git reset --hard`).
- Keep instructions ASCII and concise; use fenced code blocks for commands.
## Validation Checklist
- [ ] Supported frontmatter only; fields spelled correctly.
- [ ] Tools list matches the agent’s intent; no over-broad capabilities.
- [ ] Clear run/validate steps with default commands.
- [ ] Guardrails called out.
- [ ] Links resolve (relative paths within repo or official docs).
## Examples
- Location: `.github/agents/storybook-interaction-tests.agent.md` (interaction test fixer playbook).
- Planning agent: frontmatter with `tools: ['fetch', 'search']`, body instructs to gather context and produce a plan, handoff to implementation agent.
## Maintenance Tips
- Keep agents in sync with repo workflows (scripts, test commands). Update after script changes.
- Remove stale handoffs when target agents are renamed or removed.
- Prefer additive changes; avoid reformatting existing agents without need.
