Skip to content

Update to latest standard for prompt writing #549

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
codemillmatt merged 4 commits into from
Jan 9, 2026
Merged

Update to latest standard for prompt writing #549

Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
36d550b
Update to latest standard for prompt writing
yeelam-gordon Jan 8, 2026
fc16945
Update instructions/prompt.instructions.md
yeelam-gordon Jan 8, 2026
35a690f
Update instructions/prompt.instructions.md
yeelam-gordon Jan 8, 2026
dadec85
Merge branch 'main' into update-prompt-instructions
codemillmatt Jan 9, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
23 changes: 19 additions & 4 deletions instructions/prompt.instructions.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -13,10 +13,25 @@ Instructions for creating effective and maintainable prompt files that guide Git
- Primary references: VS Code documentation on prompt files and organization-specific conventions.

## Frontmatter Requirements
- Include `description` (single sentence, actionable outcome), `mode` (explicitly choose `ask`, `edit`, or `agent`), and `tools` (minimal set of tool bundles required to fulfill the prompt).
- Declare `model` when the prompt depends on a specific capability tier; otherwise inherit the active model.
- Preserve any additional metadata (`language`, `tags`, `visibility`, etc.) required by your organization.
- Use consistent quoting (single quotes recommended) and keep one field per line for readability and version control clarity.

Every prompt file should include YAML frontmatter with the following fields:

### Required/Recommended Fields

| Field | Required | Description |
|-------|----------|-------------|
| `description` | Recommended | A short description of the prompt (single sentence, actionable outcome) |
| `name` | Optional | The name shown after typing `/` in chat. Defaults to filename if not specified |
| `agent` | Recommended | The agent to use: `ask`, `edit`, `agent`, or a custom agent name. Defaults to current agent |
| `model` | Optional | The language model to use. Defaults to the currently selected model |
| `tools` | Optional | List of tool/tool set names available for this prompt |
| `argument-hint` | Optional | Hint text shown in chat input to guide user interaction |

### Guidelines

- Use consistent quoting (single quotes recommended) and keep one field per line for readability and version control clarity
- If `tools` are specified and the current agent is `ask` or `edit`, the default agent becomes `agent`
- Preserve any additional metadata (`language`, `tags`, `visibility`, etc.) required by your organization

## File Naming and Placement
- Use kebab-case filenames ending with `.prompt.md` and store them under `.github/prompts/` unless your workspace standard specifies another directory.
Expand Down