feat(skills): edit SKILL frontmatter schema, add CI validation, and documentation (#625)

## Description

Added foundational skill infrastructure to support semantic invocation
and optional frontmatter properties. This is a prerequisite for
migrating existing scripts to the Agent Skills pattern. Changes span the
frontmatter schema, a new CI validation script with Pester tests,
prompt-builder guidance for semantic skill invocation, documentation
updates, and PR validation pipeline integration.

> Note: Some additional changes were done to
`prompt-builder.instructions.md` based on optimization recommended by
the `/analyse-prompt` command to improve clarity and structure of the
semantic invocation documentation.

- feat(skills): Added `user-invokable`, `disable-model-invocation`, and
`argument-hint` optional properties to `skill-frontmatter.schema.json`
with `maxLength` constraints on `name` (64), `description` (1024), and
`argument-hint` (256)
- feat(skills): Created `Validate-SkillStructure.ps1` (464 lines) with
SKILL.md presence checks, frontmatter field validation, name-directory
consistency, unrecognized subdirectory warnings, changed-files-only mode
via Git merge-base, CI annotations, and JSON results export
- feat(skills): Created `Validate-SkillStructure.Tests.ps1` (876 lines)
with full Pester coverage across `Get-SkillFrontmatter`,
`Test-SkillDirectory`, `Get-ChangedSkillDirectories`, and
`Write-SkillValidationResults` including edge cases for git failures,
path normalization, and CI annotation emission
- feat(skills): Added "Skill Invocation from Callers" subsection to
`prompt-builder.instructions.md` documenting semantic description
matching as the primary invocation pattern with before/after examples,
progressive disclosure levels, and updated optional field documentation
- docs(skills): Updated `docs/contributing/skills.md` with Optional
Fields section, Invocation Control Matrix table, frontmatter example
with optional fields, Semantic Skill Loading section with progressive
disclosure levels, caller invocation patterns, and external references
to agentskills.io and VS Code docs
- ci(skills): Created `skill-validation.yml` reusable workflow with
`soft-fail` and `changed-files-only` inputs, pinned action SHAs, and
artifact upload for `skill-validation-results`
- ci(skills): Integrated `skill-validation` job into `pr-validation.yml`
with `changed-files-only: true`
- chore: Added `validate:skills` npm script to `package.json` and
appended it to `lint:all`; updated `CONTRIBUTING.md`,
`scripts/README.md`, `scripts/linting/README.md`,
`docs/architecture/workflows.md`,
`docs/contributing/ai-artifacts-common.md`,
`.github/workflows/README.md`, and `.github/PULL_REQUEST_TEMPLATE.md` to
document the new validation step
- chore: Added `agentskills` and `invokable` to `.cspell.json`
dictionary

## Related Issue(s)

Closes #623

## Type of Change

Select all that apply:

**Code & Documentation:**

- [ ] Bug fix (non-breaking change fixing an issue)
- [x] New feature (non-breaking change adding functionality)
- [ ] Breaking change (fix or feature causing existing functionality to
change)
- [x] Documentation update

**Infrastructure & Configuration:**

- [x] GitHub Actions workflow
- [ ] Linting configuration (markdown, PowerShell, etc.)
- [ ] Security configuration
- [ ] DevContainer configuration
- [ ] Dependency update

**AI Artifacts:**

- [x] Reviewed contribution with `prompt-builder` agent and addressed
all feedback
- [x] Copilot instructions (`.github/instructions/*.instructions.md`)
- [ ] Copilot prompt (`.github/prompts/*.prompt.md`)
- [ ] Copilot agent (`.github/agents/*.agent.md`)
- [ ] Copilot skill (`.github/skills/*/SKILL.md`)

> **Note for AI Artifact Contributors**:
>
> - **Agents**: Research, indexing/referencing other project (using
standard VS Code GitHub Copilot/MCP tools), planning, and general
implementation agents likely already exist. Review `.github/agents/`
before creating new ones.
> - **Skills**: Must include both bash and PowerShell scripts. See
[Skills](../docs/contributing/skills.md).
> - **Model Versions**: Only contributions targeting the **latest
Anthropic and OpenAI models** will be accepted. Older model versions
(e.g., GPT-3.5, Claude 3) will be rejected.
> - See [Agents Not
Accepted](../docs/contributing/custom-agents.md#agents-not-accepted) and
[Model Version
Requirements](../docs/contributing/ai-artifacts-common.md#model-version-requirements).

**Other:**

- [x] Script/automation (`.ps1`, `.sh`, `.py`)
- [ ] Other (please describe):

## Sample Prompts (for AI Artifact Contributions)

<!-- Not applicable — this PR updates prompt-builder instructions rather
than creating a new standalone AI artifact -->

## Testing

- Ran `/analyze-prompt`
- Ran `Validate-SkillStructure.Tests.ps1` with Pester to verify all
tests pass, including edge cases for git failures, path normalization,
and CI annotation emission.
- Ran `npm run validate:skills` to ensure the validation script executes
without errors in a real-world scenario (based on currently one existing
skill).

## Checklist

### Required Checks

- [x] Documentation is updated (if applicable)
- [x] Files follow existing naming conventions
- [ ] Changes are backwards compatible (if applicable)
- [x] Tests added for new functionality (if applicable)

### AI Artifact Contributions
<!-- If contributing an agent, prompt, instruction, or skill, complete
these checks -->
- [x] Used `/prompt-analyze` to review contribution
- [x] Addressed all feedback from `prompt-builder` review
- [x] Verified contribution follows common standards and type-specific
requirements

### Required Automated Checks

The following validation commands must pass before merging:

- [x] Markdown linting: `npm run lint:md`
- [x] Spell checking: `npm run spell-check`
- [x] Frontmatter validation: `npm run lint:frontmatter`
- [x] Skill structure validation: `npm run validate:skills`
- [x] Link validation: `npm run lint:md-links`
- [x] PowerShell analysis: `npm run lint:ps`

## Security Considerations

- [x] This PR does not contain any sensitive or NDA information
- [ ] Any new dependencies have been reviewed for security issues
- [ ] Security-related scripts follow the principle of least privilege

## Additional Notes

All four deliverables from issue #623 are addressed in this PR:

1. **Skill Frontmatter Schema Updates** — Added three optional
properties with type constraints and length limits
2. **Prompt-Builder Instructions Updates** — Added semantic invocation
guidance with before/after examples and progressive disclosure
documentation
3. **CI Validation for Skill Structure** — Created
`Validate-SkillStructure.ps1` with comprehensive Pester test coverage in
`Validate-SkillStructure.Tests.ps1`
4. **Documentation Updates** — Updated `docs/contributing/skills.md`
with optional fields, invocation control matrix, semantic skill loading,
and external specification references

🛠️ - Generated by Copilot

---------

Co-authored-by: Bill Berry <WilliamBerryiii@users.noreply.github.com>
Co-authored-by: Bill Berry <wberry@microsoft.com>

Author: katriendg

.cspell.json

@@ -59,13 +59,15 @@
     "general-technical"
   ],
   "words": [
+    "agentskills",
     "autobuild",
     "behaviour",
     "Browsable",
     "Chronograf",
     "edgeai",
     "GHCP",
     "GHSA",
+    "invokable",
     "Kapacitor",
     "kata",
     "katas",

.github/PULL_REQUEST_TEMPLATE.md

@@ -95,6 +95,7 @@ The following validation commands must pass before merging:
 - [ ] Markdown linting: `npm run lint:md`
 - [ ] Spell checking: `npm run spell-check`
 - [ ] Frontmatter validation: `npm run lint:frontmatter`
+- [ ] Skill structure validation: `npm run validate:skills`
 - [ ] Link validation: `npm run lint:md-links`
 - [ ] PowerShell analysis: `npm run lint:ps`
 

.github/instructions/prompt-builder.instructions.md

@@ -248,9 +248,10 @@ Purpose: Self-contained packages that bundle documentation with executable scrip
 
 Characteristics:
 
-* Bundled with bash and PowerShell scripts in the same directory.
+* Optionally bundled with bash and PowerShell scripts in a `scripts/` subdirectory.
 * Provides step-by-step instructions for task execution.
 * Includes prerequisites, parameters, and troubleshooting sections.
+* Skills without scripts are valid documentation-driven knowledge packages.
 
 Skill directory structure:
 
@@ -268,6 +269,32 @@ Skill directory structure:
     └── README.md               # Usage examples (recommended)
 ```
 
+#### Optional Directories
+
+##### scripts/
+
+Contains executable code that agents run to perform tasks:
+
+* Scripts are self-contained or clearly document dependencies.
+* Include helpful error messages and handle edge cases gracefully.
+* Provide parallel implementations for bash and PowerShell when targeting cross-platform use.
+
+##### references/
+
+Contains additional documentation that agents read when needed:
+
+* *REFERENCE.md* for detailed technical reference material.
+* Domain-specific files such as `finance.md` or `legal.md`.
+* Keep individual reference files focused; agents load these on demand.
+
+##### assets/
+
+Contains static resources:
+
+* Templates for documents or configuration files.
+* Images such as diagrams or examples.
+* Data files such as lookup tables or schemas.
+
 ### Skill Content Structure
 
 Skill files include these sections in order:
@@ -281,7 +308,7 @@ Skill files include these sections in order:
 7. Troubleshooting: Common issues and solutions.
 8. Attribution: Attribution in `description:` frontmatter and standard footer.
 
-### Progressive Disclosure
+#### Progressive Disclosure
 
 Structure skills for efficient context usage:
 
@@ -291,7 +318,7 @@ Structure skills for efficient context usage:
 
 Keep the main *SKILL.md* focused. Move detailed reference material to separate files.
 
-### File References
+#### File References
 
 When referencing other files in the skill, use relative paths from the skill root:
 
@@ -304,10 +331,35 @@ scripts/extract.py
 
 Keep file references one level deep from *SKILL.md*. Avoid deeply nested reference chains.
 
+#### Skill Invocation from Callers
+
+When prompts, agents, or instructions need a skill's capability, describe the task intent rather than referencing script paths directly. Copilot matches the task description against each skill's `description` frontmatter and loads the skill on-demand via progressive disclosure.
+
+Avoid hardcoded script paths, platform detection logic, or extension fallback code in caller files. Skills handle these concerns internally through their SKILL.md instructions and scripts.
+
+For explicit invocation, reference the slash command `/skill-name` in usage documentation.
+
+Semantic invocation pattern:
+
+```markdown
+<!-- Direct script reference (avoid) -->
+Run `./scripts/dev-tools/pr-ref-gen.sh --base-branch origin/main` to generate the PR reference.
+
+<!-- Semantic skill invocation (preferred) -->
+Generate the PR reference XML file comparing the current branch against origin/main.
+```
+
+When a caller describes a task that semantically matches a skill's `description`, Copilot follows this loading sequence:
+
+1. Level 1 (Discovery): Matches the task description against skill frontmatter `name` and `description` fields (~100 tokens per skill).
+2. Level 2 (Instructions): Loads the full SKILL.md body into context with script usage instructions (<5000 tokens recommended).
+3. Level 3 (Resources): Accesses scripts, examples, and references in the skill directory on-demand during execution.
+
 Validation guidelines:
 
 * Frontmatter follows the Frontmatter Requirements section, including `name` and `description` fields.
 * Provide parallel script implementations for bash and PowerShell when targeting cross-platform use.
+* Skills without scripts are valid; omit Parameters Reference and Script Reference sections in that case.
 * Document prerequisites for each supported platform.
 * Keep *SKILL.md* focused; move detailed reference material to `references/`.
 * Additional sections can be added between Parameters Reference and Troubleshooting as needed.
@@ -328,7 +380,7 @@ Skill files also include a standard attribution footer as the last line of body
 
 ## Frontmatter Requirements
 
-This section defines frontmatter field requirements for prompt engineering artifacts.
+Frontmatter field requirements for prompt engineering artifacts follow.
 
 Maturity is tracked in `collections/*.collection.yml` item metadata, not in frontmatter. Do not include a `maturity` field in artifact frontmatter. Set maturity on the artifact's matching collection item entry; when omitted, maturity defaults to `stable`.
 
@@ -352,7 +404,7 @@ Optional fields available by file type:
 
 * `tools:` - Tool restrictions for agents and subagents. When omitted, all tools are accessible. When specified, list only tools available in the current VS Code context.
 * `handoffs:` - Agent handoff declarations. Each entry includes `label` (display text, supports emoji), `agent` (target agent name), and optionally `prompt` (slash command to invoke) and `send` (boolean, auto-send the prompt when `true`).
-* `user-invocable:` - Boolean. Set to `false` to hide the agent from the user and prevent direct invocation. Defaults to `true` when omitted. Use for subagents that should not appear in the agent picker.
+* `user-invocable:` - Boolean. Set to `false` to hide the artifact from the user and prevent direct invocation. Defaults to `true` when omitted. Use for subagents that should not appear in the agent picker or background-only skills that should not appear in the slash command menu.
 * `disable-model-invocation:` - Boolean. Set to `true` to prevent Copilot from automatically invoking the agent. Use for agents that run subagents, agents that cause side effects (git operations, backlog management, deployments), or agents that should only run when explicitly requested. Defaults to `false` when omitted.
 * `agent:` - Agent delegation for prompt files.
 * `argument-hint:` - Hint text for prompt picker display.

.github/workflows/README.md

@@ -69,6 +69,7 @@ Compose multiple reusable workflows for comprehensive validation and security sc
 | `table-format.yml`           | markdown-table-formatter | Verify table formatting (check-only) | `soft-fail` (false)                                                                                             | table-format-results           |
 | `ps-script-analyzer.yml`     | PSScriptAnalyzer         | PowerShell static analysis           | `soft-fail` (false), `changed-files-only` (true)                                                                | psscriptanalyzer-results       |
 | `frontmatter-validation.yml` | Custom PS script         | YAML frontmatter validation          | `soft-fail` (false), `changed-files-only` (true), `skip-footer-validation` (false), `warnings-as-errors` (true) | frontmatter-validation-results |
+| `skill-validation.yml`       | Custom PS script         | Skill directory structure validation | `soft-fail` (false), `changed-files-only` (true)                                                                | skill-validation-results       |
 | `link-lang-check.yml`        | Custom PS script         | Detect language-specific URLs        | `soft-fail` (false)                                                                                             | link-lang-check-results        |
 | `markdown-link-check.yml`    | markdown-link-check      | Validate links (internal/external)   | `soft-fail` (true)                                                                                              | markdown-link-check-results    |
 

.github/workflows/pr-validation.yml

@@ -97,6 +97,16 @@ jobs:
     with:
       soft-fail: false
 
+  skill-validation:
+    name: Skill Validation
+    uses: ./.github/workflows/skill-validation.yml
+    permissions:
+      contents: read
+    with:
+      soft-fail: false
+      changed-files-only: true
+      base-branch: ${{ github.event.pull_request.base.sha || format('origin/{0}', github.base_ref) }}
+
   link-lang-check:
     name: Link Language Check
     uses: ./.github/workflows/link-lang-check.yml

.github/workflows/skill-validation.yml

@@ -0,0 +1,59 @@
+name: Skill Validation
+
+on:
+  workflow_call:
+    inputs:
+      soft-fail:
+        description: 'Whether to continue on validation failures'
+        required: false
+        type: boolean
+        default: false
+      changed-files-only:
+        description: 'Only validate skills with changed files'
+        required: false
+        type: boolean
+        default: true
+      base-branch:
+        description: 'Base branch or SHA for change detection (defaults to origin/main)'
+        required: false
+        type: string
+        default: ''
+
+permissions:
+  contents: read
+
+jobs:
+  validate:
+    name: Validate Skill Structure
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v4.2.2
+        with:
+          persist-credentials: false
+          fetch-depth: 0
+
+      - name: Run skill validation
+        shell: pwsh
+        run: |
+          $params = @{}
+          if ('${{ inputs.changed-files-only }}' -eq 'true') {
+            $params['ChangedFilesOnly'] = $true
+            $baseBranch = '${{ inputs.base-branch }}'
+            if (-not [string]::IsNullOrEmpty($baseBranch)) {
+              $params['BaseBranch'] = $baseBranch
+            }
+          }
+          & './scripts/linting/Validate-SkillStructure.ps1' -WarningsAsErrors @params
+        continue-on-error: ${{ inputs.soft-fail }}
+
+      - name: Upload validation results
+        if: always()
+        uses: actions/upload-artifact@b7c566a772e6b6bfb58ed0dc250532a479d7789f # v4.4.3
+        with:
+          name: skill-validation-results
+          path: logs/skill-validation-results.json
+          retention-days: 30
+          if-no-files-found: ignore

CONTRIBUTING.md

@@ -43,6 +43,7 @@ npm run lint:md          # Run markdownlint
 npm run lint:ps          # Run PowerShell analyzer
 npm run lint:yaml        # Run YAML linter
 npm run lint:frontmatter # Validate markdown frontmatter
+npm run validate:skills  # Validate skill directory structure
 npm run lint:md-links    # Check markdown links
 npm run spell-check      # Run cspell
 npm run format:tables    # Format markdown tables
@@ -61,21 +62,31 @@ We strongly recommend using the provided DevContainer, which comes pre-configure
   - [Required Tools](#required-tools)
   - [Validation Commands](#validation-commands)
   - [Development Environment](#development-environment)
+- [Table of Contents](#table-of-contents)
 - [Code of Conduct](#code-of-conduct)
 - [I Have a Question](#i-have-a-question)
 - [I Want To Contribute](#i-want-to-contribute)
   - [Reporting Bugs](#reporting-bugs)
+    - [Before Submitting a Bug Report](#before-submitting-a-bug-report)
+    - [How Do I Submit a Good Bug Report?](#how-do-i-submit-a-good-bug-report)
   - [Suggesting Enhancements](#suggesting-enhancements)
+    - [Before Submitting an Enhancement](#before-submitting-an-enhancement)
+    - [How Do I Submit a Good Enhancement Suggestion?](#how-do-i-submit-a-good-enhancement-suggestion)
   - [Your First Code Contribution](#your-first-code-contribution)
   - [Improving The Documentation](#improving-the-documentation)
 - [AI Artifact Contributions](#ai-artifact-contributions)
+  - [Getting Started with AI Artifacts](#getting-started-with-ai-artifacts)
+  - [Artifact Types](#artifact-types)
+  - [Essential Resources](#essential-resources)
+  - [Quick Reference](#quick-reference)
 - [Pull Request Inactivity Policy](#pull-request-inactivity-policy)
   - [Active Pull Requests](#active-pull-requests)
   - [Draft Pull Requests](#draft-pull-requests)
   - [Exemptions](#exemptions)
 - [Style Guides](#style-guides)
   - [Local Development Setup](#local-development-setup)
   - [Coding Conventions](#coding-conventions)
+  - [Copyright and License Headers](#copyright-and-license-headers)
 - [Testing Requirements](#testing-requirements)
   - [When Tests Are Required](#when-tests-are-required)
   - [Test Conventions](#test-conventions)
@@ -175,7 +186,7 @@ When contributing code to the project, please consider the following guidance:
 - Assign an issue to yourself before beginning any effort, and update the issue status accordingly.
 - If an issue for your contribution does not exist, [please file an issue](https://github.com/microsoft/hve-core/issues/new) first to engage with the project maintainers for guidance.
 - Commits should reference related issues for traceability (e.g., "Fixes #123" or "Relates to #456").
-- When creating a PR, use [GitHub's closing keywords](https://docs.github.com/en/issues/tracking-your-work-with-issues/linking-a-pull-request-to-an-issue) in the description to automatically link and close related issues.
+- When creating a PR, use [GitHub's closing keywords](https://docs.github.com/en/issues/tracking-your-work-with-issues/using-issues/linking-a-pull-request-to-an-issue) in the description to automatically link and close related issues.
 - All code PRs destined for the `main` branch will be reviewed by pre-determined reviewer groups that are automatically added to each PR.
 
 This project also includes a Dev Container for development work, and using that dev container is preferred, to ensure you are using the same toolchains and tool versions as other contributors. You can read more about the Dev Container in its [ReadMe](./.devcontainer/README.md).

docs/architecture/workflows.md

@@ -66,6 +66,7 @@ Individual validation workflows called by orchestration workflows:
 | `ps-script-analyzer.yml`      | PowerShell static analysis      | `npm run lint:ps`          |
 | `table-format.yml`            | Markdown table formatting       | `npm run format:tables`    |
 | `pester-tests.yml`            | PowerShell unit tests           | `npm run test:ps`          |
+| `skill-validation.yml`        | Skill structure validation      | `npm run validate:skills`  |
 | `dependency-pinning-scan.yml` | GitHub Actions pinning          | N/A (PowerShell direct)    |
 | `sha-staleness-check.yml`     | SHA reference freshness         | N/A (PowerShell direct)    |
 | `codeql-analysis.yml`         | CodeQL security scanning        | N/A (GitHub native)        |
@@ -112,6 +113,7 @@ flowchart LR
 | yaml-lint                | `yaml-lint.yml`               | YAML syntax                    |
 | pester-tests             | `pester-tests.yml`            | PowerShell unit tests          |
 | frontmatter-validation   | `frontmatter-validation.yml`  | AI artifact metadata           |
+| skill-validation         | `skill-validation.yml`        | Skill directory structure      |
 | link-lang-check          | `link-lang-check.yml`         | Link accessibility             |
 | markdown-link-check      | `markdown-link-check.yml`     | Broken links                   |
 | dependency-pinning-check | `dependency-pinning-scan.yml` | Action SHA pinning             |
@@ -235,6 +237,7 @@ Workflows invoke validation through npm scripts defined in `package.json`:
 | `lint:ps`          | `Invoke-PSScriptAnalyzer.ps1`      | ps-script-analyzer.yml     |
 | `format:tables`    | `markdown-table-formatter`         | table-format.yml           |
 | `test:ps`          | `Invoke-Pester`                    | pester-tests.yml           |
+| `validate:skills`  | `Validate-SkillStructure.ps1`      | skill-validation.yml       |
 
 ## Related Documentation
 

docs/contributing/ai-artifacts-common.md

@@ -651,6 +651,9 @@ npm run lint:md-links
 
 # PowerShell analysis (if applicable)
 npm run lint:ps
+
+# Validate skill structure (if applicable)
+npm run validate:skills
 ```
 
 ### Quality Gates