Contributing Skills to HVE Core

This guide defines the requirements, standards, and best practices for contributing skill packages to the hve-core library.

⚙️ Common Standards: See AI Artifacts Common Standards for shared requirements (XML blocks, markdown quality, RFC 2119, validation, testing).

What is a Skill?

A skill is a self-contained package that provides guidance and utilities for specific tasks. Unlike agents or prompts that guide conversation flows, skills bundle documentation, and optionally executable scripts, to perform concrete operations. A skill can be purely documentation-driven (providing structured knowledge and instructions) or can include cross-platform scripts for automated task execution.

Skill vs Agent vs Prompt

Artifact	Purpose	Includes Scripts	User Interaction
Skill	Task execution with utilities	Optional	Minimal after invocation
Agent	Conversational guidance	No	Multi-turn conversation
Prompt	Single-session workflow	No	One-shot execution

Use Cases for Skills

Create a skill when you need to:

Package structured knowledge and instructions for a specific task domain
Bundle documentation with executable scripts for automated task execution
Provide cross-platform utilities (PowerShell required, bash recommended)
Standardize common development tasks
Share reusable tooling across projects

Skills Not Accepted

The following skill types will likely be rejected:

Reason	Details
Duplicate Skills	Skills that replicate functionality of existing tools or skills
Missing PowerShell Scripts	Skills that include a `scripts/` directory without a `.ps1` file (PowerShell is required; bash is recommended)
Undocumented Utilities	Scripts without comprehensive SKILL.md documentation
Untested Skills	Skills that lack unit tests or fail to achieve 80% code coverage

File Structure Requirements

Location

Skill files are typically organized in a collection subdirectory by convention:

.github/skills/{collection-id}/<skill-name>/
├── SKILL.md                    # Main skill definition (required)
├── scripts/                    # Executable scripts (optional)
│   ├── <action>.ps1            # PowerShell script (required)
│   └── <action>.sh             # Bash script (recommended)
├── references/                 # Additional documentation (optional)
│   └── REFERENCE.md            # Detailed technical reference
├── assets/                     # Static resources (optional)
│   └── templates/              # Document or configuration templates
├── examples/
│   └── README.md               # Usage examples (recommended)
└── tests/
    └── <action>.Tests.ps1      # Pester unit tests (required for PowerShell)

NOTE

Collections can reference artifacts from any subfolder. The path: field in collection YAML files accepts any valid repo-relative path regardless of the artifact's parent directory.

The scripts/ directory is optional. When present, it MUST contain at least one .ps1 file and SHOULD contain at least one .sh file for cross-platform support. Skills without scripts are valid and function as documentation-driven knowledge packages.

Naming Convention

Use lowercase kebab-case for directory names: video-to-gif
Main definition file MUST be named SKILL.md
Script names should describe their action: convert.sh, validate.ps1
Only recognized subdirectories are allowed: scripts, references, assets, examples, tests (the tests directory is excluded from extension and CLI outputs)

Frontmatter Requirements

Required Fields

name (string, MANDATORY)

Property	Value
Purpose	Unique identifier for the skill
Format	Lowercase kebab-case matching the directory name
Example	`video-to-gif`

description (string, MANDATORY)

Property	Value
Purpose	Concise explanation of skill functionality
Format	Single sentence ending with attribution
Example	`'Video-to-GIF conversion skill with FFmpeg two-pass optimization - Brought to you by microsoft/hve-core'`

Frontmatter Example

---
name: video-to-gif
description: 'Video-to-GIF conversion skill with FFmpeg two-pass optimization - Brought to you by microsoft/hve-core'
---

Optional Fields

user-invocable (boolean, optional)

Property	Value
Purpose	Controls visibility in the VS Code slash command menu
Default	`true`
When true	Skill appears in the `/` menu for manual invocation via `/skill-name`
When false	Skill does not appear in the `/` menu; loaded only by semantic matching or explicit `#file:` reference
Use case	Set `false` for background skills that support other workflows without direct user invocation

disable-model-invocation (boolean, optional)

Property	Value
Purpose	Controls whether Copilot automatically loads the skill via semantic matching
Default	`false`
When false	Copilot loads the skill automatically when the task description semantically matches the `description` field
When true	Skill is only loaded via manual `/skill-name` slash command invocation
Use case	Set `true` for skills with high token cost or niche applicability that should not load automatically

argument-hint (string, optional)

Property	Value
Purpose	Displays expected inputs in the VS Code prompt picker
Format	Brief text with required arguments first, then optional arguments
Conventions	Use `[]` for positional arguments, `key=value` for named parameters, `{option1\|option2}` for enumerations, `...` for free-form text
Example	`"input=video.mp4 [--fps={5\|10\|15\|24}] [--width=1280]"`

Invocation Control Matrix

`user-invocable`	`disable-model-invocation`	`/` Menu	Semantic Loading	Invocation Method
`true` (default)	`false` (default)	Yes	Yes	Automatic + manual
`true`	`true`	Yes	No	Manual `/skill-name` only
`false`	`false`	No	Yes	Automatic only
`false`	`true`	No	No	Only via `#file:` reference

Frontmatter Example with Optional Fields

---
name: pr-reference
description: 'Generate PR reference XML files with commit history and diffs for pull request workflows - Brought to you by microsoft/hve-core'
user-invocable: true
disable-model-invocation: false
argument-hint: "[--base-branch=origin/main] [--exclude-markdown]"
---

This example demonstrates a skill configured for both automatic semantic loading and manual /pr-reference invocation, with argument hints displayed in the prompt picker.

Collection Entry Requirements

All skills must have matching entries in one or more collections/*.collection.yml manifests. Collection entries control distribution and maturity.

Adding Your Skill to a Collection

After creating your skill package, add an items[] entry in each target collection manifest:

items:
  # path can reference artifacts from any subfolder
  - path: .github/skills/{collection-id}/my-skill
    kind: skill
    maturity: stable

Selecting Collections for Skills

Choose collections based on who uses the skill's utilities:

Skill Type	Recommended Collections
Media processing	`hve-core-all`
Documentation tools	`hve-core-all`, `hve-core`
Data processing	`hve-core-all`, `data-science`
Infrastructure tools	`hve-core-all`, `coding-standards`
Code generation	`hve-core-all`, `coding-standards`

For complete collection documentation, see AI Artifacts Common Standards - Collection Manifests.

SKILL.md Content Structure

Required Sections

1. Title (H1)

Clear, descriptive heading matching skill purpose:

# Video-to-GIF Conversion Skill

2. Overview

Explains what the skill does and its approach:

This skill converts video files to optimized GIF animations using FFmpeg two-pass palette optimization.

3. Prerequisites

Lists installation requirements for each platform:

## Prerequisites

FFmpeg MUST be installed and available in your system PATH.

### macOS

\`\`\`bash
brew install ffmpeg
\`\`\`

### Linux

\`\`\`bash
sudo apt install ffmpeg
\`\`\`

### Windows

\`\`\`powershell
choco install ffmpeg
\`\`\`

4. Quick Start

Shows basic usage with default settings:

## Quick Start

\`\`\`bash
./scripts/convert.sh input.mp4
\`\`\`

5. Parameters Reference (when scripts are included)

Documents all configurable options with defaults. Include this section when the skill contains scripts with configurable parameters.

## Parameters

| Parameter | Default | Description  |
|-----------|---------|--------------|
| --fps     | 10      | Frame rate   |
| --width   | 480     | Output width |

6. Script Reference (when scripts are included)

Documents both bash and PowerShell usage. Include this section when the skill contains a scripts/ directory.

## Script Reference

### convert.sh (Bash)

\`\`\`bash
./convert.sh --input video.mp4 --fps 15
\`\`\`

### convert.ps1 (PowerShell)

\`\`\`powershell
./convert.ps1 -InputPath video.mp4 -Fps 15
\`\`\`

7. Troubleshooting

Common issues and solutions:

## Troubleshooting

### Tool not found

Verify the dependency is in your PATH...

Include at end of file:

*🤖 Crafted with precision by ✨Copilot following brilliant human instruction, then carefully refined by our team of discerning human reviewers.*

Script Requirements

Scripts are optional for skills. A skill can function purely as a documentation-driven knowledge package without any scripts. When a skill includes a scripts/ directory, a PowerShell implementation is required and a bash implementation is recommended for cross-platform support.

Bash Scripts

Bash scripts MUST:

Use #!/usr/bin/env bash shebang
Enable strict mode: set -euo pipefail
Follow main function pattern
Include usage function with --help support
Check for required dependencies
Handle platform differences (macOS vs Linux)

See bash.instructions.md for complete standards.

PowerShell Scripts

PowerShell scripts MUST:

Use [CmdletBinding()] attribute
Include comment-based help (.SYNOPSIS, .DESCRIPTION, .PARAMETER, .EXAMPLE)
Validate parameters with [ValidateScript()], [ValidateRange()], or [ValidateSet()]
Check for required dependencies
Use proper error handling

Unit Testing Requirements

All skill scripts MUST include unit tests that achieve a minimum of 80% code coverage. Tests are co-located inside the skill directory to keep each skill self-contained.

Test File Location

Place test files in a tests/ subdirectory within the skill directory:

.github/skills/<skill-name>/
└── tests/
    └── <script-name>.Tests.ps1

PowerShell Tests

PowerShell skill scripts require Pester 5.x tests:

Use .Tests.ps1 suffix matching the source script name
Follow the same conventions as scripts/tests/ (see Testing Architecture)
Pester configuration is defined at scripts/tests/pester.config.ps1; co-located skill tests run when their tests/ directories are included in the Pester run paths (for example via CI or explicit test invocation)

Minimal example:

Describe 'Convert-VideoToGif' {
    It 'Validates input file exists' {
        { ./convert.ps1 -InputPath 'nonexistent.mp4' } | Should -Throw
    }
}

Python Tests

Python skill scripts require pytest:

Use test_<script_name>.py naming convention
Place tests in the tests/ subdirectory alongside PowerShell tests
Configure pytest and ruff in a pyproject.toml at the skill root

Packaging Note

Co-located tests/ directories are automatically excluded from the VSIX extension package. No additional contributor action is needed.

Supported Languages

Skills may include scripts in any of these supported languages. Each language has specific tooling and CI expectations.

Language	Script Extension	Test Framework	Linter / Analyzer	CI Coverage
Bash	`.sh`	N/A	shellcheck	Lint only
PowerShell	`.ps1`	Pester 5.x	PSScriptAnalyzer	Full (lint + test)
Python	`.py`	pytest	ruff (line-length=88, target-version=py311)	Planned

Requesting New Language Support

To request support for a new programming language:

Open a Skill Request issue
Select the desired language in the Programming Language dropdown (choose "Other" if unlisted)
Describe the tooling requirements: test framework, linter, CI integration needs
A maintainer will evaluate feasibility and update this table when support is added

Examples Directory

The examples/ subdirectory SHOULD include:

Quick usage examples for common scenarios
Test data generation instructions
Quality comparison guides
Batch processing patterns

Path Portability

Skill packages are self-contained and relocatable. The skill root directory varies by distribution context:

Context	Skill Root Example
In-repo	`.github/skills/<collection>/<skill>/`
Copilot CLI plugin	`~/.copilot/installed-plugins/_direct/<plugin>/skills/<skill>/`
VS Code extension	`~/.vscode/extensions/<publisher>.<ext>-<version>/skills/<skill>/`
Plugin output	`plugins/<collection>/skills/<skill>/`

The .github/ directory does not exist in any distributed context. All file references and script paths within a skill must be relative to the skill root, never repo-root-relative.

Use ./scripts/<script-name>.sh instead of ./.github/skills/<collection>/<skill>/scripts/<script-name>.sh
Use references/<reference-name>.md instead of .github/skills/<collection>/<skill>/references/<reference-name>.md
From files in subdirectories (such as references/), use ../scripts/ to reach sibling directories

This rule applies to all files in the skill: SKILL.md, reference documents, assets, and code examples in documentation. Repo-root-relative paths break portability and will fail validation.

Semantic Skill Loading

VS Code Copilot uses progressive disclosure to load skills efficiently. Understanding this model helps authors write effective description fields and helps callers invoke skills correctly.

How Skills are Discovered

Copilot reads the name and description fields from all SKILL.md files at startup. This lightweight metadata (~100 tokens per skill) enables relevance matching without loading full skill content.

How Skills are Loaded

When a user request or caller description semantically matches a skill's description:

Level 1 (Discovery): Copilot matches the task against name and description frontmatter (always loaded, ~100 tokens per skill).
Level 2 (Instructions): The full SKILL.md body loads into context with script usage, parameters, and troubleshooting (under 5000 tokens recommended).
Level 3 (Resources): Scripts, examples, and references in the skill directory load on-demand during execution.

Writing Effective Descriptions

The description field is the semantic key for automatic loading. Craft descriptions that are:

Specific enough for accurate matching (include the primary action verb and artifact type)
Broad enough to cover all use cases (avoid narrowing to one scenario)
Containing searchable terms that callers naturally use

How Callers Invoke Skills

Prompts, agents, and instructions should describe the task intent rather than referencing script paths. Copilot matches task descriptions against skill description fields and loads the skill on-demand.

Avoid hardcoded script paths, platform detection logic, or extension fallback code in caller files.

For explicit invocation, use the /skill-name slash command in chat.

Validation Checklist

Before submitting your skill, verify:

Structure

Directory at .github/skills/<skill-name>/
SKILL.md present with valid frontmatter
If scripts/ directory exists: at least one .ps1 file present (.sh recommended)
Only recognized subdirectories used (scripts, references, assets, examples, tests)
Examples README (recommended)

Frontmatter

Valid YAML between --- delimiters
name field present and matches directory name
description field present and descriptive
Optional: user-invocable set appropriately (default true works for most skills)
Optional: disable-model-invocation set appropriately (default false works for most skills)
Optional: argument-hint provides useful input guidance if set

Scripts (when included)

scripts/ directory contains at least one .ps1 file
PowerShell script passes PSScriptAnalyzer
If bash scripts are included: follows bash.instructions.md
When both exist, scripts implement equivalent functionality
Help and usage documentation included

Testing

Unit tests present in tests/ subdirectory
PowerShell tests use .Tests.ps1 naming convention
Tests pass locally via npm run test:ps

Documentation

All required SKILL.md sections present
Prerequisites documented per platform
Parameters fully documented
Troubleshooting section included
Attribution footer present

Automated Validation

Run these commands before submission:

npm run lint:frontmatter      # Validate SKILL.md frontmatter
npm run lint:ps               # Validate PowerShell scripts (when present)
npm run lint:md               # Validate markdown formatting
npm run validate:skills       # Validate skill directory structure
npm run test:ps               # Run PowerShell unit tests

All checks MUST pass before merge.

AI Artifacts Common Standards - Shared standards for all contributions
Contributing Agents - Agent file guidelines
Contributing Prompts - Prompt file guidelines
Contributing Instructions - Instructions file guidelines
Agent Skills Specification - Core specification for skill structure and metadata
VS Code Copilot Agent Skills - VS Code integration, progressive disclosure, and frontmatter controls

🤖 Crafted with precision by ✨Copilot following brilliant human instruction, then carefully refined by our team of discerning human reviewers.

What is a Skill?​

Skill vs Agent vs Prompt​

Use Cases for Skills​

Skills Not Accepted​

File Structure Requirements​

Location​

Naming Convention​

Frontmatter Requirements​

Required Fields​

Frontmatter Example​

Optional Fields​

Invocation Control Matrix​

Frontmatter Example with Optional Fields​

Collection Entry Requirements​

Adding Your Skill to a Collection​

Selecting Collections for Skills​

SKILL.md Content Structure​

Required Sections​

1. Title (H1)​

2. Overview​

3. Prerequisites​

4. Quick Start​

5. Parameters Reference (when scripts are included)​

6. Script Reference (when scripts are included)​

7. Troubleshooting​

8. Attribution Footer​

Script Requirements​

Bash Scripts​

PowerShell Scripts​

Unit Testing Requirements​

Test File Location​

PowerShell Tests​

Python Tests​

Packaging Note​

Supported Languages​

Requesting New Language Support​

Examples Directory​

Path Portability​

Semantic Skill Loading​

How Skills are Discovered​

How Skills are Loaded​

Writing Effective Descriptions​

How Callers Invoke Skills​

Validation Checklist​

Structure​

Frontmatter​

Scripts (when included)​

Testing​

Documentation​

Automated Validation​

Related Documentation​