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

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. 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. 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 file defines the available skill collections.

Create the Folder Structure

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

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

Author the SKILL.md File

The 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.

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 exists, the front-matter is well-formed, and required fields are present. The validation logic is implemented in scripts/linting/Validate-SkillStructure.ps1.

.\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 files and bundles the complete skill folder. This script handles the packaging logic without requiring manual file copying.

.\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:

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

Practical Code Examples

Create a New Skill Skeleton

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

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

Reference the Skill from a Prompt

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

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

Key Files and Their Roles

File	Role
docs/customization/skills.md	Authoring guide, SKILL.md anatomy, Prompt-Builder usage
.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	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 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 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 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 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 file and optional assets that provide specific domain expertise.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}