# How Skills Work in HVE Core and When to Use Them Over Instructions

> Discover how HVE Core skills function as on-demand knowledge packages. Learn when to leverage skills over instructions for efficient domain-specific expertise.

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

---

**Skills in HVE Core are self-contained knowledge packages that load on-demand via a three-level disclosure model, making them ideal for domain-specific expertise and large reference materials that would overwhelm the context window if always active.**

In the `microsoft/hve-core` repository, skills provide a structured way to inject specialized knowledge into Copilot only when relevant. Unlike instructions, which remain constantly loaded for every file change, skills activate selectively based on the `copilot-skill:` URI scheme and metadata matching, preserving token budget for complex, reference-heavy workflows.

## What Are Skills in HVE Core?

Skills are modular knowledge units stored as folders within your repository, typically under `.github/skills/`. Each skill requires a mandatory [`SKILL.md`](https://github.com/microsoft/hve-core/blob/main/SKILL.md) file containing metadata and instructions, plus optional subdirectories for scripts, references, and assets.

According to the source code in [`docs/customization/skills.md`](https://github.com/microsoft/hve-core/blob/main/docs/customization/skills.md), a skill folder structure looks like this:

```text
.github/skills/
└── contoso/
    └── api-review/
        ├── SKILL.md          ← metadata + instructions
        ├── scripts/
        │   └── validate-openapi.sh
        └── references/
            └── api-schema.json

```

The [`SKILL.md`](https://github.com/microsoft/hve-core/blob/main/SKILL.md) file uses YAML front-matter to define the skill's activation profile:

```yaml
---
name: API Review
description: Reviews API designs against Contoso's REST conventions and validates OpenAPI specs.
---

```

## Skills vs. Instructions: Key Differences

Understanding when to use skills in HVE Core instead of instructions requires comparing their architectural approaches:

| Aspect | Instructions | Skills |
|--------|--------------|--------|
| **Activation** | Loaded automatically for every relevant file change | Loaded only when Copilot detects a matching domain request via `copilot-skill:` URI |
| **Scope** | Best for coding conventions, lint rules, or short guidance affecting all edits | Ideal for domain-specific, reference-heavy, or large knowledge bodies |
| **Structure** | Single Markdown file with optional front-matter | Folder with mandatory [`SKILL.md`](https://github.com/microsoft/hve-core/blob/main/SKILL.md) plus optional `scripts/`, `references/`, `assets/` |
| **Context footprint** | Entire content always in model context | Three-level disclosure: metadata (~100 tokens) → instructions (<5,000 tokens) → resources (on-demand) |

As implemented in `microsoft/hve-core`, instructions suit lightweight, always-relevant guidance like naming conventions or onboarding tips. Skills excel when knowledge is too large for constant loading or only relevant to specific tasks.

## How Skills Work: The Three-Level Disclosure Model

The HVE Core skills architecture uses progressive disclosure to manage token budgets efficiently. According to [`docs/customization/skills.md`](https://github.com/microsoft/hve-core/blob/main/docs/customization/skills.md) (lines 41-49), this works through three tiers:

1. **Metadata tier (~100 tokens)**: Copilot reads only the `name` and `description` from [`SKILL.md`](https://github.com/microsoft/hve-core/blob/main/SKILL.md) front-matter to determine relevance.
2. **Instructions tier (<5,000 tokens)**: If the description matches the user's vocabulary, Copilot loads the full body of the skill.
3. **Resources tier (on-demand)**: Any files referenced in `scripts/`, `references/`, or `assets/` are fetched only when explicitly called by the loaded instructions.

This architectural flow ensures that large reference materials—such as API schemas or compliance checklists—never consume context window space unless actively needed.

## When to Use Skills Instead of Instructions

Choose skills in HVE Core over instructions when your knowledge management needs meet these criteria:

- **Domain-specific expertise**: API-review standards, compliance checklists, or incident-response runbooks that only apply to certain workflows.
- **Heavy reference material**: Large schemas, regulatory documents, or sample data that would overwhelm the prompt if always loaded.
- **Reuse across agents**: Multiple agents or prompts need identical knowledge (e.g., a "security-review" skill used by both PR-review and documentation-audit agents).
- **Size constraints**: The knowledge body exceeds a few thousand tokens; keeping it as a skill avoids exceeding the model's context window.

Conversely, use **instructions** for lightweight, always-relevant guidance such as naming conventions, file-level linting rules, or onboarding tips that should be visible on every edit.

## How to Create and Reference Skills in HVE Core

### Creating a Skill

To create a skill in `microsoft/hve-core`, establish a folder structure with the mandatory [`SKILL.md`](https://github.com/microsoft/hve-core/blob/main/SKILL.md) file:

```text
.github/skills/contoso/api-review/
├── SKILL.md
├── scripts/
│   └── validate-openapi.sh
└── references/
    └── api-schema.json

```

The [`SKILL.md`](https://github.com/microsoft/hve-core/blob/main/SKILL.md) must include front-matter defining the skill's activation profile:

```yaml
---
name: API Review
description: Reviews API designs against Contoso's REST conventions and validates OpenAPI specs.
---

```

### Referencing Skills

Invoke a skill using the `copilot-skill:` URI scheme in prompts or agent configurations:

```markdown
When a developer asks for help with an API design, include the skill:

`copilot-skill:/api-review/SKILL.md`

```

Copilot reads the front-matter first; if the request matches the description, it loads the full skill body.

### Managing Skills with Prompt Builder

Use the prompt builder commands to create, analyze, and refactor skills:

**Creating or updating a skill from a template:**

```text
/prompt-build files=.github/skills/shared/pr-reference/SKILL.md \
               promptFiles=.github/skills/contoso/api-review/SKILL.md

```

**Analyzing skill quality:**

```text
/prompt-analyze promptFiles=.github/skills/contoso/api-review/SKILL.md

```

This evaluates description clarity, instruction structure, and reference organization.

**Refactoring overlapping skills:**

```text
/prompt-refactor promptFiles=.github/skills/contoso/*/SKILL.md \
                requirements="consolidate overlapping compliance skills into a unified package"

```

### Validating Skills

The repository includes CI validation through [`.github/workflows/skill-validation.yml`](https://github.com/microsoft/hve-core/blob/main/.github/workflows/skill-validation.yml), which runs `scripts/linting/Validate-SkillStructure.ps1` to ensure skill folders meet the required schema and front-matter standards.

## Summary

- **Skills in HVE Core** are on-demand knowledge packages activated via the `copilot-skill:` URI scheme, distinct from always-on instructions.
- They use a **three-level disclosure model** (metadata → instructions → resources) to manage token budgets efficiently.
- **Use skills** for domain-specific expertise, heavy reference materials, reusable knowledge across agents, or when content exceeds a few thousand tokens.
- **Use instructions** for lightweight, universal guidance like naming conventions or linting rules.
- Skills require a specific folder structure with a mandatory [`SKILL.md`](https://github.com/microsoft/hve-core/blob/main/SKILL.md) file and optional `scripts/`, `references/`, or `assets/` subdirectories.

## Frequently Asked Questions

### What is the difference between skills and agents in HVE Core?

**Skills** are passive knowledge repositories that Copilot loads when relevant to a specific request, while **agents** are interactive workflows that execute multi-step processes. According to the HVE Core documentation, skills provide the "what" (knowledge content), whereas agents provide the "how" (orchestrated actions). You can reference skills within agents, but skills themselves do not trigger automated workflows.

### How does Copilot decide when to load a skill versus an instruction?

Copilot loads **instructions** automatically for every relevant file change because they are lightweight and always applicable. For **skills**, Copilot performs a metadata scan first, reading only the `name` and `description` fields from [`SKILL.md`](https://github.com/microsoft/hve-core/blob/main/SKILL.md) front-matter (approximately 100 tokens). If the user's request vocabulary matches the skill description, Copilot loads the full skill body. This selective activation prevents large knowledge bases from consuming context window space during unrelated tasks.

### Can I convert existing instructions into skills in HVE Core?

Yes, you can refactor instructions into skills when they grow too large or become too domain-specific for universal application. Use the `/prompt-refactor` command with the `promptFiles` parameter pointing to your existing instruction files and the `requirements` parameter specifying your consolidation goals. For example: `/prompt-refactor promptFiles=.github/instructions/*.md requirements="convert API-specific guidance into a reusable skill"`. The validation script `scripts/linting/Validate-SkillStructure.ps1` will then verify that your new skill meets the required folder structure and front-matter schema.