tsh-creating-prompts

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:

• YAML frontmatter is valid and parseable
• agent field references an existing agent in .github/agents/
• Public prompt frontmatter omits the prompt-level model field and relies on agent for model inference
• description field is present and concise
• tools field (if present) lists only tools needed beyond agent defaults
• All skills referenced in Required Skills section exist in .github/skills/
• XML-like tags are properly opened and closed
• No agent personality or behavioral instructions are embedded (those belong in .agent.md)
• No coding standards or guidelines are embedded (those belong in .instructions.md)
• No skill content is duplicated (reference skills, don't copy them)
• Workflow steps are clear, sequential, and actionable
• The prompt is distinct from existing prompts and does not duplicate their workflows
• If the prompt extends another prompt, the dependency is explicitly stated

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:

1. Every section uses a matching opening and closing tag: <section-name> ... </section-name>
2. Tags use lowercase-kebab-case naming
3. Nesting is allowed for sub-sections
4. Markdown formatting (bold, lists, tables, code blocks) is used inside XML tags for content
5. 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 responsibilities
• tsh-creating-skills - to ensure this skill's own structure follows the canonical skill creation requirements
• tsh-technical-context-discovering - to understand existing prompt patterns and project conventions before creating a new one
• tsh-codebase-analysing - to analyze existing prompts and identify patterns to follow
• tsh-creating-instructions - to understand when coding standards belong in instruction files rather than prompt definitions