The agent file format

Part 1 · Where the files live (the path map)

Memorize-cold. Each path is a binder slot; the exam shows a path and asks "what concept is this?"

Part 2 · The agent file's YAML frontmatter

A custom agent file is Markdown (plain text with simple symbols for headings, links, lists) with a YAML frontmatter (a small settings block at the very top of the file, fenced by --- lines) and a Markdown body below (the persona/role, in prose).

---
description: Reviews PRs for security issues and posts findings   # REQUIRED
name: security-reviewer            # optional — display name only
tools:                             # allowlist of capabilities
  - read
  - search
mcp-servers:                       # MCP server config (YAML), if any
  sentry:
    command: ...
target: github-copilot             # surface: github-copilot | vscode
model: gpt-5                        # pick a model where supported
disable-model-invocation: true     # block auto-invocation by inference
user-invocable: true               # can users invoke it directly?
metadata: { team: platform }       # extra metadata
---
You are a careful security reviewer. Read the diff, flag risky patterns…

Part 3 · The tools list (values + least-privilege)

The tools key takes these values — the same set from 1.6, now as exact config:

Least-privilege is the rule. If the agent only reviews, omit edit; if it never shells out, omit execute. Worked example: an agent with tools: [read, search, agent] can read files, search the repo, and invoke subagents (a subagent is a helper agent that another agent calls to do a sub-task) — but cannot edit files or run shell commands. The capability is exactly the list, nothing implied. MCP tools go alongside: declare the tool in tools (e.g. sentry/get_issue) and configure the server in the mcp-servers block of the same file. This is the capability boundary from 1.6, made literal — and changing the allowlist is a governance-sensitive change (a change risky enough to need extra human review).

Part 4 · Plan → validate → gate (the execution model)

The agent file says what the agent is; this flow controls when it may act. The named exam objective in our words: keep planning separate from doing — the agent produces a plan first, you validate it, and action stays blocked until it's approved.

How the plan becomes enforceable (not just hoped-for):

The safe agent workflow end-to-end: create branch → open PR with plan → reviews → required checks → wait for all checks and approvals → merge. Use plan-first always for workflows, infrastructure, authentication, and production changes.

The cert-language version

A custom agent is a Markdown file with YAML frontmatter at .github/agents/*.agent.md (org/enterprise: /agents/ in .github-private). Required key: description (name optional); tools is an allowlist — omit it → all tools; [] → none — plus mcp-servers, target, model, disable-model-invocation, user-invocable, metadata (handoffs ignored by the cloud agent). Tool values: read, search (repo, not web), edit, execute (shell), agent (invoke subagent; aliases agent/custom-agent/Task); web/todo unsupported in the cloud agent. Instructions are separate — .github/copilot-instructions.md (repo-wide), .github/instructions/*.instructions.md (path-specific), AGENTS.md (root). The execution model keeps planning separate from doing: planners are read-only, the plan is a written artifact (PR body / template), and action is blocked until validated — enforced by a plan-gate workflow made a required status check, CODEOWNERS + required reviews, and environment approvals, never by instruction alone.

Our summary · grounded in MS Learn — Designing Agent Architecture & SDLC Integration (units 1, 3–6, 9) + Foundations (unit 4) · gist (Tier-2, verified) · fetched 2026-05-31

Common confusions (read these or lose points)

• "name is the required key." No — description is required; name is optional display text.
• "No tools key means the agent is locked down." Backwards — omitting tools grants ALL tools. To grant nothing, use tools: [].
• "search searches the web." No — search is repo search; web is the web tool, not available in the cloud agent today.
• "Agent A can just call agent B." No — you must list the agent tool; it isn't automatic.
• "copilot-instructions.md is the agent profile." No — that's an instructions file. The agent profile is .github/agents/*.agent.md.
• "The agent planned, so it can start." No — action is blocked until the plan is validated/approved. A produced plan is not an approved plan.
• "Adding plan-gate.yml blocks bad merges." Not by itself — a workflow only enforces once an admin makes it a required status check. Same for CODEOWNERS: it auto-requests reviewers but only blocks when paired with a required-review policy.
• (Study guide suggests) .github/prompts/*.prompt.md, .github/skills/<skill>/SKILL.md, nearest-AGENTS.md precedence, and the Lab-1 github.head_ref checkout are gist framing — learn the concepts, hold the exact strings loosely.