Agent Creator

Agent Creator

Create effective .agent.md files for VS Code's chat agent system. Agents are specialized personas that combine domain expertise with structured workflows and tool usage.

Before Creating an Agent

Fetch Latest Best Practices

Before writing or overhauling any agent, fetch the latest agentic design best practices from Anthropic:

1. Use fetch_webpage or mcp_fetch_fetch to retrieve: https://anthropic.com/research/building-effective-agents
2. Extract key principles relevant to the agent being created
3. Apply those principles throughout the agent design

If the URL is unreachable, fall back to the embedded principles below.

Embedded Agentic Design Principles (Fallback)

These are core principles from Anthropic's "Building Effective Agents" research:

• Keep it simple — start with the simplest solution that works. Add complexity only when measured need exists.
• Transparency over autonomy — show the reasoning chain. Agents should explain what they do and why.
• Well-documented tool interfaces — describe tools precisely so the agent knows when and how to use each one.
• Structured workflows over free-form — use prompt chaining, routing tables, and sequential steps rather than open-ended instructions.
• Augmented LLM pattern — combine retrieval (codebase search, MCP tools), context (domain knowledge), and tools (terminal, file editing) into a cohesive workflow.
• Orchestrator-worker — for complex tasks, break into subtasks with clear inputs/outputs per step.
• Evaluator-optimizer — when quality matters, build in a review/verify step at the end of the workflow.

Agent File Format

Frontmatter (YAML)

---
name: 'Agent Name'
description: One-sentence description of expertise, capabilities, and domain knowledge.
---

Rules:

• name — short, human-readable (e.g., MongoDB Expert, Debug Expert)
• description — concise but comprehensive; this is the trigger mechanism that determines when the agent is invoked. Include what the agent does AND what it knows.
• No other fields in frontmatter (no tools:, no license:)

Body Structure

Follow this skeleton. Omit sections that don't apply, but preserve the order:

{One-line mission statement in imperative voice}

When invoked:
- {4-6 bullet points describing key behaviors}

# Prerequisites                    ← optional, for MCP/tool-dependent agents

- {Tool/connection requirements}
- {Fallback behavior if tools unavailable}

# {Main Workflow}                  ← the core sequential process

## Step 1: {Verb phrase}
## Step 2: {Verb phrase}
## Step 3: {Verb phrase}
...

# {Domain Knowledge}               ← environment-specific conventions, patterns

## {Sub-section}
## {Sub-section}

# {General Best Practices}         ← universal domain knowledge

# Anti-Patterns                    ← table format

| Anti-Pattern | Why It's Wrong | Fix |
|---|---|---|
| ... | ... | ... |

# Important Rules                 ← final section, always last

- {Bullet list of hard constraints}

Writing Style Rules

• Imperative voice throughout — "Analyze the query", not "You should analyze the query"
• No "You are a..." preamble in the mission statement — write it as a direct command
• Tables for structured data (categories, patterns, configurations, anti-patterns)
• Code blocks for examples, commands, and configuration snippets
• Bullet lists for rules, constraints, and checklists
• No passive voice — "Check the index" not "The index should be checked"
• Concise — every line must justify its token cost. Challenge: "Does the agent really need this?"

Structural Patterns

Mission Statement (Line 1 after frontmatter)

One sentence describing what the agent does. Imperative, active voice.

Good:

Analyze, optimize, and troubleshoot MongoDB usage across .NET services.

Bad:

You are a MongoDB performance optimization specialist who helps users...

"When invoked" Block

4-6 bullets describing the agent's key behaviors. Start each with a verb.

When invoked:
- Diagnose performance problems by correlating queries with cluster metrics
- Review schema design, index coverage, and aggregation pipelines
- Use MCP tools in readonly mode to inspect live cluster state
- Provide concrete before/after comparisons backed by data

Prerequisites Section

Only for agents that depend on external tools (MCP servers, extensions). Include fallback behavior.

# Prerequisites

- MongoDB MCP Server connected to the target cluster in **readonly mode**
- Atlas credentials on an M10+ cluster recommended for Performance Advisor access

Verify MCP connectivity first. If tools unavailable, report the gap and focus on codebase-only analysis.

Workflow Steps

Sequential numbered steps with clear verbs. Use "Follow these steps in order" as the introductory line.

Each step should:

• Have a clear verb-phrase heading (## Step 1: Gather Evidence)
• List specific actions (numbered or bulleted)
• Reference concrete tools or commands where applicable
• State what to produce before moving to the next step

Domain Knowledge Sections

Use tables for structured reference data. Include code examples where patterns are non-obvious.

Convention tables:

| Collection | Type | Purpose |
|---|---|---|
| `{Entity}_snapshots` | `Snapshot` | Current entity state |

Configuration tables:

| Class | Key Properties |
|---|---|
| `SqlChangeTrackerConfiguration` | `StoredProcedure`, `CronSchedule`, ... |

Anti-Patterns Table

Always use the 3-column format: Anti-Pattern | Why It's Wrong | Fix

Target 8-12 entries. Each entry should be concrete and actionable.

Important Rules Section

Final section. 5-8 hard constraints as bullet points. Include:

• Operating mode constraints (readonly, no modifications)
• Quality requirements (data-backed recommendations)
• Scope boundaries (what the agent should NOT do)

Sizing Guidelines

Exceeding 400 lines signals the agent should be split or content moved to a skill.

Creation Process

1. Clarify scope — determine what the agent does and does NOT do
2. Fetch best practices — retrieve https://anthropic.com/research/building-effective-agents
3. Research the domain — search the codebase, ADO repos, and wikis for environment-specific patterns
4. Draft the agent — follow the body structure skeleton above
5. Review — verify imperative style, no passive voice, no redundancy, appropriate line count
6. Optimize — remove anything the LLM already knows; keep only non-obvious, project-specific knowledge

Common Mistakes to Avoid

• Too generic — an agent that just says "you are an expert in X" adds no value. Include specific workflows, tables, code patterns.
• Too long — context window is shared. If it exceeds 400 lines, extract domain knowledge into a skill.
• Missing workflow — agents without a structured step-by-step process produce inconsistent results.
• Duplicating LLM knowledge — don't teach the agent general programming. Focus on project-specific conventions and environment details.
• Missing anti-patterns — agents that only say what TO do are less effective than agents that also say what NOT to do.
• No scope boundary — always define what the agent should NOT handle (e.g., "DBA territory", "not server administration").
• Passive voice — undermines the imperative style and wastes tokens.
• tools: in frontmatter — VS Code agent format does not support tool declarations in frontmatter. Remove if present.