From 9d4e024f249edd0b4951ad4b74ac4c597f9641cc Mon Sep 17 00:00:00 2001 From: Aaron Powell Date: Thu, 26 Feb 2026 14:13:06 +1100 Subject: [PATCH] docs: expand coding agent article with custom agents, skills, and repo resources - Expand 'Specifying an Agent' into full 'Using Custom Agents' section with agent profile format, storage locations, and selection methods - Add 'Agent Skills and the Coding Agent' section covering how skills are automatically loaded, directory structure, and SKILL.md format - Add comparison table: Instructions vs Skills vs Custom Agents - Add 'Leveraging Community Resources' section linking to this repo's agents, skills, and hooks directories - Update best practices with skills and agent recommendations - Update FAQ to cover both agents and skills - Add skills article to related articles and Next Steps Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- .../using-copilot-coding-agent.md | 146 +++++++++++++++++- 1 file changed, 140 insertions(+), 6 deletions(-) diff --git a/website/src/content/learning-hub/using-copilot-coding-agent.md b/website/src/content/learning-hub/using-copilot-coding-agent.md index 73cc9ff8..264abafd 100644 --- a/website/src/content/learning-hub/using-copilot-coding-agent.md +++ b/website/src/content/learning-hub/using-copilot-coding-agent.md @@ -4,7 +4,7 @@ description: 'Learn how to use GitHub Copilot coding agent to autonomously work authors: - GitHub Copilot Learning Hub Team lastUpdated: '2026-02-26' -estimatedReadingTime: '9 minutes' +estimatedReadingTime: '12 minutes' tags: - coding-agent - automation @@ -12,6 +12,7 @@ tags: relatedArticles: - ./building-custom-agents.md - ./automating-with-hooks.md + - ./creating-effective-skills.md prerequisites: - Understanding of GitHub Copilot agents - Repository with GitHub Copilot enabled @@ -131,16 +132,46 @@ Or provide more specific direction: Use the existing FileUpload component and S3 service. ``` -### Specifying an Agent +### Using Custom Agents -You can direct the coding agent to use a specific custom agent: +Custom agents let you give the coding agent a specialized persona, toolset, and instructions for specific types of work. Instead of relying on generic behavior, you can point the coding agent at an agent profile tailored for your task. + +**Where custom agents live**: Agent profiles are stored as `.agent.md` files in `.github/agents/` in your repository. For organization-wide agents, place them in the root `agents/` directory. ``` -@copilot use the terraform-expert agent to implement this infrastructure change +.github/ +└── agents/ + ├── api-architect.agent.md + ├── test-specialist.agent.md + └── security-reviewer.agent.md +``` + +**Selecting an agent on GitHub.com**: When prompting the coding agent or assigning it to an issue, use the dropdown menu in the agents panel to select your custom agent instead of the default. + +**Selecting an agent via comment**: On any issue, mention the agent by name: + +``` +@copilot use the api-architect agent to implement this API endpoint ``` The agent will adopt the persona, tools, and guardrails defined in that agent file. +**What goes in an agent profile**: An `.agent.md` file is a Markdown file with YAML frontmatter defining the agent's name, description, available tools, and optionally MCP server configurations. The Markdown body contains the agent's behavioral instructions (up to 30,000 characters). + +```markdown +--- +name: test-specialist +description: Focuses on test coverage, quality, and testing best practices +tools: ["read", "edit", "search", "bash"] +--- + +You are a testing specialist. Analyze existing tests, identify coverage gaps, +and write comprehensive unit and integration tests. Follow best practices for +the language and framework. Never modify production code unless asked. +``` + +> **Tip**: Browse the [Agents Directory](/agents/) on this site for ready-to-use agent profiles you can add to your repository. + ## Writing Effective Issues for the Coding Agent The coding agent is only as good as the issue it receives. Well-structured issues lead to better results. @@ -204,6 +235,105 @@ Also, add a test for the Retry-After header value. The agent will read your feedback, make changes, and push new commits to the same PR. +## Agent Skills and the Coding Agent + +Agent skills are folders of instructions, scripts, and resources that the coding agent can automatically load when relevant to a task. While custom agents define _who_ does the work, skills define _how_ to do specific types of work. + +### How Skills Work with the Coding Agent + +When the coding agent works on a task, it reads the `description` field in each skill's `SKILL.md` and decides whether that skill is relevant. If so, the skill's instructions are injected into the agent's context — giving it access to specialized guidance, scripts, and examples without you needing to specify anything. + +This means you can add skills to your repository and the coding agent will **automatically** leverage them when appropriate. + +### Where Skills Live + +Skills are stored in a `skills/` subdirectory, with each skill in its own folder: + +**Project skills** (specific to one repository): +``` +.github/ +└── skills/ + ├── github-actions-debugging/ + │ └── SKILL.md + ├── database-migrations/ + │ ├── SKILL.md + │ └── scripts/ + │ └── migrate.sh + └── api-testing/ + ├── SKILL.md + └── references/ + └── test-template.ts +``` + +**Personal skills** (shared across all your projects): +``` +~/.copilot/ +└── skills/ + └── code-review-checklist/ + └── SKILL.md +``` + +### What Makes Skills Powerful + +Unlike simple instructions, skills can bundle additional resources: + +- **Scripts** that the agent can execute (e.g., a migration script, a code generator) +- **Templates** and examples the agent can reference +- **Data files** and reference material for specialized domains +- **Supplementary Markdown** files with detailed guidance + +The `SKILL.md` file tells the agent when and how to use these resources: + +```markdown +--- +name: database-migrations +description: 'Guide for creating safe database migrations. Use when asked to modify database schema or create migrations.' +--- + +When creating database migrations, follow this process: + +1. Run `./scripts/check-schema.sh` to validate current state +2. Create a new migration file following the naming convention: `YYYYMMDD_description.sql` +3. Always include a rollback section +4. Test the migration against a local database before committing +``` + +### Skills vs Instructions vs Agents + +| Feature | Instructions | Skills | Custom Agents | +|---------|-------------|--------|---------------| +| When loaded | Always (matching file patterns) | Automatically when relevant | When explicitly selected | +| Best for | Coding standards, style guides | Specialized task guidance | Role-based personas | +| Can include scripts | No | Yes | No (but can reference skills) | +| Scope | File-pattern based | Task-based | Session-wide | + +> **Tip**: Browse the [Skills Directory](/skills/) for ready-to-use skills you can add to your repository. Each skill includes a `SKILL.md` and any bundled assets needed. + +## Leveraging Community Resources + +This repository provides a curated collection of agents, skills, and hooks designed for the coding agent. Here's how to use them: + +### Adding Agents from This Repo + +1. Browse the [Agents Directory](/agents/) for agents matching your needs +2. Copy the `.agent.md` file into your repository's `.github/agents/` directory +3. The agent will be available in the dropdown when assigning work to the coding agent + +### Adding Skills from This Repo + +1. Browse the [Skills Directory](/skills/) for specialized skills +2. Copy the entire skill folder into your repository's `.github/skills/` directory +3. The coding agent will automatically use the skill when it's relevant to a task + +### Adding Hooks from This Repo + +1. Browse the [Hooks Directory](/hooks/) for automation hooks +2. Copy the `hooks.json` content into a file in `.github/hooks/` in your repository +3. Copy any referenced scripts alongside it +4. The hooks will run automatically during coding agent sessions + +> **Example workflow**: Combine a `test-specialist` agent with a `database-migrations` skill and a linting hook. Assign an issue to the coding agent using the test-specialist agent — it will automatically pick up the migrations skill when relevant, and the hook ensures all code is formatted before completion. + ## Hooks and the Coding Agent Hooks are especially valuable with the coding agent because they provide deterministic guardrails for autonomous work: @@ -222,6 +352,8 @@ See [Automating with Hooks](../learning-hub/automating-with-hooks/) for configur - **Invest in `copilot-setup-steps.yml`**: A reliable setup means the agent can build and test confidently. If tests are flaky, the agent will struggle. - **Add comprehensive instructions**: The agent reads your `.github/instructions/` files. The more context you provide about patterns and conventions, the better the output. +- **Create skills for repeatable tasks**: If your team frequently does a specific type of work (migrations, API endpoints, test suites), create a skill with step-by-step guidance the agent can follow automatically. +- **Use custom agents for specialized roles**: Create focused agent profiles for different types of work — a security reviewer, a test specialist, or an infrastructure expert. - **Define hooks for formatting**: Hooks ensure the agent's code meets your style requirements automatically, reducing review friction. ### Choosing the Right Tasks @@ -265,15 +397,17 @@ A: The agent has built-in timeouts. If it can't make progress, it will open a PR A: Yes. The coding agent can work on multiple issues in parallel, each in its own branch. Use Mission Control on GitHub.com to track all active agent sessions. -**Q: Does the coding agent use my custom agents?** +**Q: Does the coding agent use my custom agents and skills?** -A: Yes. You can specify which agent to use when assigning work. The coding agent adopts that agent's persona, tools, and guardrails for the session. +A: Yes. You can specify which agent to use when assigning work — the coding agent adopts that agent's persona, tools, and guardrails. Skills are loaded automatically when the agent determines they're relevant to the task, based on the skill's description. ## Next Steps - **Set Up Your Environment**: Create `.github/copilot-setup-steps.yml` for your project +- **Create Skills**: [Creating Effective Skills](../learning-hub/creating-effective-skills/) — Build skills the coding agent can use automatically - **Add Guardrails**: [Automating with Hooks](../learning-hub/automating-with-hooks/) — Ensure code quality in autonomous sessions - **Build Custom Agents**: [Building Custom Agents](../learning-hub/building-custom-agents/) — Create specialized agents for the coding agent to use - **Explore Configuration**: [Copilot Configuration Basics](../learning-hub/copilot-configuration-basics/) — Set up repository-level customizations +- **Browse Community Resources**: Explore the [Agents](/agents/), [Skills](/skills/), and [Hooks](/hooks/) directories for ready-to-use resources ---