Add CI workflow to validate YAML frontmatter in PRs

Adds a GitHub Actions workflow that validates frontmatter in agent,
skill, and command .md files changed by a PR. Checks:

- Agents: name and description are present and parseable
- Skills: description is present (required for Skill tool discovery)
- Commands: description is present and parseable

The workflow only runs when PRs touch files in agents/, skills/, or
commands/ directories, and only validates the changed files.

.github/scripts/validate-frontmatter.ts

@@ -0,0 +1,273 @@
+#!/usr/bin/env bun
+/**
+ * Validates YAML frontmatter in agent, skill, and command .md files.
+ *
+ * Usage:
+ *   bun validate-frontmatter.ts                    # scan current directory
+ *   bun validate-frontmatter.ts /path/to/dir       # scan specific directory
+ *   bun validate-frontmatter.ts file1.md file2.md  # validate specific files
+ */
+
+import { parse as parseYaml } from "yaml";
+import { readdir, readFile } from "fs/promises";
+import { basename, join, relative, resolve } from "path";
+
+// Characters that require quoting in YAML values when unquoted:
+// {} [] flow indicators, * anchor/alias, & anchor, # comment,
+// ! tag, | > block scalars, % directive, @ ` reserved
+const YAML_SPECIAL_CHARS = /[{}[\]*&#!|>%@`]/;
+const FRONTMATTER_REGEX = /^---\s*\n([\s\S]*?)---\s*\n?/;
+
+/**
+ * Pre-process frontmatter text to quote values containing special YAML
+ * characters. This allows glob patterns like **\/*.{ts,tsx} to parse.
+ */
+function quoteSpecialValues(text: string): string {
+  const lines = text.split("\n");
+  const result: string[] = [];
+
+  for (const line of lines) {
+    const match = line.match(/^([a-zA-Z_-]+):\s+(.+)$/);
+    if (match) {
+      const [, key, value] = match;
+      if (!key || !value) {
+        result.push(line);
+        continue;
+      }
+      // Skip already-quoted values
+      if (
+        (value.startsWith('"') && value.endsWith('"')) ||
+        (value.startsWith("'") && value.endsWith("'"))
+      ) {
+        result.push(line);
+        continue;
+      }
+      if (YAML_SPECIAL_CHARS.test(value)) {
+        const escaped = value.replace(/\\/g, "\\\\").replace(/"/g, '\\"');
+        result.push(`${key}: "${escaped}"`);
+        continue;
+      }
+    }
+    result.push(line);
+  }
+
+  return result.join("\n");
+}
+
+interface ParseResult {
+  frontmatter: Record<string, unknown>;
+  content: string;
+  error?: string;
+}
+
+function parseFrontmatter(markdown: string): ParseResult {
+  const match = markdown.match(FRONTMATTER_REGEX);
+
+  if (!match) {
+    return {
+      frontmatter: {},
+      content: markdown,
+      error: "No frontmatter found",
+    };
+  }
+
+  const frontmatterText = quoteSpecialValues(match[1] || "");
+  const content = markdown.slice(match[0].length);
+
+  try {
+    const parsed = parseYaml(frontmatterText);
+    if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
+      return { frontmatter: parsed as Record<string, unknown>, content };
+    }
+    return {
+      frontmatter: {},
+      content,
+      error: `YAML parsed but result is not an object (got ${typeof parsed}${Array.isArray(parsed) ? " array" : ""})`,
+    };
+  } catch (err) {
+    return {
+      frontmatter: {},
+      content,
+      error: `YAML parse failed: ${err instanceof Error ? err.message : err}`,
+    };
+  }
+}
+
+// --- Validation ---
+
+type FileType = "agent" | "skill" | "command";
+
+interface ValidationIssue {
+  level: "error" | "warning";
+  message: string;
+}
+
+function validateAgent(
+  frontmatter: Record<string, unknown>
+): ValidationIssue[] {
+  const issues: ValidationIssue[] = [];
+
+  if (!frontmatter["name"] || typeof frontmatter["name"] !== "string") {
+    issues.push({ level: "error", message: 'Missing required "name" field' });
+  }
+  if (
+    !frontmatter["description"] ||
+    typeof frontmatter["description"] !== "string"
+  ) {
+    issues.push({
+      level: "error",
+      message: 'Missing required "description" field',
+    });
+  }
+
+  return issues;
+}
+
+function validateSkill(
+  frontmatter: Record<string, unknown>
+): ValidationIssue[] {
+  const issues: ValidationIssue[] = [];
+
+  if (!frontmatter["description"] && !frontmatter["when_to_use"]) {
+    issues.push({
+      level: "error",
+      message: 'Missing required "description" field',
+    });
+  }
+
+  return issues;
+}
+
+function validateCommand(
+  frontmatter: Record<string, unknown>
+): ValidationIssue[] {
+  const issues: ValidationIssue[] = [];
+
+  if (
+    !frontmatter["description"] ||
+    typeof frontmatter["description"] !== "string"
+  ) {
+    issues.push({
+      level: "error",
+      message: 'Missing required "description" field',
+    });
+  }
+
+  return issues;
+}
+
+// --- File type detection ---
+
+function detectFileType(filePath: string): FileType | null {
+  if (filePath.includes("/agents/")) return "agent";
+  if (filePath.includes("/skills/") && basename(filePath) === "SKILL.md")
+    return "skill";
+  if (filePath.includes("/commands/")) return "command";
+  return null;
+}
+
+// --- File discovery ---
+
+async function findMdFiles(
+  baseDir: string
+): Promise<{ path: string; type: FileType }[]> {
+  const results: { path: string; type: FileType }[] = [];
+
+  async function walk(dir: string) {
+    const entries = await readdir(dir, { withFileTypes: true });
+    for (const entry of entries) {
+      const fullPath = join(dir, entry.name);
+      if (entry.isDirectory()) {
+        await walk(fullPath);
+      } else if (entry.name.endsWith(".md")) {
+        const type = detectFileType(fullPath);
+        if (type) {
+          results.push({ path: fullPath, type });
+        }
+      }
+    }
+  }
+
+  await walk(baseDir);
+  return results;
+}
+
+// --- Main ---
+
+async function main() {
+  const args = process.argv.slice(2);
+
+  let files: { path: string; type: FileType }[];
+  let baseDir: string;
+
+  if (args.length > 0 && args.every((a) => a.endsWith(".md"))) {
+    baseDir = process.cwd();
+    files = [];
+    for (const arg of args) {
+      const fullPath = resolve(arg);
+      const type = detectFileType(fullPath);
+      if (type) {
+        files.push({ path: fullPath, type });
+      }
+    }
+  } else {
+    baseDir = args[0] || process.cwd();
+    files = await findMdFiles(baseDir);
+  }
+
+  let totalErrors = 0;
+  let totalWarnings = 0;
+
+  console.log(`Validating ${files.length} frontmatter files...\n`);
+
+  for (const { path: filePath, type } of files) {
+    const rel = relative(baseDir, filePath);
+    const content = await readFile(filePath, "utf-8");
+    const result = parseFrontmatter(content);
+
+    const issues: ValidationIssue[] = [];
+
+    if (result.error) {
+      issues.push({ level: "error", message: result.error });
+    }
+
+    if (!result.error) {
+      switch (type) {
+        case "agent":
+          issues.push(...validateAgent(result.frontmatter));
+          break;
+        case "skill":
+          issues.push(...validateSkill(result.frontmatter));
+          break;
+        case "command":
+          issues.push(...validateCommand(result.frontmatter));
+          break;
+      }
+    }
+
+    if (issues.length > 0) {
+      console.log(`${rel} (${type})`);
+      for (const issue of issues) {
+        const prefix = issue.level === "error" ? "  ERROR" : "  WARN ";
+        console.log(`${prefix}: ${issue.message}`);
+        if (issue.level === "error") totalErrors++;
+        else totalWarnings++;
+      }
+      console.log();
+    }
+  }
+
+  console.log("---");
+  console.log(
+    `Validated ${files.length} files: ${totalErrors} errors, ${totalWarnings} warnings`
+  );
+
+  if (totalErrors > 0) {
+    process.exit(1);
+  }
+}
+
+main().catch((err) => {
+  console.error("Fatal error:", err);
+  process.exit(2);
+});

.github/workflows/validate-frontmatter.yml

@@ -0,0 +1,34 @@
+name: Validate Frontmatter
+
+on:
+  pull_request:
+    paths:
+      - '**/agents/*.md'
+      - '**/skills/*/SKILL.md'
+      - '**/commands/*.md'
+
+jobs:
+  validate:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: oven-sh/setup-bun@v2
+
+      - name: Install dependencies
+        run: cd .github/scripts && bun install yaml
+
+      - name: Get changed frontmatter files
+        id: changed
+        run: |
+          FILES=$(gh pr diff ${{ github.event.pull_request.number }} --name-only | grep -E '(agents/.*\.md|skills/.*/SKILL\.md|commands/.*\.md)$' || true)
+          echo "files<<EOF" >> "$GITHUB_OUTPUT"
+          echo "$FILES" >> "$GITHUB_OUTPUT"
+          echo "EOF" >> "$GITHUB_OUTPUT"
+        env:
+          GH_TOKEN: ${{ github.token }}
+
+      - name: Validate frontmatter
+        if: steps.changed.outputs.files != ''
+        run: |
+          echo "${{ steps.changed.outputs.files }}" | xargs bun .github/scripts/validate-frontmatter.ts

plugins/hookify/skills/writing-rules/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: writing-hookify-rules
+name: Writing Hookify Rules
 description: This skill should be used when the user asks to "create a hookify rule", "write a hook rule", "configure hookify", "add a hookify rule", or needs guidance on hookify rule syntax and patterns.
 version: 0.1.0
 ---

plugins/plugin-dev/README.md

@@ -6,13 +6,13 @@ A comprehensive toolkit for developing Claude Code plugins with expert guidance
 
 The plugin-dev toolkit provides seven specialized skills to help you build high-quality Claude Code plugins:
 
-1. **hook-development** - Advanced hooks API and event-driven automation
-2. **mcp-integration** - Model Context Protocol server integration
-3. **plugin-structure** - Plugin organization and manifest configuration
-4. **plugin-settings** - Configuration patterns using .claude/plugin-name.local.md files
-5. **command-development** - Creating slash commands with frontmatter and arguments
-6. **agent-development** - Creating autonomous agents with AI-assisted generation
-7. **skill-development** - Creating skills with progressive disclosure and strong triggers
+1. **Hook Development** - Advanced hooks API and event-driven automation
+2. **MCP Integration** - Model Context Protocol server integration
+3. **Plugin Structure** - Plugin organization and manifest configuration
+4. **Plugin Settings** - Configuration patterns using .claude/plugin-name.local.md files
+5. **Command Development** - Creating slash commands with frontmatter and arguments
+6. **Agent Development** - Creating autonomous agents with AI-assisted generation
+7. **Skill Development** - Creating skills with progressive disclosure and strong triggers
 
 Each skill follows best practices with progressive disclosure: lean core documentation, detailed references, working examples, and utility scripts.
 
@@ -53,7 +53,7 @@ Use this workflow for structured, high-quality plugin development from concept t
 
 ## Skills
 
-### 1. hook-development
+### 1. Hook Development
 
 **Trigger phrases:** "create a hook", "add a PreToolUse hook", "validate tool use", "implement prompt-based hooks", "${CLAUDE_PLUGIN_ROOT}", "block dangerous commands"
 
@@ -73,7 +73,7 @@ Use this workflow for structured, high-quality plugin development from concept t
 
 **Use when:** Creating event-driven automation, validating operations, or enforcing policies in your plugin.
 
-### 2. mcp-integration
+### 2. MCP Integration
 
 **Trigger phrases:** "add MCP server", "integrate MCP", "configure .mcp.json", "Model Context Protocol", "stdio/SSE/HTTP server", "connect external service"
 
@@ -92,7 +92,7 @@ Use this workflow for structured, high-quality plugin development from concept t
 
 **Use when:** Integrating external services, APIs, databases, or tools into your plugin.
 
-### 3. plugin-structure
+### 3. Plugin Structure
 
 **Trigger phrases:** "plugin structure", "plugin.json manifest", "auto-discovery", "component organization", "plugin directory layout"
 
@@ -111,7 +111,7 @@ Use this workflow for structured, high-quality plugin development from concept t
 
 **Use when:** Starting a new plugin, organizing components, or configuring the plugin manifest.
 
-### 4. plugin-settings
+### 4. Plugin Settings
 
 **Trigger phrases:** "plugin settings", "store plugin configuration", ".local.md files", "plugin state files", "read YAML frontmatter", "per-project plugin settings"
 
@@ -132,7 +132,7 @@ Use this workflow for structured, high-quality plugin development from concept t
 
 **Use when:** Making plugins configurable, storing per-project state, or implementing user preferences.
 
-### 5. command-development
+### 5. Command Development
 
 **Trigger phrases:** "create a slash command", "add a command", "command frontmatter", "define command arguments", "organize commands"
 
@@ -151,7 +151,7 @@ Use this workflow for structured, high-quality plugin development from concept t
 
 **Use when:** Creating slash commands, defining command arguments, or organizing plugin commands.
 
-### 6. agent-development
+### 6. Agent Development
 
 **Trigger phrases:** "create an agent", "add an agent", "write a subagent", "agent frontmatter", "when to use description", "agent examples", "autonomous agent"
 
@@ -172,7 +172,7 @@ Use this workflow for structured, high-quality plugin development from concept t
 
 **Use when:** Creating autonomous agents, defining agent behavior, or implementing AI-assisted agent generation.
 
-### 7. skill-development
+### 7. Skill Development
 
 **Trigger phrases:** "create a skill", "add a skill to plugin", "write a new skill", "improve skill description", "organize skill content"
 
@@ -286,11 +286,11 @@ The hook-development skill includes production-ready utilities:
 ### Working Examples
 
 Every skill provides working examples:
-- **hook-development**: 3 complete hook scripts (bash, write validation, context loading)
-- **mcp-integration**: 3 server configurations (stdio, SSE, HTTP)
-- **plugin-structure**: 3 plugin layouts (minimal, standard, advanced)
-- **plugin-settings**: 3 examples (read-settings hook, create-settings command, templates)
-- **command-development**: 10 complete command examples (review, test, deploy, docs, etc.)
+- **Hook Development**: 3 complete hook scripts (bash, write validation, context loading)
+- **MCP Integration**: 3 server configurations (stdio, SSE, HTTP)
+- **Plugin Structure**: 3 plugin layouts (minimal, standard, advanced)
+- **Plugin Settings**: 3 examples (read-settings hook, create-settings command, templates)
+- **Command Development**: 10 complete command examples (review, test, deploy, docs, etc.)
 
 ## Documentation Standards
 

plugins/plugin-dev/skills/agent-development/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: agent-development
+name: Agent Development
 description: This skill should be used when the user asks to "create an agent", "add an agent", "write a subagent", "agent frontmatter", "when to use description", "agent examples", "agent tools", "agent colors", "autonomous agent", or needs guidance on agent structure, system prompts, triggering conditions, or agent development best practices for Claude Code plugins.
 version: 0.1.0
 ---

plugins/plugin-dev/skills/command-development/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: command-development
+name: Command Development
 description: This skill should be used when the user asks to "create a slash command", "add a command", "write a custom command", "define command arguments", "use command frontmatter", "organize commands", "create command with file references", "interactive command", "use AskUserQuestion in command", or needs guidance on slash command structure, YAML frontmatter fields, dynamic arguments, bash execution in commands, user interaction patterns, or command development best practices for Claude Code.
 version: 0.2.0
 ---

plugins/plugin-dev/skills/hook-development/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: hook-development
+name: Hook Development
 description: This skill should be used when the user asks to "create a hook", "add a PreToolUse/PostToolUse/Stop hook", "validate tool use", "implement prompt-based hooks", "use ${CLAUDE_PLUGIN_ROOT}", "set up event-driven automation", "block dangerous commands", or mentions hook events (PreToolUse, PostToolUse, Stop, SubagentStop, SessionStart, SessionEnd, UserPromptSubmit, PreCompact, Notification). Provides comprehensive guidance for creating and implementing Claude Code plugin hooks with focus on advanced prompt-based hooks API.
 version: 0.1.0
 ---

plugins/plugin-dev/skills/mcp-integration/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: mcp-integration
+name: MCP Integration
 description: This skill should be used when the user asks to "add MCP server", "integrate MCP", "configure MCP in plugin", "use .mcp.json", "set up Model Context Protocol", "connect external service", mentions "${CLAUDE_PLUGIN_ROOT} with MCP", or discusses MCP server types (SSE, stdio, HTTP, WebSocket). Provides comprehensive guidance for integrating Model Context Protocol servers into Claude Code plugins for external tool and service integration.
 version: 0.1.0
 ---

plugins/plugin-dev/skills/plugin-settings/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: plugin-settings
+name: Plugin Settings
 description: This skill should be used when the user asks about "plugin settings", "store plugin configuration", "user-configurable plugin", ".local.md files", "plugin state files", "read YAML frontmatter", "per-project plugin settings", or wants to make plugin behavior configurable. Documents the .claude/plugin-name.local.md pattern for storing plugin-specific configuration with YAML frontmatter and markdown content.
 version: 0.1.0
 ---

plugins/plugin-dev/skills/plugin-structure/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: plugin-structure
+name: Plugin Structure
 description: This skill should be used when the user asks to "create a plugin", "scaffold a plugin", "understand plugin structure", "organize plugin components", "set up plugin.json", "use ${CLAUDE_PLUGIN_ROOT}", "add commands/agents/skills/hooks", "configure auto-discovery", or needs guidance on plugin directory layout, manifest configuration, component organization, file naming conventions, or Claude Code plugin architecture best practices.
 version: 0.1.0
 ---

plugins/plugin-dev/skills/skill-development/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: skill-development
+name: Skill Development
 description: This skill should be used when the user wants to "create a skill", "add a skill to plugin", "write a new skill", "improve skill description", "organize skill content", or needs guidance on skill structure, progressive disclosure, or skill development best practices for Claude Code plugins.
 version: 0.1.0
 ---