Designing High-Quality Custom Markdown Agents for GitHub Copilot

An engineer’s guide to designing safe, focused, and high-signal custom GitHub Copilot markdown agents

Custom agents for GitHub Copilot are defined using structured Markdown with YAML frontmatter and explicit instructions that guide Copilot behavior. To build agents that are meaningful, effective, and productive, engineers must approach agent design as a form of systems design. The agent profile defines intent, boundaries, expectations, and safety in a compact yet highly leveraged artifact.

The Quality Reviewer agent provides a concrete example of how to encode not only a task, but also the criteria used to judge agent quality. This article distills the principles embedded in that agent and reframes them as guidance for building robust custom Markdown agents.

Define a Clear Mission and Purpose

Every agent should begin with a clearly stated mission that explains what the agent is responsible for and what it is not. A strong mission statement identifies the role the agent plays and the outcome it is expected to produce.

In the Quality Reviewer agent, the mission is explicit and unambiguous:

## Mission
You are a **Quality Reviewer** for GitHub Copilot Markdown agent profiles. Your task is to evaluate an agent profile against explicit quality criteria and produce a structured review report.

This definition leaves no uncertainty about intent, scope, or output. The agent is not a generator, not a fixer, and not a refactoring tool. It is an evaluator.

Avoid vague language such as “help with” or “assist in.” Prefer direct verbs such as evaluate, analyze, generate, verify, or review. The mission should be understandable without reading the rest of the file.

Why this matters:
A clear mission establishes intent early and prevents scope drift. It reduces ambiguity for both the human reader and the model, which improves alignment and response quality.

Explicitly Define Scope and Tool Boundaries

Tool access is one of the most critical design decisions in an agent profile. Agents should be granted only the minimal tools necessary to perform their task.

The Quality Reviewer encodes this both in frontmatter and in narrative constraints:

tools: [’read’]

## Constraints & Boundaries
- **Read-only scope:** Do not use write/edit/search tools
- **No modifications:** You must not modify the agent or generate code patches

This dual reinforcement is intentional. Frontmatter constrains capability at the platform level, while instructions constrain reasoning behavior.

Beyond tool limits, the agent also forbids implicit assumptions:

- **Explicit references:** Refer to the agent’s contents explicitly; do not assume workspace context beyond what you have read.

Why this matters:
Clear boundaries prevent unsafe behavior and unintended side effects. They also reduce the likelihood that the model will hallucinate actions or context outside its permitted scope.

Specify Inputs and Context Expectations Precisely

Agents should clearly state what inputs they expect and what optional context may be provided. Required inputs should be unambiguous.

The Quality Reviewer separates required and optional inputs cleanly:

## Inputs
- The **Markdown agent profile** under review
- (Optional) A description of the intended use case or workflow context

Optional context is explicitly marked as optional, which signals to the agent that it must not rely on that information unless it is provided.

The agent also defines how to behave when context is missing:

- **Clarification protocol:** If context is insufficient, ask up to three clarifying questions and proceed only with explicit clarifications.

Why this matters:
When context expectations are unclear, the model fills in gaps with assumptions. Precise input definitions prevent hallucination and improve determinism.

Encode Quality Dimensions and Evaluation Criteria

High-quality agents often evaluate or reason about complex artifacts. In these cases, the agent should define the dimensions it uses to judge quality or correctness.

The Quality Reviewer explicitly enumerates its evaluation dimensions:

## Quality Dimensions & Scoring (1–5 per Dimension)

1. **Role Definition**
2. **Tool Scoping**
3. **Output Expectations**
4. **Context Specificity**
5. **Phase Alignment**
6. **Safety & Guardrails**
7. **File Focus & Practical Size**

Each dimension is accompanied by guiding questions, which serve as evaluation heuristics rather than vague principles.

For example:

- Are tools appropriately scoped?
- Has the agent been granted only the minimal tools necessary?

Why this matters:
Explicit evaluation criteria act as a shared mental model between the agent and the user. They encourage consistent reasoning and make the agent’s judgments easier to understand and challenge.

Structure the Agent’s Reasoning as a Procedure

Complex tasks should be broken into ordered steps or phases. Each phase should have a clear purpose and bounded scope.

The Quality Reviewer enforces a procedural approach through explicit steps:

## Evaluation Procedure

### Step 1 — Profile Analysis & Constraint Verification
### Step 2 — Instructional Clarity Audit
### Step 3 — Scoring & Rubric Application
### Step 4 — Fit to Workflows
### Step 5 — Report Generation

Each step has a narrowly defined responsibility, which prevents the agent from collapsing analysis, judgment, and reporting into a single unstructured response.

Why this matters:
Structured procedures reduce cognitive load for the model and improve coverage. They make it less likely that important checks or steps will be skipped.

Make Output Expectations Explicit and Reproducible

Agents should not leave output format to chance. If the agent is expected to produce a report, that structure should be defined explicitly.

The Quality Reviewer requires the final output to use an exact template:

Produce your review using this *exact template*:

Followed by a full Markdown report structure:

# Quality Review Report

## Frontmatter Summary
- name: ...
- description: ...
- tools: ...

This eliminates ambiguity about structure, ordering, and level of detail.

Why this matters:
Clear output expectations align the agent’s responses with user needs. They reduce follow-up prompts and make outputs easier to scan, compare, and reuse.

Include Guardrails and Clarification Protocols

Agents should be allowed to ask for clarification, but only in controlled ways.

The Quality Reviewer limits clarification explicitly:

If context is insufficient, ask up to three clarifying questions and proceed only with explicit clarifications.

This prevents infinite questioning loops while still allowing the agent to avoid unsafe assumptions.

Why this matters:
Clarification protocols prevent incorrect conclusions based on incomplete data. They also make agent behavior predictable and trustworthy.

Align the Agent to a Specific Development Phase

Agents are most effective when they are aligned to a specific phase of work.

The Quality Reviewer enforces this alignment as an evaluation criterion:

5. **Phase Alignment**
- Is the agent aligned to a development phase?
- Is that intent clearly signaled in instructions?

This ensures agents are designed with workflow placement in mind, not as generic assistants.

Why this matters:
Phase alignment reduces confusion and prevents agents from overstepping their intended role in a workflow.

Maintain Focus and Practical Size

Agent profiles should be concise and focused. Narrative bloat reduces effectiveness.

The Quality Reviewer explicitly evaluates this:

7. **File Focus & Practical Size**
- Is the instruction set focused and concise?
- Does it minimize redundancy?

It even recommends splitting agents when instructions become too large or unfocused.

Why this matters:
Focused agents are easier to reason about, easier to maintain, and more reliable in practice. Concise instruction sets also improve model comprehension.

Conclusion

Designing effective GitHub Copilot Markdown agents requires the same rigor applied to software design. A strong agent profile clearly defines its mission, constraints, inputs, evaluation criteria, procedures, outputs, and guardrails.

The Quality Reviewer agent demonstrates how these concerns can be encoded directly into an agent profile as executable instruction rather than commentary or just a ‘prompt’. By applying these principles, engineers can build agents that are safer, clearer, and more effective in real development workflows.