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

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 file containing metadata and instructions, plus optional subdirectories for scripts, references, and assets.

According to the source code in docs/customization/skills.md, a skill folder structure looks like this:

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

The SKILL.md file uses YAML front-matter to define the skill's activation profile:

---
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 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 (lines 41-49), this works through three tiers:

1. Metadata tier (~100 tokens): Copilot reads only the name and description from 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 file:

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

The SKILL.md must include front-matter defining the skill's activation profile:

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

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:

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

Analyzing skill quality:

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

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

Refactoring overlapping skills:

/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, 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 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 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.

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