feat(skills): align skill frontmatter schema with VS Code and agentskills.io specification

@AhmedMustafa249 is already working on this.

Since Feb 23, 2026.

### Issue Description

The skill frontmatter schema (`scripts/linting/schemas/skill-frontmatter.schema.json`) and validation script (`scripts/linting/Validate-SkillStructure.ps1`) are missing several fields that VS Code already supports and that the official Agent Skills specification defines at .

**The schema should be updated once full skill support stabilizes in VS Code.**

### Current State

The schema defines five properties with `additionalProperties: false`:

| Field | Type | Status in Schema |
|----------------------------|---------|------------------|
| `name` | string | Present |
| `description` | string | Present |
| `user-invocable` | boolean | Present |
| `disable-model-invocation` | boolean | Present |
| `argument-hint` | string | Present |

VS Code currently accepts these attributes in skill files:

`argument-hint`, `compatibility`, `description`, `disable-model-invocation`, `license`, `metadata`, `name`, `user-invocable`

The official Agent Skills spec at defines:

| Field | Required | Description |
|----------------|----------|--------------------------------------------------------------------|
| `name` | Yes | Max 64 chars, lowercase kebab-case, no leading/trailing/double `-` |
| `description` | Yes | Max 1024 chars, describes what the skill does and when to use it |
| `license` | No | License name or reference to bundled license file |
| `compatibility`| No | Max 500 chars, environment requirements |
| `metadata` | No | Arbitrary key-value map for additional metadata |
| `allowed-tools`| No | Space-delimited pre-approved tool list (experimental) |

### Gaps

1. **Missing `compatibility` field**: Already used by `pr-reference/SKILL.md` (`compatibility: 'Requires git available on PATH'`), but not in the JSON schema. Adding it would formalize existing usage.

2. **Missing `license` field**: Both VS Code and the spec support it. Not currently used by any skill in the repo, but needed for completeness and for skills that bundle proprietary or non-MIT content.

3. **Missing `metadata` field**: Both VS Code and the spec support a map of string key-value pairs. Useful for author, version, and other custom metadata.

4. **`allowed-tools` field (experimental)**: Defined in the official spec but NOT listed in VS Code's supported attributes. This should be tracked but deferred until VS Code adds support.

5. **`name` pattern too permissive**: Current regex `^[a-z][a-z0-9-]*$` allows trailing hyphens (`my-skill-`) and consecutive hyphens (`my--skill`). The spec explicitly forbids both. The pattern should be tightened to `^[a-z][a-z0-9]*(-[a-z0-9]+)*$` or equivalent.

6. **Validation script does not check for unsupported attributes**: `Get-SkillFrontmatter` in `Validate-SkillStructure.ps1` parses all key-value pairs without validating keys against the known set. While the JSON schema has `additionalProperties: false`, the PowerShell script runs independently and silently accepts unknown keys.

### Proposed Changes

Once VS Code skill support stabilizes:

1. Add `compatibility`, `license`, and `metadata` to `skill-frontmatter.schema.json`.
2. Tighten the `name` regex to reject trailing hyphens and consecutive hyphens.
3. Add attribute validation to `Validate-SkillStructure.ps1` to warn on unrecognized frontmatter keys.
4. Update `docs/contributing/skills.md` and `prompt-builder.instructions.md` to document new fields.
5. Track `allowed-tools` separately; add to schema when VS Code supports it.
6. Update Pester tests in `Validate-SkillStructure.Tests.ps1` for new validation rules.

### Acceptance Criteria

* Schema includes `compatibility` (string, maxLength 500), `license` (string), and `metadata` (object with string values).
* `name` pattern rejects `-trailing`, `double--hyphen`, and `-leading` names.
* `Validate-SkillStructure.ps1` warns when a SKILL.md frontmatter key is not in the recognized set.
* Existing skills (`pr-reference`, `video-to-gif`) pass validation after changes.
* `allowed-tools` is tracked as a follow-up item, not added to schema yet.

### References

* Official spec:
* VS Code supported attributes screenshot (attached to conversation)
* Current schema: `scripts/linting/schemas/skill-frontmatter.schema.json`
* Current validator: `scripts/linting/Validate-SkillStructure.ps1`
* Existing usage: `.github/skills/shared/pr-reference/SKILL.md` (uses `compatibility`)

### Additional Context

_No response_