GitVita
New repositoryImport repositoryNew issue
Your repositories Your dashboard Sign in

microsoft/hve-core

Public

mirrored fromhttps://github.com/microsoft/hve-coreAvailable

Watch0Fork0Star0
CodeCommitsIssuesPull requestsActionsInsightsSecurity
hve-core-v2.1.0

Branches

Tags

  • No tags available.
0Branches0Tags
Go to file
Add file
Code

Clone

HTTPS

Download ZIP

hve-core/docs/contributing

docs/contributing/skills.md

304lines · modecode

RawDownload
Latest commit unavailable.
1---
2title: Contributing Skills to HVE Core
3description: Requirements and standards for contributing skill packages to hve-core
4author: Microsoft
5ms.date: 2026-01-18
6ms.topic: how-to
7keywords:
8 - skills
9 - contributing
10 - ai artifacts
11estimated_reading_time: 8
12---
13
14This guide defines the requirements, standards, and best practices for contributing skill packages to the hve-core library.
15
16**⚙️ Common Standards**: See [AI Artifacts Common Standards](ai-artifacts-common.md) for shared requirements (XML blocks, markdown quality, RFC 2119, validation, testing).
17
18## What is a Skill?
19
20A **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 with executable scripts that perform concrete operations.
21
22## Skill vs Agent vs Prompt
23
24| Artifact | Purpose | Includes Scripts | User Interaction |
25|----------|-------------------------------|------------------|--------------------------|
26| Skill | Task execution with utilities | Yes | Minimal after invocation |
27| Agent | Conversational guidance | No | Multi-turn conversation |
28| Prompt | Single-session workflow | No | One-shot execution |
29
30## Use Cases for Skills
31
32Create a skill when you need to:
33
34* Bundle documentation with executable scripts
35* Provide cross-platform utilities (bash and PowerShell)
36* Standardize common development tasks
37* Share reusable tooling across projects
38
39## Skills Not Accepted
40
41The following skill types will likely be **rejected**:
42
43* **Duplicate Skills**: Skills that replicate functionality of existing tools or skills
44* **Single-Platform Skills**: Skills that only work on one operating system
45* **Undocumented Utilities**: Scripts without comprehensive SKILL.md documentation
46
47## File Structure Requirements
48
49### Location
50
51All skill files **MUST** be placed in:
52
53```text
54.github/skills/<skill-name>/
55├── SKILL.md # Main skill definition (required)
56├── convert.sh # Bash script (required for cross-platform)
57├── convert.ps1 # PowerShell script (required for cross-platform)
58└── examples/
59 └── README.md # Usage examples (recommended)
60```
61
62### Naming Convention
63
64* Use lowercase kebab-case for directory names: `video-to-gif`
65* Main definition file MUST be named `SKILL.md`
66* Script names should describe their action: `convert.sh`, `validate.ps1`
67
68## Frontmatter Requirements
69
70### Required Fields
71
72**`name`** (string, MANDATORY)
73
74* **Purpose**: Unique identifier for the skill
75* **Format**: Lowercase kebab-case matching the directory name
76* **Example**: `video-to-gif`
77
78**`description`** (string, MANDATORY)
79
80* **Purpose**: Concise explanation of skill functionality
81* **Format**: Single sentence ending with attribution
82* **Example**: `'Video-to-GIF conversion skill with FFmpeg two-pass optimization - Brought to you by microsoft/hve-core'`
83
84**`maturity`** (string enum, MANDATORY)
85
86* **Purpose**: Controls which extension channel includes this skill
87* **Valid values**: `stable`, `preview`, `experimental`, `deprecated`
88
89### Frontmatter Example
90
91```yaml
92---
93name: video-to-gif
94description: 'Video-to-GIF conversion skill with FFmpeg two-pass optimization - Brought to you by microsoft/hve-core'
95maturity: stable
96---
97```
98
99## SKILL.md Content Structure
100
101### Required Sections
102
103#### 1. Title (H1)
104
105Clear, descriptive heading matching skill purpose:
106
107```markdown
108# Video-to-GIF Conversion Skill
109```
110
111#### 2. Overview
112
113Explains what the skill does and its approach:
114
115```markdown
116This skill converts video files to optimized GIF animations using FFmpeg two-pass palette optimization.
117```
118
119#### 3. Prerequisites
120
121Lists installation requirements for each platform:
122
123```markdown
124## Prerequisites
125
126FFmpeg MUST be installed and available in your system PATH.
127
128### macOS
129
130\`\`\`bash
131brew install ffmpeg
132\`\`\`
133
134### Linux
135
136\`\`\`bash
137sudo apt install ffmpeg
138\`\`\`
139
140### Windows
141
142\`\`\`powershell
143choco install ffmpeg
144\`\`\`
145```
146
147#### 4. Quick Start
148
149Shows basic usage with default settings:
150
151```markdown
152## Quick Start
153
154\`\`\`bash
155./.github/skills/video-to-gif/convert.sh input.mp4
156\`\`\`
157```
158
159#### 5. Parameters Reference
160
161Documents all configurable options with defaults:
162
163```markdown
164## Parameters
165
166| Parameter | Default | Description |
167|-----------|---------|--------------|
168| --fps | 10 | Frame rate |
169| --width | 480 | Output width |
170```
171
172#### 6. Script Reference
173
174Documents both bash and PowerShell usage:
175
176```markdown
177## Script Reference
178
179### convert.sh (Bash)
180
181\`\`\`bash
182./convert.sh --input video.mp4 --fps 15
183\`\`\`
184
185### convert.ps1 (PowerShell)
186
187\`\`\`powershell
188./convert.ps1 -InputPath video.mp4 -Fps 15
189\`\`\`
190```
191
192#### 7. Troubleshooting
193
194Common issues and solutions:
195
196```markdown
197## Troubleshooting
198
199### Tool not found
200
201Verify the dependency is in your PATH...
202```
203
204#### 8. Attribution Footer
205
206Include at end of file:
207
208```markdown
209*🤖 Crafted with precision by ✨Copilot following brilliant human instruction, then carefully refined by our team of discerning human reviewers.*
210```
211
212## Script Requirements
213
214### Bash Scripts
215
216Bash scripts **MUST**:
217
218* Use `#!/usr/bin/env bash` shebang
219* Enable strict mode: `set -euo pipefail`
220* Follow main function pattern
221* Include usage function with `--help` support
222* Check for required dependencies
223* Handle platform differences (macOS vs Linux)
224
225See [bash.instructions.md](../../.github/instructions/bash/bash.instructions.md) for complete standards.
226
227### PowerShell Scripts
228
229PowerShell scripts **MUST**:
230
231* Use `[CmdletBinding()]` attribute
232* Include comment-based help (`.SYNOPSIS`, `.DESCRIPTION`, `.PARAMETER`, `.EXAMPLE`)
233* Validate parameters with `[ValidateScript()]`, `[ValidateRange()]`, or `[ValidateSet()]`
234* Check for required dependencies
235* Use proper error handling
236
237## Examples Directory
238
239The `examples/` subdirectory **SHOULD** include:
240
241* Quick usage examples for common scenarios
242* Test data generation instructions
243* Quality comparison guides
244* Batch processing patterns
245
246## Validation Checklist
247
248Before submitting your skill, verify:
249
250### Structure
251
252* [ ] Directory at `.github/skills/<skill-name>/`
253* [ ] SKILL.md present with valid frontmatter
254* [ ] Bash script present for macOS/Linux
255* [ ] PowerShell script present for Windows
256* [ ] Examples README (recommended)
257
258### Frontmatter
259
260* [ ] Valid YAML between `---` delimiters
261* [ ] `name` field present and matches directory name
262* [ ] `description` field present and descriptive
263* [ ] `maturity` field present with valid value
264
265### Scripts
266
267* [ ] Bash script follows bash.instructions.md
268* [ ] PowerShell script passes PSScriptAnalyzer
269* [ ] Both scripts implement equivalent functionality
270* [ ] Help and usage documentation included
271
272### Documentation
273
274* [ ] All required SKILL.md sections present
275* [ ] Prerequisites documented per platform
276* [ ] Parameters fully documented
277* [ ] Troubleshooting section included
278* [ ] Attribution footer present
279
280## Automated Validation
281
282Run these commands before submission:
283
284```bash
285npm run lint:frontmatter # Validate SKILL.md frontmatter
286npm run psscriptanalyzer # Validate PowerShell scripts
287npm run lint # Validate markdown formatting
288```
289
290All checks **MUST** pass before merge.
291
292## Related Documentation
293
294* [AI Artifacts Common Standards](ai-artifacts-common.md) - Shared standards for all contributions
295* [Contributing Agents](custom-agents.md) - Agent file guidelines
296* [Contributing Prompts](prompts.md) - Prompt file guidelines
297* [Contributing Instructions](instructions.md) - Instructions file guidelines
298
299---
300
301<!-- markdownlint-disable MD036 -->
302*🤖 Crafted with precision by ✨Copilot following brilliant human instruction,
303then carefully refined by our team of discerning human reviewers.*
304<!-- markdownlint-enable MD036 -->
305