feat(skillpack): harden validator and improve skill discovery

Expands descriptions with more trigger phrases for Copilot auto-discovery. Quotes argument-hint values to fix GitHub web rendering. Adds disable-model-invocation to skill-scaffold so it only runs on explicit /skill-scaffold invocation. Validator now enforces name matches folder, name format and length per Agent Skills spec, and description length. README clarifies that version is a repo convention, not a spec requirement.

Author: mickpletcher

README.md

@@ -3,13 +3,13 @@
 [![Build Skillpack](https://github.com/mickpletcher/VSCode/actions/workflows/build-skillpack.yml/badge.svg)](https://github.com/mickpletcher/VSCode/actions/workflows/build-skillpack.yml)
 [![Create Release Tag](https://github.com/mickpletcher/VSCode/actions/workflows/create-release-tag.yml/badge.svg)](https://github.com/mickpletcher/VSCode/actions/workflows/create-release-tag.yml)
 [![Latest Release](https://img.shields.io/github/v/release/mickpletcher/VSCode)](https://github.com/mickpletcher/VSCode/releases)
-[![Download Skillpack](https://img.shields.io/badge/release%20artifact-skillpack.tar.gz-1f883d)](https://github.com/mickpletcher/VSCode/releases/latest/download/skillpack.tar.gz)
+[![Download Skillpack](https://img.shields.io/badge/release%20artifact-skillpack.zip-1f883d)](https://github.com/mickpletcher/VSCode/releases/latest/download/skillpack.zip)
 [![Download Manifest](https://img.shields.io/badge/release%20artifact-manifest.json-0a7ea4)](https://github.com/mickpletcher/VSCode/releases/latest/download/manifest.json)
 
 A small catalog of reusable GitHub Copilot skills for VS Code. Each skill in this repository packages a repeatable workflow as:
 
-- a machine-readable [SKILL.md](git-autopilot/SKILL.md)
-- a human-readable local README
+- a machine-readable `SKILL.md` with YAML frontmatter Copilot uses to trigger the skill
+- a human-readable `README.md`
 - a top-level folder that can be browsed directly from GitHub
 
 The goal is straightforward: keep useful workflows packaged, documented, and easy to extend.
@@ -58,14 +58,14 @@ Summarizes a pull request or diff into a reviewer-friendly overview with key cha
 ## Design Rules
 
 - keep each skill focused on one repeatable workflow
-- include a stable `version` field in each skill's frontmatter
+- include a `version` field in each skill's frontmatter — this is a repo convention for the skillpack manifest, not part of the Agent Skills specification
 - use strong trigger phrases in each `description` field
 - write supporting READMEs for humans, not just Copilot
 - prefer procedural instructions and explicit edge cases over vague guidance
 
 ## Skillpack Script
 
-The repository includes a packaging script at [scripts/skillpack.sh](scripts/skillpack.sh). It builds a distributable bundle under `dist/skillpack`, copies every top-level skill directory that contains a `SKILL.md`, includes the root README and license, writes a manifest, and creates a `dist/skillpack.tar.gz` archive. See [scripts/README.md](scripts/README.md) for full usage details.
+The repository includes a packaging script at [scripts/skillpack.sh](scripts/skillpack.sh). It builds a distributable bundle under `dist/skillpack`, copies every top-level skill directory that contains a `SKILL.md`, includes the root README and license, writes a manifest, and creates a `dist/skillpack.zip` archive. See [scripts/README.md](scripts/README.md) for full usage details.
 
 ## GitHub Actions
 

pr-summary/SKILL.md

@@ -1,8 +1,8 @@
 ---
 name: pr-summary
 version: 1.0.0
-description: Summarizes a pull request or pending code changes into a reviewer-friendly overview with highlights, risks, and testing notes. Use this when asked to write a PR summary, draft a pull request description, explain a change set, or prepare reviewer notes from a diff.
-argument-hint: [optional: branch, file scope, or PR theme]
+description: Summarizes a pull request or pending code changes into a reviewer-friendly overview with highlights, key changes, risks, and testing notes. Use this when asked to write a PR summary, draft a pull request description, explain a change set, summarize a branch, prepare reviewer notes from a diff, or generate PR context for a code review.
+argument-hint: "[branch] optional branch name, file scope, or PR theme"
 ---
 
 # Pull Request Summary

release-notes/SKILL.md

@@ -1,8 +1,8 @@
 ---
 name: release-notes
 version: 1.0.0
-description: Drafts release notes or changelog entries from git history, staged diffs, or completed work items. Use this when asked to write release notes, summarize a release, prepare a changelog entry, or turn recent changes into a publishable update summary.
-argument-hint: [optional: version, date range, or scope]
+description: Drafts release notes or changelog entries from git history, staged diffs, or completed work items. Use this when asked to write release notes, summarize a release, prepare a changelog entry, update the changelog, publish a release summary, or turn recent commits into a structured update for users or maintainers.
+argument-hint: "[version] optional version, date range, or scope"
 ---
 
 # Release Notes

scripts/skillpack.sh

@@ -91,7 +91,7 @@ collect_skills() {
 }
 
 validate_skills() {
-  local skill_dir skill_name
+  local skill_dir skill_name declared_name name_length desc_length
 
   collect_skills
 
@@ -107,26 +107,50 @@ validate_skills() {
       echo "Missing README.md for skill: $skill_name" >&2
       exit 1
     fi
-
     if ! grep -q '^---$' "$skill_dir/SKILL.md"; then
       echo "Missing YAML frontmatter markers in $skill_name/SKILL.md" >&2
       exit 1
     fi
-
     if ! grep -q '^name:' "$skill_dir/SKILL.md"; then
       echo "Missing name field in $skill_name/SKILL.md" >&2
       exit 1
     fi
-
     if ! grep -q '^description:' "$skill_dir/SKILL.md"; then
       echo "Missing description field in $skill_name/SKILL.md" >&2
       exit 1
     fi
-
     if ! grep -q '^version:' "$skill_dir/SKILL.md"; then
       echo "Missing version field in $skill_name/SKILL.md" >&2
       exit 1
     fi
+
+    # Enforce Agent Skills spec: name must match folder name exactly
+    declared_name=$(extract_frontmatter_value "$skill_dir/SKILL.md" "name")
+    if [[ "$declared_name" != "$skill_name" ]]; then
+      echo "Name mismatch in $skill_name/SKILL.md: frontmatter declares '$declared_name' but folder is '$skill_name'" >&2
+      echo "VS Code will not load this skill until these match." >&2
+      exit 1
+    fi
+
+    # Enforce spec: name must be lowercase letters, digits, and hyphens only
+    if [[ ! "$declared_name" =~ ^[a-z0-9-]+$ ]]; then
+      echo "Invalid name '$declared_name' in $skill_name/SKILL.md: must be lowercase letters, digits, and hyphens only" >&2
+      exit 1
+    fi
+
+    # Enforce spec: name must be max 64 characters
+    name_length=${#declared_name}
+    if [[ $name_length -gt 64 ]]; then
+      echo "Name too long in $skill_name/SKILL.md: $name_length characters (max 64)" >&2
+      exit 1
+    fi
+
+    # Enforce spec: description must be max 1024 characters
+    desc_length=$(extract_frontmatter_value "$skill_dir/SKILL.md" "description" | wc -c)
+    if [[ $desc_length -gt 1024 ]]; then
+      echo "Description too long in $skill_name/SKILL.md: $desc_length characters (max 1024)" >&2
+      exit 1
+    fi
   done
 }
 
@@ -162,7 +186,7 @@ write_json_manifest() {
     printf '  "manifest_format": "json",\n'
     printf '  "source": "%s",\n' "$(json_escape "$repo_root")"
     printf '  "output": "%s",\n' "$(json_escape "$output_dir")"
-    printf '  "archive": "%s",\n' "$(json_escape "$output_dir.tar.gz")"
+    printf '  "archive": "%s",\n' "$(json_escape "$output_dir.zip")"
     printf '  "generated_at": "%s",\n' "$generated_at"
     printf '  "hash_algorithm": "sha256",\n'
     printf '  "skill_count": %s,\n' "${#skill_dirs[@]}"
@@ -282,7 +306,12 @@ else
   write_text_manifest
 fi
 
-tar -czf "$output_dir.tar.gz" -C "$(dirname "$output_dir")" "$(basename "$output_dir")"
+if ! command -v zip >/dev/null 2>&1; then
+  echo "zip is not available" >&2
+  exit 1
+fi
+
+(cd "$(dirname "$output_dir")" && zip -qr "$(basename "$output_dir").zip" "$(basename "$output_dir")")
 
 echo "Created skillpack at $output_dir"
-echo "Created archive at $output_dir.tar.gz"
+echo "Created archive at $output_dir.zip"

skill-scaffold/SKILL.md

@@ -1,8 +1,9 @@
 ---
 name: skill-scaffold
 version: 1.0.0
-description: Creates a new GitHub Copilot skill folder with a valid SKILL.md, a human-readable README.md, and an index entry in the repository root README. Use this when asked to add a new skill, scaffold a Copilot skill, document a skill folder, or expand a skill catalog repository.
-argument-hint: [optional: skill name and purpose]
+description: Creates a new GitHub Copilot skill folder with a valid SKILL.md, a human-readable README.md, and an index entry in the repository root README. Use this when asked to add a new skill, scaffold a Copilot skill, create a skill folder, bootstrap a skill, document a skill folder, or expand a skill catalog repository.
+argument-hint: "[skill-name] optional skill name and purpose"
+disable-model-invocation: true
 ---
 
 # Skill Scaffold