Prompt File Design

Principles for designing high-quality VS Code .prompt.md files — the reusable task templates that define WHAT to deliver without prescribing HOW. Based on official VS Code documentation, GitHub best practices, and the three-layer agentic model.

Core Principle

Prompts are the WHAT layer. They specify context, deliverables, and success criteria. They do NOT contain methodology, constraints, tool instructions, or behavioral rules — those belong in agents and skills.

Structure Reference

---
name: prompt-name                        # Used after typing / in chat
description: VS Code prompt file (.prompt.md) design principles, variable patterns, boundary rules, and quality tests. Use when creating prompt files, designing reusable prompts, or reviewing prompt templates.
agent: "agent-name"                      # Optional: which agent executes
model: "Claude Sonnet 4.5"              # Optional: override default model
tools: ['read', 'search']               # Optional: restrict tools
---

Body Components

Design Rules

1. Agent-Agnostic

Prompts should work with any compatible agent. If a prompt only works with one specific agent, the methodology has leaked.

Test: Can another agent execute this prompt and produce a valid result? → Yes = correct.

2. Variable-Driven

Parameterize via ${input:} instead of creating separate prompt files per variation.

## Context
- **Component**: ${input:name:MyComponent}
- **Framework**: ${input:framework:Vue}
- **Target**: ${file}

3. Reference, Don't Duplicate

Link to standards files instead of copying content:

Follow patterns in [TESTING.md](../../docs/TESTING.md).
Respect conventions in [copilot-instructions.md](../copilot-instructions.md).

4. Deliverable-Focused

Specify WHAT success looks like:

## Deliverable
Generate test file(s) that:
- Cover happy path, error cases, and boundary conditions
- Follow existing test patterns in this project
- Include descriptive test names

## Success Criteria
- All generated tests pass
- No `any` types or `# type: ignore`

5. Size Limit: ≤50 Lines

If a prompt exceeds 50 lines, content is leaking from the agent or skill layer. Extract methodology to the agent, extract reusable knowledge to a skill.

Dual-Runtime Compatibility

Prompt files can serve both VS Code Copilot (via agent: routing) and Claude Code (via .claude/commands/ symlink) from a single source file.

Architecture

.github/prompts/plan.prompt.md    ← Source of truth
       ↓ (read by VS Code)               ↓ (symlinked)
VS Code Copilot agent routing     .claude/commands/ → ../. github/prompts/

Runtime Behavior Matrix

Enrichment Pattern

VS Code prompts that only contain ${input:...} are "thin launchers" — they route to an agent that has the full methodology. Claude Code has no agent routing, so thin prompts produce poor results.

Solution: Enrich the body with a compressed summary of the agent's methodology. This serves as additive reinforcement in VS Code and primary instruction in Claude Code.

---
name: plan
agent: "plan"
description: "Create an implementation plan"
---

${input:request:What would you like to plan?}

## Context

You are an **Implementation Planner**. Create detailed, actionable plans without modifying code.

### Key Rules
- {3-5 agent-specific constraints, not generic project rules}
- Read `docs/DOCUMENTATION-GUIDE.md` to find relevant docs
- Use `make` targets — never raw `npm`, `poetry`, `pip`, or `python` commands

### Methodology
1. **{Phase}** — {compressed description}
2. **{Phase}** — {compressed description}
3. **{Phase}** — {compressed description}

### Output
{What to produce — format expectations}

### Skills
Apply these skills from `.github/skills/`: {skill1}, {skill2}

$ARGUMENTS

Key Principles

1. •Header unchanged — VS Code frontmatter stays exactly as-is
2. •Body = compressed agent — NOT a copy, but enough for standalone operation (~20-30 lines)
3. •Both variable systems present — ${input:...} (VS Code) and $ARGUMENTS (Claude Code) coexist harmlessly
4. •Single source of truth — .github/prompts/ is canonical; .claude/commands/ is a symlink
5. •Still under 50 lines — enriched prompts should stay within the size limit

Symlink Setup

# Directory symlink — zero-maintenance on new prompts
cd .claude && ln -s ../.github/prompts commands

Claude Code invokes as /project:plan.prompt "add auth module". The .prompt suffix in the command name is a cosmetic tradeoff for zero-maintenance directory symlink.

Quality Tests

Apply all four before finalizing any prompt file:

Prompt Types

Routing Prompts (Slash Command Shortcuts)

Minimal prompt files that serve as agent switching shortcuts via the / slash command menu. Solves the UX friction of dropdown navigation when chaining agents in a sequential workflow.

Why routing prompts exist: In VS Code Copilot Chat, agents appear in the chat mode dropdown (click → scroll → select). Prompts appear in the slash command menu (type / → pick). Slash commands are faster for mid-session agent switching, especially in sequential workflows like study → plan → implement.

Pattern:

---
name: {agent-name}
agent: "{agent-name}"
description: VS Code prompt file (.prompt.md) design principles, variable patterns, boundary rules, and quality tests. Use when creating prompt files, designing reusable prompts, or reviewing prompt templates.
---

${input:request:What would you like to {verb}?}

Rules:

• •One routing prompt per user-facing agent (1:1 mapping)
• •~6-7 lines maximum — no context, no deliverable, no references
• •name matches the agent name for discoverability
• •description follows the pattern: "Use {agent} agent to {verb} {object}"
• •Body is a single ${input:request} variable with a helpful placeholder
• •When a new agent is created, create a matching routing prompt

Routing prompts are the exception to the "agent-agnostic" rule — they exist specifically to route to one agent. This is their only purpose.

Task Prompts (Context Templates)

Standard prompt files that carry reusable task context to any compatible agent. These are the primary prompt type described throughout this skill.

Templates

Routing Prompt Template

---
name: {agent-name}
agent: "{agent-name}"
description: VS Code prompt file (.prompt.md) design principles, variable patterns, boundary rules, and quality tests. Use when creating prompt files, designing reusable prompts, or reviewing prompt templates.
---

${input:request:What would you like to {verb}?}

Task Prompt Template

---
name: {prompt-name}
description: VS Code prompt file (.prompt.md) design principles, variable patterns, boundary rules, and quality tests. Use when creating prompt files, designing reusable prompts, or reviewing prompt templates.
---

## Context
- **Target**: ${input:target:default}
- **Scope**: ${input:scope:default}
- **Reference**: ${file}

Follow conventions in [relevant-doc](../../path/to/doc.md).

## Deliverable
{What to produce}:
- {Required element 1}
- {Required element 2}
- {Required element 3}

## Success Criteria
- {Measurable criterion 1}
- {Measurable criterion 2}

Anti-Patterns

Sources

• •VS Code Prompt Files Documentation
• •GitHub Blog — Better Prompts
• •GitHub Copilot Chat Cookbook
• •awesome-copilot