# How to Create Custom Skills with Domain-Specific Knowledge Packages in HVE Core

> Learn to build custom skills in HVE Core by creating domain-specific knowledge packages. Discover the three-layer architecture for on-demand skill loading.

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

---

**Custom skills in HVE Core are self-contained knowledge packages that Copilot loads on-demand when requests match the skill's domain, using a three-layer architecture of metadata, instructions, and lazy-loaded resources.**

The `microsoft/hve-core` repository provides a framework for building domain-specific knowledge packages that extend Copilot's capabilities. When you create custom skills with domain-specific knowledge packages, you enable the LLM to access specialized procedures, validation scripts, and reference materials only when relevant to the user's request.

## Understanding the Skill Architecture

HVE Core implements a progressive disclosure pattern that keeps the LLM prompt efficient while providing rich context when needed. The architecture consists of three distinct layers:

### Metadata Layer (~100 tokens)

The metadata layer contains the `name` and `description` fields defined in the YAML front-matter of [`SKILL.md`](https://github.com/microsoft/hve-core/blob/main/SKILL.md). Copilot reads this layer at request-time to determine if the skill is relevant to the current conversation. This layer is always loaded first.

### Instructions Layer (< 5,000 tokens)

The instructions layer comprises the full markdown body of [`SKILL.md`](https://github.com/microsoft/hve-core/blob/main/SKILL.md). This content describes procedures, parameters, and examples. It is loaded only when the metadata layer indicates the skill applies to the current request.

### Resources Layer (On-Demand)

The resources layer includes files in `scripts/`, `references/`, and `assets/` directories. These are pulled in lazily when a specific instruction references them, ensuring the LLM context window contains only actively used materials.

## Step-by-Step Guide to Creating Custom Skills

### Choose a Collection

Skills are organized by collection ID (e.g., `contoso`, `experimental`). The collection manifest (`*.collection.yml`) tells the extension which skills to package. In `microsoft/hve-core`, the [`collections/hve-core.collection.yml`](https://github.com/microsoft/hve-core/blob/main/collections/hve-core.collection.yml) file defines the available skill collections.

### Create the Folder Structure

Create a dedicated folder under `.github/skills/` using your collection ID and skill name:

```text
.github/skills/
└── <collection-id>/
    └── <skill-name>/
        ├── SKILL.md          ← required
        ├── scripts/          ← optional
        └── references/       ← optional

```

### Author the SKILL.md File

The [`SKILL.md`](https://github.com/microsoft/hve-core/blob/main/SKILL.md) file must start with YAML front-matter defining `name` and `description`. The body contains the procedural guide. For example, the `video-to-gif` skill in the experimental collection demonstrates the required structure in [`.github/skills/experimental/video-to-gif/SKILL.md`](https://github.com/microsoft/hve-core/blob/main/.github/skills/experimental/video-to-gif/SKILL.md).

Required front-matter fields include:
- `name`: The display name of the skill
- `description`: A concise summary for the metadata layer

### Add Supporting Assets

Place reusable scripts in `scripts/`, schemas in `references/`, and images in `assets/`. Reference these from the markdown body using relative paths. These assets are loaded only when specifically referenced by the active instructions.

### Validate the Skill Structure

Run the built-in linter to ensure [`SKILL.md`](https://github.com/microsoft/hve-core/blob/main/SKILL.md) exists, the front-matter is well-formed, and required fields are present. The validation logic is implemented in `scripts/linting/Validate-SkillStructure.ps1`.

```powershell
.\scripts\linting\Validate-SkillStructure.ps1 -Path .github/skills/contoso/api-review

```

### Package with the Extension

When building a VS Code extension or Copilot CLI plugin, `Prepare-Extension.ps1` automatically discovers [`SKILL.md`](https://github.com/microsoft/hve-core/blob/main/SKILL.md) files and bundles the complete skill folder. This script handles the packaging logic without requiring manual file copying.

```powershell
.\scripts\extension\Prepare-Extension.ps1 -Root .

```

### Activate and Reference the Skill

Agents or prompts can reference skills using the URI scheme `copilot-skill:`. For example, to invoke the API-review skill:

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

```

## Practical Code Examples

### Create a New Skill Skeleton

```bash
mkdir -p .github/skills/contoso/api-review
cat > .github/skills/contoso/api-review/SKILL.md <<'EOF'
---
name: API Review
description: Reviews OpenAPI specs against Contoso REST conventions.
---

## Review Protocol

1. Validate the OpenAPI spec with `references/api-schema.json`.
2. Enforce naming conventions.
3. Flag breaking changes.

## References

- [API Schema](references/api-schema.json)
- Validation script: `scripts/validate-openapi.sh`
EOF
mkdir -p .github/skills/contoso/api-review/scripts
mkdir -p .github/skills/contoso/api-review/references

```

### Validate the New Skill

```powershell
.\scripts\linting\Validate-SkillStructure.ps1 -Path .github/skills/contoso/api-review

```

### Reference the Skill from a Prompt

```markdown
Please run the API review skill to check the latest spec:

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

```

### Package the Repository as a VS Code Extension

```powershell
.\scripts\extension\Prepare-Extension.ps1 -Root .
.\scripts\extension\Package-Extension.ps1 -ExtensionPath ./extension

```

## Key Files and Their Roles

| File | Role |
|------|------|
| [`docs/customization/skills.md`](https://github.com/microsoft/hve-core/blob/main/docs/customization/skills.md) | Authoring guide, SKILL.md anatomy, Prompt-Builder usage |
| [`.github/skills/experimental/video-to-gif/SKILL.md`](https://github.com/microsoft/hve-core/blob/main/.github/skills/experimental/video-to-gif/SKILL.md) | Real-world skill example (media processing) |
| `scripts/linting/Validate-SkillStructure.ps1` | Validation of skill folder structure & front-matter |
| `scripts/extension/Prepare-Extension.ps1` | Auto-discovers SKILL.md and builds skill objects for packaging |
| `scripts/extension/Package-Extension.ps1` | Copies full skill directories into the VS Code extension bundle |
| [`collections/hve-core.collection.yml`](https://github.com/microsoft/hve-core/blob/main/collections/hve-core.collection.yml) | Collection manifest that includes skill definitions for packaging |

## Summary

- Custom skills in HVE Core are domain-specific knowledge packages stored under `.github/skills/<collection>/<skill>/`.
- Each skill requires a [`SKILL.md`](https://github.com/microsoft/hve-core/blob/main/SKILL.md) file with YAML front-matter (`name`, `description`) and a procedural markdown body.
- The three-layer architecture (metadata, instructions, resources) ensures efficient LLM context usage through progressive disclosure.
- Use `Validate-SkillStructure.ps1` to lint skills and `Prepare-Extension.ps1` to package them for distribution.
- Skills are activated via the `copilot-skill:` URI scheme, enabling on-demand loading by Copilot agents.

## Frequently Asked Questions

### What is the maximum size for a skill's instructions?

The instructions layer in [`SKILL.md`](https://github.com/microsoft/hve-core/blob/main/SKILL.md) should remain under 5,000 tokens. This limit ensures the LLM context window remains available for user queries and conversation history while still providing comprehensive procedural guidance.

### Can I include executable scripts in my custom skill?

Yes. Place executable scripts in the `scripts/` folder within your skill directory. Reference them from [`SKILL.md`](https://github.com/microsoft/hve-core/blob/main/SKILL.md) using relative paths. These resources are loaded on-demand only when the LLM needs to execute or reference the specific script, keeping the initial prompt size minimal.

### How does Copilot decide which skills to load?

Copilot evaluates the metadata layer first, reading only the `name` and `description` fields from the YAML front-matter of each [`SKILL.md`](https://github.com/microsoft/hve-core/blob/main/SKILL.md) file. If this metadata indicates relevance to the current request, Copilot then loads the full instructions and any referenced resources. This two-step filtering prevents irrelevant domain knowledge from consuming context window space.

### What is the difference between a collection and a skill?

A **collection** is a logical grouping of related skills identified by a collection ID (e.g., `contoso`, `experimental`). The collection manifest (`*.collection.yml`) defines which skills are packaged together for distribution. A **skill** is an individual knowledge package within that collection, containing the [`SKILL.md`](https://github.com/microsoft/hve-core/blob/main/SKILL.md) file and optional assets that provide specific domain expertise.