Create Custom Instruction

Create a Custom Instruction File

Custom instructions define coding standards, conventions, and guidelines that Copilot applies automatically — either to all requests (always-on) or to specific files matching a glob pattern (file-based).

When to Use This Skill

• User asks to create a new .instructions.md file for a specific language, framework, or project area.
• User wants to add or update project-wide coding standards in .github/copilot-instructions.md.
• User wants instructions applied only to certain file types (e.g., **/*.cpp, **/test/**).

File Locations

Directories are searched recursively — group by team/language/module is allowed:

.github/instructions/
  cpp/
    autosar.instructions.md
  android/
    kotlin.instructions.md
  testing/
    unit-tests.instructions.md

File Format

.github/copilot-instructions.md (always-on, no frontmatter)

# Project Coding Standards

- Use C++17. No exceptions in embedded code.
- All public APIs must have Doxygen comments.
- Prefer `std::unique_ptr` over raw pointers.

.instructions.md (file-based, with frontmatter)

---
name: 'C++ Automotive Standards'
description: 'AUTOSAR and MISRA coding conventions for C++ source files'
applyTo: '**/*.{cpp,hpp,c,h}'
---

# C++ Coding Standards

- Use fixed-width integer types: `uint8_t`, `int32_t` — never `int` or `long`.
- Every pointer must be null-checked before dereferencing.
- No `dynamic_cast` in safety-critical paths (AUTOSAR A5-2-3).

Frontmatter Fields

Step-by-Step Workflow

Step 1: Determine scope

• Project-wide rule (all files) → copilot-instructions.md
• Language/framework-specific rule → .instructions.md with applyTo

Step 2: Create the file in the correct location

Step 3: Write the frontmatter (for .instructions.md)

• Set applyTo to the appropriate glob pattern.
• Write description concisely — it helps the AI decide when to apply.

Step 4: Write the instruction body

Follow these guidelines:

• One rule per bullet — short, self-contained statements.
• Include the "why" when non-obvious: "Use date-fns, not moment.js — moment is deprecated and increases bundle size."
• Show code examples for allowed and forbidden patterns.
• Skip what linters already enforce — focus on non-obvious conventions.
• Reference related files using Markdown links rather than duplicating rules.

Instruction Quality Checklist

• Each rule is a single, actionable statement.
• applyTo pattern is correct and minimal (not ** if it should only apply to C++ files).
• Non-obvious rules include rationale.
• Code examples included for complex rules.
• No duplication with existing copilot-instructions.md.

Examples

Language-specific

---
name: 'Kotlin Android Standards'
description: 'Kotlin conventions for Android Automotive app code'
applyTo: '**/*.kt'
---
- Use `StateFlow` instead of `LiveData` for new code.
- Inject dependencies via Hilt — do not use `ServiceLocator`.
- Every `suspend` function must be called from a coroutine scope, never from `GlobalScope`.

Test file rules

---
name: 'Unit Test Standards'
description: 'Conventions for unit test files'
applyTo: '**/{test,tests}/**/*.{cpp,kt,java}'
---
- Test function name format: `GIVEN_<state>_WHEN_<action>_THEN_<expected>`.
- Do not use real filesystem or network in unit tests — mock all I/O.
- Each test must have exactly one logical assertion.

Prerequisites

• VS Code 1.87+ with the GitHub Copilot extension installed.
• A workspace with a .github/ directory at the root.
• Familiarity with glob patterns for the applyTo field.

Troubleshooting

• AI never auto-loads the skill / agent / instruction — verify disable-model-invocation is not true and description contains a clear "Use when ..." trigger phrase.
• Skill / prompt not shown in the / command menu — check that user-invocable is not false and the file is saved to the correct .github/ subdirectory.
• name validator error (FM_NAME_DIR_MISMATCH) — the name frontmatter field must exactly match the directory/file name (case-sensitive, lowercase, hyphens only).
• Companion file not found by the AI — reference files with paths relative to the skill/instruction/prompt file (e.g., ./examples/good.cpp).

References

• VS Code Custom Instructions Docs