Prompt Files and Instructions Files Explained

GitHub Copilot is transforming the way developers write code by acting as an intelligent coding agent directly in your editor. Whether you’re building ASP.NET web applications, working with C#, or reviewing code with your team, Copilot can help automate repetitive tasks, suggest entire functions, and streamline code reviews. In this guide, we’ll explore productivity tips, practical examples, and best practices for setting up instruction files and prompt files in Visual Studio, VS Code, and GitHub.com—making it easy for .NET developers to harness its full potential.

Instruction Files

Do you wish Copilot knew more about your solution and your coding preferences? Instruction Files are here to help.

What are Instruction Files?

• Instruction files (often named copilot-instructions.md) define the rules, coding standards, or guidelines Copilot should follow when generating code in your repository or workspace.
• You can create a generic custom instructions file that is used for every request (copilot-instructions.md) and you can create instructions specific to certain scenarios (title.instructions.md) that are applied only to applicable requests.
• Learn more about custom instructions.

When to Use Instruction Files

• Use instruction files in team projects to ensure Copilot suggests code that aligns with your organization’s standards and naming conventions.
• Great for open-source repositories where contributors might benefit from automated adherence to project-specific rules.

How to Use Instruction Files

• Write your instructions file starting with a sample, from scratch, or using Copilot.
• Place your copilot-instructions.md file in the .github folder in your workspace. Place your file type specific instructions that only apply to .cs files or .razor files in your .github/instructions folder.
• Copilot will automatically include the appropriate instructions files with each request sent via the chat.

What to include in Instruction Files

• Purpose & scope: One sentence saying what this instruction file controls (e.g., “Guides automated assistants on safe repo edits and conventions for the Blazor UI”).
• Location & scope rules: Where the file applies (paths, languages, file globs) and any cases it does NOT apply to.
• Project overview: Short intent of the project (audience, main features, runtime/platform).
• Tooling & versions: Exact commands and versions (e.g., .NET 8.0, dotnet command examples, Node, Python, SDKs).
• Build / run / test commands: Minimal, copyable commands for dev and CI (PowerShell-friendly examples on Windows).
• Coding conventions & linting: Formatter (e.g., dotnet format, prettier), style rules, naming patterns, Single Source of Truth for style.
• API & data contracts: JSON shapes, DTO examples, DB schemas or important fields (avoid secrets).
• Tests & E2E expectations: Which tests must pass before changes are accepted.
• CI/CD & release rules: Branching model, required checks, versioning policy, deployment constraints.
• Security & secrets policy: What must never be checked in, env var naming, secret storage guidance.
• Allowed edits & risk tolerance: What the assistant can change autonomously (typo fixes, formatting, tests) vs what requires reviewer/PR (schema changes, DB migrations, infra).
• Output format & diffs: How to present code changes (patch format, single-file edits vs multi-file), commit message style, PR description template.
• Behavior & tone: Preferred assistant persona (concise, conservative, test-first), verbosity and what to ask the human about.
• Failures & rollback: How to handle failing builds or tests, revert instructions, and who to notify.
• Examples & snippets: Good examples of small accepted PRs and disallowed changes.
• Maintenance notes: Where to update this doc and how often.

For more samples of instruction files, check out the many community-submitted examples at awesome-copilot/instructions.

Prompt Files

Do you use Copilot to perform similar tasks on your repo? Do you wish Copilot knew better what it was allowed to change and what not? Prompt Files are here to help.

What are Prompt Files

• Prompt files provide context for Copilot in a specific coding session or for a particular file. They can be added as context or dedicated prompt files to steer the AI’s output for a given task.

When to Use Prompt Files

• Use prompt files when you need Copilot to generate code following specific requirements, such as for custom algorithms, integrations, or compliance needs.
• Ideal for prototyping, documentation, or when onboarding new team members who need explicit guidance.

How to Use Prompt Files

• Write the prompt starting with a sample, from scratch, or with the help of Copilot.
• Place it in the .github/prompts folder in your workspace with the filename format [promptname].prompt.md, for example CreateAnalyzer.prompt.md.
• In VS Code, type /[promptName] in the chat to use it, and in VS, type #[promptName] in the chat to use it. For example, to create an analyzer that checks for weak hashing techniques using my CreateAnalyzer prompt, I would type “/CreateAnalyzer detect usage of MD5.Create(), SHA1.Create(), RijndaelManaged with insecure modes, new HMACSHA1(), or TripleDES and suggest using SHA256 or RandomNumberGenerator and point to library wrappers”.

What to include in Prompt Files

• Header / Metadata
  • Name, version, last-updated, author/maintainer contact.
  • Scope globs (what paths / languages / components the prompt controls).
• Purpose / One-line summary
  • Short statement of intent (what this prompt enables the assistant to do).
• Persona & tone
  • How the assistant should speak (concise, conservative, ask clarifying Qs).
• Allowed autonomous actions
  • Precise list (typo fixes, docs updates, single-file refactors with tests, formatting).
  • Include limits (e.g., max files changed, no infra changes).
• Disallowed actions / require human review
  • DB schema/migrations, secrets, production config, large refactors, major dependency upgrades.
• Build / Run / Test commands
  • Exact commands and environment notes (PowerShell examples for Windows workspaces).
  • Minimum smoke-check commands the assistant should run locally before proposing a change.
• Lint/format commands
  • Tools and invocation (e.g., dotnet format, prettier –check).
• CI rules & PR acceptance criteria
  • Must-pass checks, required labels, tests to run, PR title/body template.
• File & path exceptions
  • List binary, generated, or vendor files that must not be changed.
• Output format & patch conventions
  • Patch/PR format, commit message style, testing evidence to include.
• Error handling & rollback
  • What to do if tests fail, how to revert, who to notify.
• Examples
  • 2–3 short “good” and “bad” examples of edits the assistant might make.
• Minimal machine-ready snippet (optional)
  • YAML or front-matter with apply-to globs, sdk versions so automation can parse it.
• Maintenance notes
  • Who updates this file, and when to bump the version.

For samples of prompt files, check out the many community-submitted examples at awesome-copilot/prompts.

Choosing Between Instruction and Prompt Files

• Instruction Files: Best for repository-wide guidance and long-term standards across multiple contributors and projects.
• Prompt Files: Best for local, session-based guidance or for specific functionality in a single file or segment.
• Combine Both: For maximum results, use instruction files for your overall project and supplement with prompt files in areas that need extra clarity or specificity.

Best Practices: Effective Prompt Writing and Collaboration

• Be specific with prompts and instructions—clarity yields better suggestions.
• Review all AI-generated code for accuracy, security, and compliance.
• Use instruction files for consistency and prompt files for targeted guidance.
• Check out the documentation at Customize chat to your workflow.
• Share Copilot’s outputs in code reviews for collaborative improvement.

Conclusion: Experiment, Guide, and Collaborate with Copilot

GitHub Copilot can supercharge your .NET projects when guided with clear instructions and prompts. By exploring Copilot’s many ways of helping you achieve more, you’ll maximize both productivity and code quality. Explore, refine, and share your Copilot experiences with the developer community!

The post Prompt Files and Instructions Files Explained appeared first on .NET Blog.