Overview

Update foundational skill infrastructure to support semantic invocation and optional frontmatter properties before new skills can use the pattern. This is a prerequisite for migrating existing scripts to the Agent Skills pattern.

Deliverables

1. Skill Frontmatter Schema Updates

Update scripts/linting/schemas/skill-frontmatter.schema.json:

• Add optional properties: user-invokable (boolean, default true), disable-model-invocation (boolean, default false), argument-hint (string)
• Add maxLength: 64 to name, maxLength: 1024 to description
• Keep additionalProperties: false

2. Prompt-Builder Instructions Updates

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

• Add "Skill Invocation from Callers" subsection under Skill Files
• Document semantic description matching as the primary invocation pattern
• Discourage direct script path references in caller files
• Provide before/after examples showing the transformation from direct paths to semantic task descriptions
• Update Optional Fields to document user-invokable, disable-model-invocation, argument-hint with defaults and behavior

3. CI Validation for Skill Structure

Create scripts/linting/Validate-SkillStructure.ps1:

• Validate all skills under .github/skills/ have a SKILL.md file
• Validate skill directory structure follows agentskills.io conventions
• Add npm run validate:skills script to package.json
• Integrate into PR validation workflow as a conditional step — run only when the PR contains changes under .github/skills/
• 100% Pester test coverage required — create scripts/tests/linting/Validate-SkillStructure.Tests.ps1 with full coverage of all validation paths (valid structures, missing SKILL.md, invalid directories, empty skills folder, edge cases)

4. Documentation Updates

Update docs/contributing/skills.md:

• Add Optional Fields section documenting argument-hint, user-invokable, disable-model-invocation
• Add Invocation Control Matrix table showing setting combinations and their effects
• Add second frontmatter example with optional fields
• Add Semantic Skill Loading section explaining VS Code progressive disclosure (Level 1→2→3)
• Add caller invocation patterns (describe intent, not script paths)
• Update validation checklist with optional field guidance
• Add references to VS Code Agent Skills docs and agentskills.io specification

References

• Agent Skills Specification
• VS Code Copilot Agent Skills
• Existing skill pattern: .github/skills/video-to-gif/SKILL.md

Acceptance Criteria

• skill-frontmatter.schema.json includes optional properties with correct types and constraints
• prompt-builder.instructions.md has "Skill Invocation from Callers" section with examples
• Validate-SkillStructure.ps1 validates skill directory structure
• Validate-SkillStructure.Tests.ps1 achieves 100% code coverage of the validation script
• npm run validate:skills runs skill validation
• PR validation workflow runs skill validation only when .github/skills/ files are changed in the PR
• docs/contributing/skills.md updated with optional fields, invocation control matrix, and semantic loading guidance
• npm run lint:frontmatter passes with existing skills