# How to Configure Instruction Files for Copilot Behavior Customization in HVE Core

> Learn to customize Copilot behavior in HVE Core using instruction files. Configure `.instructions.md` files with YAML front-matter to define AI coding rules and generate plugin metadata.

- Repository: [Microsoft/hve-core](https://github.com/microsoft/hve-core)
- Tags: how-to-guide
- Published: 2026-03-09

---

**HVE Core uses VS Code Copilot instruction files ending in [`.instructions.md`](https://github.com/microsoft/hve-core/blob/main/.instructions.md) located under `.github/instructions/` with mandatory YAML front-matter to customize AI coding behavior, which are then compiled into plugin metadata via `npm run plugin:generate` to activate the rules.**

The **microsoft/hve-core** repository implements a structured approach to configure instruction files for Copilot behavior customization in HVE Core. By leveraging specialized markdown files with strict schema validation, developers can enforce coding standards and automate AI-driven workflows. This configuration system relies on YAML front-matter and a plugin generation pipeline to integrate custom rules into the Copilot ecosystem.

## Understanding the Instruction File Hierarchy

### Repository-Wide Priority Rules

The foundation of Copilot customization in HVE Core starts with [`.github/copilot-instructions.md`](https://github.com/microsoft/hve-core/blob/main/.github/copilot-instructions.md). This file defines the highest-priority rules that govern project-wide AI behavior. According to the source code, individual instruction files can override conflicting guidance defined in this generic file, creating a layered configuration system.

### Individual Instruction Files

Specific behavioral guidelines live under the `.github/instructions/` directory hierarchy. Files placed directly under `.github/` are ignored for collection manifests; only those within the `instructions` subdirectory are discovered recursively. The file name (minus the [`.instructions.md`](https://github.com/microsoft/hve-core/blob/main/.instructions.md) suffix) becomes the UI name unless overridden by front-matter.

## Creating Valid Instruction Files

### Required Front-Matter Schema

Every instruction file must begin with a YAML front-matter block conforming to the **Instruction Frontmatter Schema** defined in [`scripts/linting/schemas/instruction-frontmatter.schema.json`](https://github.com/microsoft/hve-core/blob/main/scripts/linting/schemas/instruction-frontmatter.schema.json). The schema requires a non-empty `description` field:

```json
{
  "required": ["description"],
  "properties": {
    "description": {"type":"string"},
    "name": {"type":"string"},
    "applyTo": {"type":"string"}
  }
}

```

### Optional Configuration Fields

Beyond the mandatory description, the schema supports two optional fields:

- **`name`** – An explicit UI label; if omitted, the system uses the file name (e.g., *pull-request*).
- **`applyTo`** – A glob pattern that tells Copilot to automatically apply instructions to matching workspace files, such as `**/*.cs` for all C# files.

## Practical Configuration Examples

### Commit Message Style Guidelines

Create [`.github/instructions/hve-core/commit-message.instructions.md`](https://github.com/microsoft/hve-core/blob/main/.github/instructions/hve-core/commit-message.instructions.md) to enforce commit conventions:

```markdown
--- 
description: "Enforce a consistent commit‑message format for the HVE Core project"
name: "Commit Message Style"
applyTo: "**/*.md"
---

# Commit‑Message Instructions

- The first line must be ≤ 72 characters and start with a capital letter.
- Use the imperative mood (e.g. *Add* instead of *Added*).
- Separate the subject from the body with a blank line.
- Reference related issue numbers with `#<id>` at the end of the body.

```

### Pull Request Description Standards

Define [`.github/instructions/pull-request.instructions.md`](https://github.com/microsoft/hve-core/blob/main/.github/instructions/pull-request.instructions.md) for PR templates:

```markdown
--- 
description: "Guidelines for writing pull‑request descriptions"
applyTo: "**/*.md"
---

# Pull‑Request Instructions

- Summarize the change in 1‑2 sentences.
- Include a **What** and **Why** section.
- Add screenshots or logs when relevant.
- Tag appropriate reviewers using `@`.

```

## Compiling Instructions with Plugin Generation

After creating or modifying instruction files, you must regenerate the plugin metadata. The `npm run plugin:generate` command executes `scripts/plugins/Generate-Plugins.ps1` to discover files recursively under `.github/instructions/` and bake the new metadata into the `plugins/` directory.

Follow these steps to activate your configuration:

1. Create or modify a `<topic>.instructions.md` file under `.github/instructions/`.
2. Add YAML front-matter satisfying the JSON schema with a mandatory `description`.
3. Optionally set `applyTo` to target specific file types.
4. Commit the file to the repository.
5. Run `npm run plugin:generate` to refresh generated metadata.
6. Execute `npm run plugin:validate` to ensure schema compliance.

Without this generation step, Copilot cannot see the new instructions, regardless of file placement or front-matter validity.

## Summary

- **Instruction files** use the [`.instructions.md`](https://github.com/microsoft/hve-core/blob/main/.instructions.md) extension and must reside under `.github/instructions/`.
- **YAML front-matter** is mandatory with a `description` field conforming to the schema in [`scripts/linting/schemas/instruction-frontmatter.schema.json`](https://github.com/microsoft/hve-core/blob/main/scripts/linting/schemas/instruction-frontmatter.schema.json).
- **`applyTo`** glob patterns enable automatic application to specific file types.
- **`npm run plugin:generate`** compiles instruction files into plugin metadata required by Copilot.
- **Priority rules** in [`.github/copilot-instructions.md`](https://github.com/microsoft/hve-core/blob/main/.github/copilot-instructions.md) can be overridden by specific instruction files for granular control.

## Frequently Asked Questions

### What is the required file extension for HVE Core instruction files?

Instruction files must end with [`.instructions.md`](https://github.com/microsoft/hve-core/blob/main/.instructions.md) to be recognized by the plugin generation system. Files lacking this suffix or placed outside `.github/instructions/` are ignored during the discovery process executed by `Generate-Plugins.ps1`.

### How do I apply instruction files to specific file types?

Use the `applyTo` field in the YAML front-matter with a glob pattern. For example, setting `applyTo: "**/*.cs"` automatically applies the instructions to all C# files in the workspace when Copilot generates or updates code.

### What happens if I forget to run the plugin generation step?

Copilot will not recognize new or updated instruction files. The `npm run plugin:generate` command must execute to bake the metadata into the `plugins/` directory and update the collection manifests that Copilot references for behavior customization.

### Can I override repository-wide Copilot instructions?

Yes. Rules defined in individual instruction files under `.github/instructions/` override conflicting guidance from the repository-wide [`.github/copilot-instructions.md`](https://github.com/microsoft/hve-core/blob/main/.github/copilot-instructions.md) file. This allows granular customization while maintaining baseline project standards defined in the priority rules file.