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

[katriendg]

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 https://agentskills.io/specification.

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 https://agentskills.io/specification 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: https://agentskills.io/specification
• 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

[AhmedMustafa249]

Not sure if the VS Code Skill support is stable yet, but if it is, can I take this on?

[katriendg]

@AhmedMustafa249 Thanks for offering! We do need to wait out for changes still expected, let's see what gets released in the next VS Code push, probably arriving in March. I can assign your name to it already but keep it in waiting mode, and then ping you once we have a stable version to align to?

[AhmedMustafa249]

@katriendg Sounds good, go ahead and assign it to me

[AhmedMustafa249]

@katriendg Any update on this?

[katriendg]

@AhmedMustafa249 there is no clear update in the docs yet, so I believe this becomes more relevant once we see further stabilization. Let's give it another couple of weeks. Thanks for checking BTW.