Creating Agents
Overview
This skill provides capabilities for creating and reviewing agent definition files (agents.md / agent.md) that transform a general-purpose AI assistant into a focused specialist. Agent definitions give an AI coding agent a specific persona, project knowledge, executable commands, and explicit boundaries.
A well-written agent definition follows the principle: specific beats vague. "You are a helpful coding assistant" fails. "You are a test engineer who writes tests for React components, follows these examples, and never modifies source code" succeeds.
This skill is informed by analysis of over 2,500 agents.md files across public repositories (source).
Capabilities
| Capability |
Action |
Description |
| Create |
actions/create.md |
Generate a new agent definition with persona, commands, and boundaries |
| Review |
actions/review.md |
Analyse an existing agent definition for quality and completeness |
Standards
This skill bundles the following standards in standards/:
| Standard |
File |
Description |
| Agent Structure |
agent-structure.md |
Required sections and organisation for agent definitions |
| Persona |
persona.md |
Writing effective agent personas and role definitions |
| Boundaries |
boundaries.md |
Defining always-do, ask-first, and never-do rules |
| Commands and Tools |
commands-and-tools.md |
Documenting executable commands agents can run |
| Code Style |
code-style.md |
Providing code examples and style guidance to agents |
| Checklist |
checklist.md |
Consolidated compliance and quality checklist |
Principles
1. Specific Beats Vague
Every successful agent definition gives the agent a clear, narrow job. State the exact role, tech stack with versions, file paths, and commands. Ambiguity leads to unpredictable behavior.
2. Show, Don't Tell
One real code snippet showing your preferred style beats three paragraphs describing it. Provide concrete examples of good output — naming conventions, error handling patterns, test structures.
3. Commands Early, Boundaries Clear
Put executable commands (npm test, pytest -v, cargo build) near the top of the agent definition. Agents reference these often. Define boundaries using a three-tier system: ✅ Always do, ⚠️ Ask first, 🚫 Never do.
4. Cover the Six Core Areas
The best agent definitions address six areas:
- Commands — Executable commands with flags and options
- Testing — Test framework, commands, and coverage expectations
- Project structure — File layout and what lives where
- Code style — Naming, patterns, and concrete examples
- Git workflow — Branch naming, commit messages, PR process
- Boundaries — What the agent must never touch
5. Start Small, Iterate
Begin with a minimal agent definition for one specific task. Test it with real work. Add detail when the agent makes mistakes. The best agent definitions grow through iteration, not upfront planning.
Usage
- Load this skill manifest
- Identify the required capability (create or review)
- Load the bundled standards from
standards/
- Execute the action following
actions/<capability>.md
References
1---2name: creating-agents3description: Create and review agent definition files (agents.md) that give AI coding agents a clear persona, project knowledge, executable commands, code style examples, and explicit boundaries. Use when a user asks to create an agent, define an agent persona, write an agents.md file, set up a custom Copilot agent, review an existing agent definition, or improve agent quality. Covers the six core areas: commands, testing, project structure, code style, git workflow, and boundaries.4license: MIT5---67# Creating Agents89## Overview1011This skill provides capabilities for creating and reviewing agent definition files (`agents.md` / `agent.md`) that transform a general-purpose AI assistant into a focused specialist. Agent definitions give an AI coding agent a specific persona, project knowledge, executable commands, and explicit boundaries.1213A well-written agent definition follows the principle: **specific beats vague**. "You are a helpful coding assistant" fails. "You are a test engineer who writes tests for React components, follows these examples, and never modifies source code" succeeds.1415This skill is informed by analysis of over 2,500 `agents.md` files across public repositories ([source](https://github.blog/ai-and-ml/github-copilot/how-to-write-a-great-agents-md-lessons-from-over-2500-repositories/)).1617## Capabilities1819| Capability | Action | Description |20|------------|--------|-------------|21| Create | `actions/create.md` | Generate a new agent definition with persona, commands, and boundaries |22| Review | `actions/review.md` | Analyse an existing agent definition for quality and completeness |2324## Standards2526This skill bundles the following standards in `standards/`:2728| Standard | File | Description |29|----------|------|-------------|30| Agent Structure | `agent-structure.md` | Required sections and organisation for agent definitions |31| Persona | `persona.md` | Writing effective agent personas and role definitions |32| Boundaries | `boundaries.md` | Defining always-do, ask-first, and never-do rules |33| Commands and Tools | `commands-and-tools.md` | Documenting executable commands agents can run |34| Code Style | `code-style.md` | Providing code examples and style guidance to agents |35| Checklist | `checklist.md` | Consolidated compliance and quality checklist |3637## Principles3839### 1. Specific Beats Vague4041Every successful agent definition gives the agent a clear, narrow job. State the exact role, tech stack with versions, file paths, and commands. Ambiguity leads to unpredictable behavior.4243### 2. Show, Don't Tell4445One real code snippet showing your preferred style beats three paragraphs describing it. Provide concrete examples of good output — naming conventions, error handling patterns, test structures.4647### 3. Commands Early, Boundaries Clear4849Put executable commands (`npm test`, `pytest -v`, `cargo build`) near the top of the agent definition. Agents reference these often. Define boundaries using a three-tier system: ✅ Always do, ⚠️ Ask first, 🚫 Never do.5051### 4. Cover the Six Core Areas5253The best agent definitions address six areas:54551. **Commands** — Executable commands with flags and options562. **Testing** — Test framework, commands, and coverage expectations573. **Project structure** — File layout and what lives where584. **Code style** — Naming, patterns, and concrete examples595. **Git workflow** — Branch naming, commit messages, PR process606. **Boundaries** — What the agent must never touch6162### 5. Start Small, Iterate6364Begin with a minimal agent definition for one specific task. Test it with real work. Add detail when the agent makes mistakes. The best agent definitions grow through iteration, not upfront planning.6566## Usage67681. Load this skill manifest692. Identify the required capability (create or review)703. Load the bundled standards from `standards/`714. Execute the action following `actions/<capability>.md`7273## References7475- [How to write a great agents.md](https://github.blog/ai-and-ml/github-copilot/how-to-write-a-great-agents-md-lessons-from-over-2500-repositories/) — Lessons from over 2,500 repositories76- [GitHub Copilot Custom Agents](https://docs.github.com/en/copilot/customizing-copilot/adding-repository-custom-instructions-for-github-copilot) — Official documentation77- [Agent Skills Specification](https://agentskills.io/specification) — Open format for agent capabilities
diegosouzapw