Skip to content

CustomInstructions.md

Latest commit

 

History

History
183 lines (122 loc) · 7.81 KB

CustomInstructions.md

File metadata and controls

183 lines (122 loc) · 7.81 KB

Use custom instructions in GitHub Copilot for Xcode

Custom instructions enable you to define common guidelines and rules that automatically influence how AI generates code and handles other development tasks. Instead of manually including context in every chat prompt, specify custom instructions in a Markdown file to ensure consistent AI responses that align with your coding practices and project requirements.

You can configure custom instructions to apply automatically to all chat requests or to specific files only. Alternatively, you can manually attach custom instructions to a specific chat prompt.

Note

Custom instructions are not taken into account for code completions as you type in the editor.

Type of instructions files

GitHub Copilot for Xcode supports two types of Markdown-based instructions files:

  • A single .github/copilot-instructions.md file

    • Automatically applies to all chat requests in the workspace
    • Stored within the workspace or global

  • One or more .instructions.md files

    • Created for specific tasks or files
    • Use applyTo frontmatter to define what files the instructions should be applied to
    • Stored in the workspace

Whitespace between instructions is ignored, so the instructions can be written as a single paragraph, each on a new line, or separated by blank lines for legibility.

Reference specific context, such as files or URLs, in your instructions by using Markdown links.

Custom instructions examples

The following examples demonstrate how to use custom instructions. For more community-contributed examples, see the Awesome Copilot repository.

Example: General coding guidelines 
---
applyTo: "**"
---
# Project general coding standards

## Naming Conventions
- Use PascalCase for component names, interfaces, and type aliases
- Use camelCase for variables, functions, and methods
- Use ALL_CAPS for constants

## Error Handling
- Use try/catch blocks for async operations
- Always log errors with contextual information
Example: Language-specific coding guidelines

Notice how these instructions reference the general coding guidelines file. You can separate the instructions into multiple files to keep them organized and focused on specific topics.

---
applyTo: "**/*.swift"
---
# Project coding standards for Swift

Apply the [general coding guidelines](./general-coding.instructions.md) to all code.

## Swift Guidelines
- Use Swift for all new code
- Follow functional programming principles where possible
- Use interfaces for data structures and type definitions
- Use optional chaining (?.) and nullish coalescing (??) operators
Example: Documentation writing guidelines

You can create instructions files for different types of tasks, including non-development activities like writing documentation.

---
applyTo: "docs/**/*.md"
---
# Project documentation writing guidelines

## General Guidelines
- Write clear and concise documentation.
- Use consistent terminology and style.
- Include code examples where applicable.

## Grammar
* Use present tense verbs (is, open) instead of past tense (was, opened).
* Write factual statements and direct commands. Avoid hypotheticals like "could" or "would".
* Use active voice where the subject performs the action.
* Write in second person (you) to speak directly to readers.

## Markdown Guidelines
- Use headings to organize content.
- Use bullet points for lists.
- Include links to related resources.
- Use code blocks for code snippets.

Use a .github/copilot-instructions.md file

Define your custom instructions in a single .github/copilot-instructions.md Markdown file in the root of your workspace or globally. Copilot applies the instructions in this file automatically to all chat requests within this workspace.

To create a .github/copilot-instructions.md file:

  1. Open Settings > Advanced > Chat Settings
  2. To the right of "Copilot Instructions", click Current Workspace or Global to choose whether the custom instructions apply to the current workspace or all workspaces.
  3. Describe your instructions by using natural language and in Markdown format.

Note

GitHub Copilot provides cross-platform support for the .github/copilot-instructions.md configuration file. This file is automatically detected and applied in VSCode, Visual Studio, 3rd-party IDEs, and GitHub.com.

  • Workspace instructions files: are only available within the workspace.
  • Global: is available across multiple workspaces and is stored in the preferences.

For more information, you can read the How-to docs.

Use .instructions.md files

Instead of using a single instructions file that applies to all chat requests, you can create multiple .instructions.md files that apply to specific file types or tasks. For example, you can create instructions files for different programming languages, frameworks, or project types.

By using the applyTo frontmatter property in the instructions file header, you can specify a glob pattern to define which files the instructions should be applied to automatically. Instructions files are used when creating or modifying files and are typically not applied for read operations.

Alternatively, you can manually attach an instructions file to a specific chat prompt by using the file picker.

Instructions file format

Instructions files use the .instructions.md extension and have this structure:

  • Header (optional): YAML frontmatter

    • description: Description shown on hover in Chat view
    • applyTo: Glob pattern for automatic application (use ** for all files)

  • Body: Instructions in Markdown format

Example:

---
applyTo: "**/*.swift"
---
# Project coding standards for Swift
- Follow the Swift official guide for Swift.
- Always prioritize readability and clarity.
- Write clear and concise comments for each function.
- Ensure functions have descriptive names and include type hints.
- Maintain proper indentation (use 4 spaces for each level of indentation).

Create an instructions file

  1. Open Settings > Advanced > Chat Settings

  2. To the right of "Custom Instructions", click Create to create a new *.instructions.md file.

  3. Enter a name for your instructions file.

  4. Author the custom instructions by using Markdown formatting.

    Specify the applyTo metadata property in the header to configure when the instructions should be applied automatically. For example, you can specify applyTo: "**/*.swift" to apply the instructions only to Swift files.

    To reference additional workspace files, use Markdown links ([App](../App.swift)).

To modify or view an existing instructions file, click Open Instructions Folder to open the instructions file directory.

Tips for defining custom instructions

  • Keep your instructions short and self-contained. Each instruction should be a single, simple statement. If you need to provide multiple pieces of information, use multiple instructions.

  • For task or language-specific instructions, use multiple *.instructions.md files per topic and apply them selectively by using the applyTo property.

  • Store project-specific instructions in your workspace to share them with other team members and include them in your version control.

  • Reuse and reference instructions files in your prompt files to keep them clean and focused, and to avoid duplicating instructions.

Related content