# Agents and skills

The AI agents and skills in the Maester repository, who they are for, and how to change them.

Source: https://maester.dev/docs/agents-and-skills

<!-- Generated by build/github/Update-AgentFiles.ps1 from .github/agents and .github/skills. Edit those files, then run the script. -->

# Agents and skills

The Maester repository ships AI agents and skills that know its conventions: how a check is written,
which attributes it needs, how pull requests and issues are labelled. They work in
[GitHub Copilot](https://docs.github.com/copilot) and [Claude Code](https://docs.claude.com/en/docs/claude-code)
when you open the repository. [AGENTS.md](https://github.com/maester365/maester/blob/main/AGENTS.md) holds the rules every agent follows.

## Agents

An agent is a role with its own instructions and tools. Ask for it by name, for example
"use maester-test-planner to plan a check for guest invite settings".

| Agent | For | What it does | How to use it |
| --- | --- | --- | --- |
| [`maester-issue-manager`](https://github.com/maester365/maester/blob/main/.github/agents/maester-issue-manager.agent.md) | Contributors and maintainers | Reserves MT test IDs on issue #697 and keeps tracking issues tidy for new checks. | Called by the other agents, or ask Claude Code to use it |
| [`maester-test-expert`](https://github.com/maester365/maester/blob/main/.github/agents/maester-test-expert.agent.md) | Contributors writing or reviewing checks | Writes, reviews and documents checks, including their attributes and the Test.&lt;ID&gt;.md guide. | Pick it in Copilot's agent list, or ask Claude Code to use it |
| [`maester-test-planner`](https://github.com/maester365/maester/blob/main/.github/agents/maester-test-planner.agent.md) | Contributors planning a new check | Plans a new or changed check before any code is written: files, attributes, validation steps. | Called by the other agents, or ask Claude Code to use it |
| [`maester-triage`](https://github.com/maester365/maester/blob/main/.github/agents/maester-triage.agent.md) | Maintainers and reviewers | Labels and re-labels PRs, issues and discussions with the label rubric so the queue can be filtered. | Pick it in Copilot's agent list, or ask Claude Code to use it |

## Skills

A skill is a body of knowledge an agent loads when the task needs it. The agents above read these, and
any agent can follow them directly.

| Skill | For | What it covers |
| --- | --- | --- |
| [`maester-test-expert`](https://github.com/maester365/maester/blob/main/.github/skills/maester-test-expert/SKILL.md) | Contributors writing or reviewing checks | The full guide to writing a check: layout, templates, attributes, rubric, validation and remediation. |
| [`maester-triage`](https://github.com/maester365/maester/blob/main/.github/skills/maester-triage/SKILL.md) | Maintainers and reviewers | The label rubric for PRs, issues and discussions, and the steps for applying it. |

## Changing an agent or skill

Each agent and skill has one source file, which GitHub Copilot reads:

- an agent is `.github/agents/<name>.agent.md`
- a skill is `.github/skills/<name>/SKILL.md`

Everything else is generated from those files by `build/github/Update-AgentFiles.ps1`: the Claude Code copies under
`.claude/agents/` and `.claude/skills/`, and this page. Never edit the generated files.

To add or change one:

1. Edit or create the source file. Its frontmatter needs `name` and `description`, and a
   `metadata` block with `audience` (who uses it) and `summary` (one sentence on what it does).
   An agent also needs `metadata.claude-tools`: the Claude Code tools it may use, or `all`.
2. Run `./build/github/Update-AgentFiles.ps1`.
3. Commit the source file and the generated files together. `powershell/tests/general/AgentFiles.Tests.ps1`
   fails the build when a generated file is out of date.