t. The implementation follows a strict architecture: frontmatter configuration dictates execution environment, while the Markdown body enforces stepwise logic, guardrails, and output formatting.

Step 1: Define Scope and Storage Location

Prompt files operate in two distinct scopes. Choose based on portability requirements:

• Workspace scope: Store in .github/prompts/ within the repository. Visible only to collaborators cloning the project. Ideal for team-specific conventions.
• User profile scope: Store in the VS Code user data directory. Visible across all repositories opened with that profile. Ideal for personal automation.

On Windows, the user prompt directory resolves to:

%APPDATA%\Code\User\prompts\

On macOS/Linux:

~/Library/Application Support/Code/User/prompts/

The filename directly maps to the slash command. snapshot.prompt.md becomes /snapshot.

Step 2: Configure Execution Environment (Frontmatter)

The YAML frontmatter controls how Copilot routes and executes the prompt. Misconfiguration here is the primary cause of silent failures.

---
description: "Analyze working tree, generate conventional commit, and create local snapshot"
name: snapshot
agent: agent
model: Claude Sonnet 4.6
tools: ['git/status', 'git/diff', 'git/commit', 'terminal/run']
argument-hint: "Optional commit scope override"
---

Architecture decisions & rationale:

• agent: agent: Required for tool execution. The ask agent operates in read-only mode and cannot invoke git commands or terminal utilities.
• model: Claude Sonnet 4.6: Pins the inference engine. Without this, Copilot defaults to the last-selected chat model, causing behavioral drift across sessions.
• tools: Explicitly whitelist capabilities. Restricting tools prevents the AI from attempting unsafe operations (e.g., git push, git reset --hard).
• argument-hint: Provides inline documentation for optional parameters, reducing user friction.

Step 3: Draft Procedural Instructions

The Markdown body must read like a state machine. Vague directives produce unpredictable outputs. Use explicit branching, conditional checks, and forbidden action declarations.

## Execution Workflow

1. **Repository Validation**
   - Execute `git rev-parse --show-toplevel`
   - If the command fails, halt execution and report: "Not a valid Git repository."

2. **Staging State Detection**
   - Run `git status --short` and `git diff --cached --stat`
   - Branch logic:
     - If staged files exist: Analyze only `git diff --cached`. Do not modify the index.
     - If working tree is dirty but index is empty: Run `git add -A` to stage all modifications.

3. **Intent Extraction**
   - Parse the selected diff for structural changes, not just line additions.
   - Cross-reference recent chat history for task rationale. Prioritize user-provided context over inferred intent.
   - If the diff contains unrelated modifications (e.g., formatting mixed with feature logic), pause and request user confirmation before proceeding.

4. **Message Construction**
   - Format: `<type>(<scope>): <subject>`
   - Subject rules: Imperative mood, max 72 characters, no trailing punctuation.
   - Body rules: Explain motivation and trade-offs. Wrap at 72 characters. Use bullet points for multi-part changes.
   - Footer rules: Include `BREAKING CHANGE:` or issue references only when applicable.
   - Prohibited: Generic phrases ("update", "fix stuff", "WIP").

5. **Commit Execution**
   - Write the formatted message to a temporary file: `tmp_commit_msg.txt`
   - Execute: `git commit -F tmp_commit_msg.txt`
   - Delete the temporary file immediately after execution.
   - **CRITICAL**: Do not invoke `git push` or any remote synchronization command.

6. **Verification & Reporting**
   - Print the complete commit message inside a fenced code block.
   - Confirm successful local snapshot creation.

Step 4: Test and Iterate

Validate the prompt in an isolated repository before deploying to active projects. Use the VS Code Command Palette (Chat: New Prompt File) to scaffold the artifact, or manually create it in the target directory. Execute via /snapshot in the Chat view. Observe tool invocation logs to verify branching logic and guardrail enforcement.

Pitfall Guide

1. Agent Mode Mismatch

Explanation: Using agent: ask for workflows that require terminal execution or file manipulation. The ask agent lacks tool permissions and will fail silently or request manual intervention. Fix: Always set agent: agent for command-driven workflows. Reserve ask for pure analysis or documentation generation.

2. Model Drift

Explanation: Omitting the model field causes Copilot to inherit the last-used chat model. Different models interpret instructions with varying strictness, leading to inconsistent commit formats or tool usage. Fix: Explicitly pin model: Claude Sonnet 4.6 or model: GPT-4o in the frontmatter. Document the expected model in the description.

3. Implicit Guardrails

Explanation: Relying on the AI to "know not to push" without explicit prohibition. LLMs optimize for task completion and may interpret "commit changes" as including remote synchronization. Fix: Use capitalized, unambiguous directives: **DO NOT PUSH**, **HALT BEFORE REMOTE SYNC**. Place forbidden actions in a dedicated section.

4. Scope Collision

Explanation: Saving a user-level prompt in a workspace directory, or vice versa. This causes visibility mismatches where commands appear in unrelated repositories or disappear in expected contexts. Fix: Audit storage paths before creation. Use workspace scope for team conventions, user scope for personal automation. Enable Settings Sync only for user-level artifacts.

5. Context Overload

Explanation: Instructing the AI to "read chat history" without specifying how to weight it against code diffs. The model may prioritize conversational noise over actual code changes. Fix: Define context precedence: Prefer diff analysis for structural changes. Use chat history only for intent clarification when the diff is ambiguous.

6. CLI Quoting Failures

Explanation: Passing multi-line commit messages directly to git commit -m "...". Newlines and special characters break shell parsing, causing command failures or malformed commits. Fix: Always route multi-line inputs through temporary files (git commit -F <file>). Clean up artifacts immediately after execution.

7. Silent Repository Validation

Explanation: Executing Git commands in non-versioned directories or submodules without pre-checks. This produces stack traces or misleading AI responses. Fix: Always begin with git rev-parse --show-toplevel. Implement explicit error handling: If exit code != 0, halt and explain.

Production Bundle

Action Checklist

• Define execution scope: Choose workspace (.github/prompts/) or user profile (%APPDATA%/Code/User/prompts/) based on sharing requirements.
• Configure frontmatter: Set agent: agent, pin a specific model, and whitelist only necessary tools.
• Implement state validation: Add repository existence checks and staging state detection before any Git operations.
• Enforce explicit guardrails: Document forbidden actions in uppercase. Separate safety rules from execution steps.
• Route multi-line inputs through temp files: Avoid shell quoting issues by using git commit -F instead of -m.
• Test in isolation: Validate the prompt in a throwaway repository before deploying to active codebases.
• Enable Settings Sync: Ensure user-level prompts propagate across development machines without manual copying.

Decision Matrix

Scenario	Recommended Approach	Why	Cost Impact
Team-wide commit conventions	Workspace prompt file	Portable, version-controlled, visible to all contributors	Zero (repository-native)
Personal automation routines	User profile prompt file	Available across all repos, syncs via Settings Sync	Zero (local config)
Always-on coding standards	Custom Instructions	Applies globally without manual invocation	Low (may cause prompt noise)
Complex multi-step pipelines	Agent Skills	Supports scripts, dependencies, and package distribution	Medium (requires gh skill setup)
One-off analysis tasks	Ad-hoc Chat	No persistence required, flexible exploration	High (repetitive effort)

Configuration Template

Copy this structure to bootstrap new prompt files. Replace placeholders with task-specific logic.

---
description: "[Brief task description for autocomplete]"
name: [command-name]
agent: agent
model: Claude Sonnet 4.6
tools: ['git/status', 'git/diff', 'git/commit', 'terminal/run']
argument-hint: "[Optional parameter hint]"
---

## Execution Protocol

1. **Pre-flight Check**
   - Validate environment prerequisites
   - Halt with clear error message if conditions unmet

2. **State Analysis**
   - Inspect current working directory / index
   - Branch logic based on detected state

3. **Intent Resolution**
   - Parse code changes for structural impact
   - Cross-reference user context when ambiguous

4. **Output Generation**
   - Apply strict formatting rules
   - Enforce length limits and tone constraints

5. **Safe Execution**
   - Use temporary files for multi-line inputs
   - Execute commands with explicit flags
   - **DO NOT** perform remote synchronization

6. **Verification**
   - Confirm successful execution
   - Report results in structured format

Quick Start Guide

1. Create the artifact: Open VS Code Command Palette (Ctrl+Shift+P / Cmd+Shift+P), search Chat: New Prompt File, and select User scope.
2. Name the file: Save as snapshot.prompt.md in the prompted directory. The slash command automatically resolves to /snapshot.
3. Paste the template: Insert the frontmatter and execution protocol from the Configuration Template. Customize the branching logic and formatting rules for your workflow.
4. Test execution: Open any Git repository, make local changes, and type /snapshot in the Chat view. Verify that staging detection, message formatting, and commit execution behave as expected.
5. Sync across machines: Navigate to VS Code Settings, enable Settings Sync, and ensure Prompts and Instructions is checked. Your command will propagate automatically to other environments.