| name | tsh-creating-prompts |
| description | Create custom prompt files (.prompt.md) for GitHub Copilot in VS Code. Provides templates, guidelines, and a structured process for building prompt files that trigger specific workflows routed to the right custom agent, with model selection inferred from that agent. Use when creating, reviewing, or updating .prompt.md files. |
| user-invocable | false |
Creating Prompts
Creates well-structured custom prompt files for GitHub Copilot in VS Code. Enforces a consistent pattern across all prompts and ensures clear separation between prompt files, agent definitions, and skills.
Core Design Principles
A prompt file (.prompt.md) defines WHAT workflow to execute. It must NOT define WHO the agent is.
- Prompt = workflow trigger, workflow steps, tool configuration, expected outcome
- Agent = behavior, personality, responsibilities, and problem-solving approach (.agent.md files)
- Skills = reusable domain knowledge, step-by-step processes, templates (SKILL.md files)
A prompt routes work to an agent and configures the workflow context. The agent's role, personality, and behavioral guidelines are defined exclusively in the agent file. The prompt must never redefine, override, or contradict the agent's identity.
A prompt file is a **workflow trigger**. It must:
- Route to a specific custom agent via the
agent frontmatter field
- Let the selected agent determine the model; public prompts omit prompt-level model selection
- Describe the workflow steps the agent should follow for this specific task
- Define the expected outcome of the workflow
- Optionally configure tools (MCP servers, built-in tools) available for the workflow
A prompt must NOT:
- Define or alter the agent's personality, tone, or behavioral traits
- Duplicate instructions that belong in skills
- Duplicate coding standards or guidelines that belong in
.instructions.md files
- Contain generic instructions that are not specific to the workflow
All structured content inside the prompt body MUST use XML-like tags for explicit structure. This ensures reliable parsing across all LLM model tiers.
Use Markdown only for inline formatting (bold, code blocks, tables, lists) within XML sections.
A prompt should only describe what is necessary for the specific workflow it triggers. Delegate domain knowledge to skills, coding standards to instructions, and behavioral guidelines to agents.
Creation Process
Use the checklist below and track your progress:
Creation progress:
- [ ] Step 1: Define the prompt's purpose
- [ ] Step 2: Choose the target agent
- [ ] Step 3: Determine tool requirements
- [ ] Step 4: Identify required skills
- [ ] Step 5: Design the workflow steps
- [ ] Step 6: Define output expectations
- [ ] Step 7: Assemble the prompt file using the template
- [ ] Step 8: Validate the prompt file
Step 1: Define the prompt's purpose
Answer these questions before writing anything:
- What specific workflow does this prompt trigger? (e.g., research a task, implement a feature, run e2e tests)
- What is the expected outcome? (e.g., a research document, implemented code, test suite)
- What inputs does the workflow require? (e.g., Jira ID, plan file, feature description)
- Does this prompt extend or depend on another prompt?
- What makes this workflow distinct from existing prompts?
Step 2: Choose the target agent
Select the agent best suited for the workflow:
- Review existing agents in
.github/agents/ to find the one whose role aligns with the workflow
- Choose the agent based on its specialization — the prompt should not need to redefine the agent's capabilities
- The
agent field controls which agent runs the prompt and provides the model selection; public prompts must not declare a prompt-level model
Step 3: Determine tool requirements
Decide if the prompt needs tools beyond the agent's defaults:
- If the workflow requires specific MCP servers (e.g.,
figma/*, atlassian/*), list them in the tools frontmatter
- If the workflow only needs the agent's default tools, omit the
tools field entirely
- Remember: prompt-level tools take priority over agent-level tools (see VS Code docs on tool list priority)
- Use the
<server-name>/* format to include all tools from an MCP server
Step 4: Identify required skills
Determine which skills the workflow depends on:
- Review existing skills in
.github/skills/ to find relevant ones
- Each referenced skill will be loaded by the agent before starting the workflow
- List skills with a brief explanation of why they are needed for THIS workflow
- Do not reference skills that are not directly used in the workflow steps
Step 5: Design the workflow steps
Outline the workflow as a numbered sequence:
- Each step should be a clear, actionable instruction
- Steps should reference skills and tools where appropriate
- Include decision points and branching logic if the workflow is not purely linear
- Include automatic handoffs to other agents if the workflow spans multiple specializations
- Keep steps focused on WHAT to do, not HOW to think about it (the agent's personality handles the how)
Step 6: Define output expectations
Specify the expected deliverables of the workflow:
- File name conventions and output locations
- Document structure or template to follow (reference skill templates where applicable)
- Summary format if the workflow produces a report
- Success criteria — how to know the workflow is complete
- This step is optional if the workflow outcome is self-evident (e.g., implemented code)
Step 7: Assemble the prompt file using the template
Use the ./prompt.template.md template to assemble the final .prompt.md file. Place the file in .github/prompts/ with a descriptive kebab-case filename (e.g., research.prompt.md, implement-ui.prompt.md).
Step 8: Validate the prompt file
Verify the prompt file against this checklist:
Prompt File Structure Reference
Frontmatter Fields
| Field | Required | Description |
|---|
agent | Yes | The custom agent used for running the prompt. Must match an agent filename in .github/agents/ (without the .agent.md suffix). If omitted, the current agent in chat is used. |
description | Yes | A short description of what the prompt does. Shown in the / menu. |
name | No | Override display name shown in the / menu instead of the filename. |
argument-hint | No | Hint text shown in the chat input field to guide the user on what to provide (e.g., [Jira ID or task description]). |
tools | No | A list of tool or tool set names available for this prompt. Overrides agent defaults. Use <server-name>/* for all MCP server tools. |
* Technically optional per VS Code, but agent is required by convention in this project; public prompts infer model selection from the selected agent and omit prompt-level model metadata.
Body Sections
| Section | Required | Purpose |
|---|
| Goal statement | Yes | 1-2 paragraphs describing what the prompt accomplishes and the expected outcome. |
<prerequisites> | No | Dependencies on other prompts or files that must be completed first. |
<input-requirements> | No | Describes what context or inputs the workflow needs to start. |
| Required Skills | Yes | Skills to load before starting the workflow, with brief rationale for each. |
| Workflow | Yes | Numbered steps defining the workflow sequence. |
<output-specification> | No | File naming, document structure, summary format, or success criteria. |
<handoff> | No | Automatic handoff to another agent at the end of the workflow. |
<constraints> | No | Workflow-specific limitations, anti-patterns, or scope boundaries. |
XML Syntax Guidelines
All body content in the prompt file must use XML-like tags for structure. Rules:
- Every section uses a matching opening and closing tag:
<section-name> ... </section-name>
- Tags use lowercase-kebab-case naming
- Nesting is allowed for sub-sections
- Markdown formatting (bold, lists, tables, code blocks) is used inside XML tags for content
- Avoid XML attributes for structural content — use nested tags or Markdown content instead. Exception: identifier attributes (e.g.,
<tool name="...">) are acceptable when they improve readability.
Variables Reference
Prompt files support variables that are resolved at runtime. Use them to make prompts more flexible:
| Variable | Description |
|---|
${workspaceFolder} | Absolute path to the workspace root |
${workspaceFolderBasename} | Name of the workspace folder |
${file} | Path to the currently open file |
${fileBasename} | Filename of the currently open file |
${fileDirname} | Directory of the currently open file |
${fileBasenameNoExtension} | Filename without extension |
${selection} / ${selectedText} | Currently selected text in the editor |
${input:variableName} | Prompts user for text input at runtime |
${input:variableName:placeholder} | User input with placeholder hint |
Variables are useful for prompts that operate on dynamic context (e.g., the current file, user-provided identifiers).
Connected Skills
tsh-creating-agents - to understand agent patterns and ensure prompts don't overlap with agent responsibilitiestsh-creating-skills - to ensure this skill's own structure follows the canonical skill creation requirementstsh-technical-context-discovering - to understand existing prompt patterns and project conventions before creating a new onetsh-codebase-analysing - to analyze existing prompts and identify patterns to followtsh-creating-instructions - to understand when coding standards belong in instruction files rather than prompt definitions
