git:20260824.3b80357 to git:20260826.e9b5dac

12 added, 652 removed. Audit A to A.

---

name: validate-frontmatter

- description: "Validate and fix frontmatter consistency across all workflows"

+ description: "Validates YAML frontmatter on plugins/*/skills/*/SKILL.md and plugins/*/agents/*.md against docs/frontmatter-standard.md and .claude/rules/plugin-editing.md: required fields, the disable-model-invocation/user-invocable polarity, allowed-tools vs tools, and skill-only fields that must not leak (model, category). Use when adding or editing a skill or agent, before opening a PR that touches plugins/**, or paired with audit-references to confirm a plugin cleanup's frontmatter didn't drift."

---

# Validate Frontmatter

- You are tasked with validating frontmatter consistency across all agents and skills in the

- workspace, and fixing any issues found.

- ## Purpose

- This command ensures all workflows follow the workspace frontmatter standard, making them easier to

- maintain, discover, and integrate.

- ## Initial Response

+ Checks every skill and agent in the repo against the current frontmatter standard and reports (or fixes) drift.

- When invoked:

+ ## The standard

- ```

- I'll validate frontmatter across all workflows.

+ Field tables are the single source in [`docs/frontmatter-standard.md`](../../../../docs/frontmatter-standard.md) — don't restate them here. The skills-only shape rule (`no commands/ directories — skills only`) is in [`.claude/rules/plugin-editing.md`](../../../../.claude/rules/plugin-editing.md).

- Checking:

- - agents/ directory

- - skills/ directory

+ ## The rule everyone gets backwards

- What would you like to do?

- 1. Validate all workflows (report issues only)

- 2. Validate and auto-fix issues

- 3. Validate specific workflow

- 4. Generate frontmatter standard document

- ```

+ `disable-model-invocation: true` marks a **user-invoked** skill — a human runs it explicitly via `/plugin:skill`, and the model is *disabled* from auto-triggering it off its description. `user-invocable: false` (a different key) marks a CI/background skill nobody explicitly invokes. Getting this backwards tells authors to set every user-invoked skill to the value that lets the model auto-trigger it — the opposite of what "user-invoked" means. Full table: [references/checklist.md](references/checklist.md).

## Process

- ### Step 1: Determine Scope

- Get user selection:

- - **All workflows**: Check everything

- - **Auto-fix**: Fix issues automatically

- - **Specific workflow**: Validate one file

- - **Generate standard**: Create reference document

- ### Step 2: Parallel Validation

- **IMPORTANT**: Spawn parallel validation tasks for efficiency.

- Use TodoWrite to track parallel validation tasks.

- **For "Validate All" mode**:

- **Task 1 - Validate Agents**:

- ```

- Use codebase-analyzer agent:

- "Validate frontmatter in all files matching agents/*.md. For each file, check:

- 1. Required fields present (name, description, tools, model, version)

- 2. Name field matches filename (kebab-case)

- 3. Tools list contains valid Claude Code tools

- 4. Category is one of: research, analysis, search, execution, validation, general

- 5. Version follows semver (e.g., 1.0.0)

- 6. Description is clear and informative

- Return: List of all validation issues found with file:line references"

- Tools: Glob, Grep, Read

- Path: $(git rev-parse --show-toplevel)/plugins/*/agents/

- Return: Validation report for all agents

- ```

- **Task 2 - Validate Skills**:

- ```

- Use codebase-analyzer agent:

- "Validate frontmatter in all files matching skills/*/SKILL.md. For each file, check:

- 1. Required fields present (name, description)

- 2. User-invoked skills have disable-model-invocation: false

- 3. CI/background skills have user-invocable: false

- 4. Uses allowed-tools (not tools) for tool restrictions

- 5. Does NOT include model or category in frontmatter

- 6. Description is clear and concise

- Return: List of all validation issues found with file:line references"

- Tools: Glob, Grep, Read

- Path: $(git rev-parse --show-toplevel)/plugins/*/skills/

- Return: Validation report for all skills

- ```

- **Task 3 - Extract Tool References**:

- ```

- Use codebase-pattern-finder agent:

- "Extract all unique tool names referenced in frontmatter across plugins/*/agents/*.md and plugins/*/skills/*/SKILL.md. Return a sorted list of all tools used."

- Tools: Glob, Grep

- Path: $(git rev-parse --show-toplevel)/plugins/

- Return: Complete list of tools referenced

- ```

- **WAIT for all 3 tasks to complete.**

- ### Step 3: Aggregate Validation Results

- Combine results from parallel tasks:

- - Agent issues (Task 1)

- - Skill issues (Task 2)

- - Tool inventory (Task 3)

- Mark all tasks complete in TodoWrite.

- Analyze:

- 1. **Critical issues**: Missing required fields, invalid formats

- 2. **Warnings**: Unusual patterns, potential improvements

- 3. **Tool usage**: Are all tools valid?

- 4. **Category distribution**: Are categories being used correctly?

- ### Step 4: Present Validation Report

- Show comprehensive report:

- ```markdown

- # Frontmatter Validation Report

- **Validated**: {date} **Scope**: {agents-count} agents, {skills-count} skills **Status**:

- {PASS/FAIL}

- ## Summary

- - ✅ **Passed**: {pass-count} workflows

- - ⚠️ **Warnings**: {warning-count} workflows

- - ❌ **Failed**: {fail-count} workflows

- ## Critical Issues

- ### {workflow-name}.md

- - ❌ Missing required field: `version`

- - ❌ Invalid category: "misc" (should be one of: general, research, analysis...)

- ### {workflow-name}.md

- - ❌ Name field "{name}" doesn't match filename "{filename}"

- - ❌ Invalid tool reference: "SearchFiles" (not a valid Claude Code tool)

- ## Warnings

- ### {workflow-name}.md

- - ⚠️ Description is very short (< 20 chars)

- - ⚠️ No category specified (defaulting to "general")

- ### {workflow-name}.md

- - ⚠️ Using old version format: "v1.0" (should be "1.0.0")

- ## Tool Inventory

- **Total unique tools**: {tool-count} **Valid tools**: {valid-count} **Invalid references**:

- {invalid-count}

- ### Used Tools:

- - Read ({usage-count} workflows)

- - Write ({usage-count} workflows)

- - Edit ({usage-count} workflows)

- - Grep ({usage-count} workflows)

- - Glob ({usage-count} workflows) [... more tools ...]

- ### Invalid References:

- - SearchFiles (used in {workflow-name}.md) → Should be: Grep or Glob

- - FindFile (used in {workflow-name}.md) → Should be: Glob

- ## Category Distribution

- ### Agents:

- - research: {count}

- - analysis: {count}

- - search: {count}

- - execution: {count}

- - validation: {count}

- - general: {count}

- ### Commands:

- - workflow: {count}

- - planning: {count}

- - implementation: {count}

- - validation: {count}

- - linear: {count}

- - git: {count}

- - workflow-discovery: {count}

- - general: {count}

- ## Recommendations

- 1. **Fix critical issues first**: {count} workflows need immediate attention

- 2. **Standardize versions**: {count} workflows use non-semver format

- 3. **Update tool references**: {count} invalid tool names found

- 4. **Add descriptions**: {count} workflows have minimal descriptions

- ---

- Next steps:

- - Run with `--fix` to auto-correct issues

- - Review and approve fixes before applying

- - Re-validate after fixes

- ```

- ### Step 5: Auto-Fix Mode (if requested)

- If user chose auto-fix:

- 1. **Create fix plan**:

- - List all fixable issues

- - Show what will be changed

- - Ask for confirmation

- 2. **Present fix plan**:

- ```markdown

- # Auto-Fix Plan

- I can automatically fix {fixable-count} issues:

- ## {workflow-name}.md

- - Add missing `version: 1.0.0`

- - Fix category: "misc" → "general"

- - Standardize tool name: "SearchFiles" → "Grep"

- ## {workflow-name}.md

- - Fix version format: "v1.0" → "1.0.0"

- - Add missing `model: inherit`

- **Cannot auto-fix** ({manual-count} issues):

- - {workflow-name}.md: Description too short (needs human review)

- - {workflow-name}.md: Unclear category (analysis vs research?)

- Proceed with auto-fix? (Y/n)

- ```

- 3. **Apply fixes** (after confirmation):

- - Use Edit tool to fix each issue

- - Track all changes made

- - Preserve original formatting and comments

- 4. **Report results**:

- ```markdown

- ✅ Auto-fix complete!

- **Fixed**: {fixed-count} issues across {file-count} files

- ### Changes Made:

- #### agents/codebase-locator.md

- - Added `version: 1.0.0`

- - Standardized category: "search"

- #### skills/create_plan/SKILL.md

- - Fixed version: "v1.0" → "1.0.0"

- - Updated tool reference: "SearchFiles" → "Grep"

- [... more changes ...]

- **Still needs manual review**:

- - {workflow-name}.md: {issue description}

- Re-run validation to verify: `/catalyst-meta:validate-frontmatter`

- ```

- ### Step 6: Generate Standard Document (if requested)

- If user chose to generate standard:

- Create `docs/frontmatter-standard.md`:

- ````markdown

- # Frontmatter Standard

- This document defines the frontmatter standard for all agents and commands in this workspace.

- ## Agent Frontmatter

- ### Required Fields

- ```yaml

- ---

- name: { agent-name } # Agent identifier (kebab-case, must match filename)

- description: | # Multi-line description

- {What this agent does}

- Use this agent when:

- - {Use case 1}

- - {Use case 2}

- tools: { tool-list } # Array of Claude Code tools

- model: inherit # Always "inherit"

- category: { category } # One of: research, analysis, search, execution, validation, general

- version: 1.0.0 # Semantic version

- ---

- ```

- ````

- ### Optional Fields

- ```yaml

- source: { repo-url } # If imported/adapted

- adapted: { date } # Date of adaptation

- original-author: { name } # Original creator

- ```

- ### Valid Categories

- - **research**: Finding and gathering information

- - **analysis**: Deep code/data analysis

- - **search**: Locating files/patterns/content

- - **execution**: Running commands/operations

- - **validation**: Checking and verifying

- - **general**: Multi-purpose or uncategorized

- ### Example

- ```yaml

- ---

- name: codebase-analyzer

- description: |

- Analyzes codebases to understand implementation details and patterns.

- Use this agent when:

- - You need to understand how a feature is implemented

- - You want to trace data flow through the system

- - You need to find patterns and conventions

- tools: Read, Grep, Glob

- model: inherit

- category: analysis

- version: 1.0.0

- ---

- ```

- ## Command Frontmatter

- ### Required Fields

- ```yaml

- ---

- description: { one-line-summary } # Brief description (no name field!)

- category: { category } # Command category

- tools: { tool-list } # Array of Claude Code tools

- model: inherit # Always "inherit"

- version: 1.0.0 # Semantic version

- ---

- ```

- ### Optional Fields

- ```yaml

- argument-hint: { hint } # Hint for command arguments

- source: { repo-url } # If imported/adapted

- adapted: { date } # Date of adaptation

- original-author: { name } # Original creator

- ```

- ### Valid Categories

- - **workflow**: Development workflows

- - **planning**: Planning and design

- - **implementation**: Code changes

- - **validation**: Testing and verification

- - **linear**: Linear integration

- - **git**: Version control

- - **workflow-discovery**: Meta-workflows

- - **general**: Miscellaneous

- ### Example

- ```yaml

- ---

- description: Create detailed implementation plans through interactive process

- category: planning

- argument-hint: [ticket-file | ticket-reference]

- tools: Read, Write, Edit, Grep, Glob, Task, TodoWrite

- model: inherit

- version: 1.0.0

- ---

- ```

- ## Valid Tools

- Claude Code provides these tools:

- ### File Operations

- - `Read` - Read file contents

- - `Write` - Write files

- - `Edit` - Edit existing files

- ### Search

- - `Grep` - Search file contents (regex)

- - `Glob` - Find files by pattern

- ### Execution

- - `Bash` - Run shell commands

- - `Task` - Spawn sub-agents

- ### Management

- - `TodoWrite` - Manage todo lists

- ### External

- - `WebFetch` - Fetch web content

- - `WebSearch` - Search the web

- ### Code Understanding (Serena MCP)

- - `mcp__serena__activate_project` - Activate the repo so language servers target it

- - `mcp__serena__list_memories` / `mcp__serena__read_memory` - Read persisted project orientation

- - `mcp__serena__get_symbols_overview` - Map a file's top-level symbols

- - `mcp__serena__find_symbol` - Jump to a symbol's definition (semantic, not grep)

- - `mcp__serena__find_referencing_symbols` - Find callers/references of a symbol

- - `mcp__serena__search_for_pattern` / `mcp__serena__find_file` / `mcp__serena__list_dir` - Search/list

- ### Linear Integration

- - `linear_get_ticket` - Get Linear ticket details

- - `linear_create_ticket` - Create Linear tickets

- - `linear_update_ticket` - Update Linear tickets

- (Check official Claude Code docs for complete list)

- ## Validation Rules

- ### All Workflows

- 1. **Required fields must be present**

- 2. **Version must follow semver**: `X.Y.Z` (not `vX.Y`)

- 3. **Model must be "inherit"** (unless specific reason)

- 4. **Tools must be valid Claude Code tools**

- 5. **Category must be from valid list**

- ### Agents Specifically

- 1. **Must have `name` field** matching filename

- 2. **Name must be kebab-case**

- 3. **Description should be multi-line with use cases**

- ### Commands Specifically

- 1. **Must NOT have `name` field** (use filename)

- 2. **Description should be one-line summary**

- 3. **Use `argument-hint` if command takes arguments**

- ## Common Mistakes

- ### ❌ Wrong: Command with name field

- ```yaml

- ---

- name: create-plan # Commands don't have name field

- description: Create plans

- ---

- ```

- ### ✅ Correct: Command without name

- ```yaml

- ---

- description: Create detailed implementation plans

- category: planning

- ---

- ```

- ### ❌ Wrong: Invalid tool reference

- ```yaml

- tools: SearchFiles, FindFile # These aren't real tools

- ```

- ### ✅ Correct: Valid tools

- ```yaml

- tools: Grep, Glob # Correct tool names

- ```

- ### ❌ Wrong: Version format

- ```yaml

- version: v1.0 # Should be semver

- ```

- ### ✅ Correct: Semver version

- ```yaml

- version: 1.0.0 # Proper semver

- ```

- ## Updating the Standard

- When adding new categories or patterns:

- 1. Update this document

- 2. Validate all existing workflows

- 3. Fix any inconsistencies

- 4. Document the change in git commit

- ## See Also

- - `/catalyst-meta:validate-frontmatter` - Validate workflows against this standard

- - `/catalyst-meta:create-workflow` - Create new workflows with correct frontmatter

- - `/catalyst-meta:import-workflow` - Import external workflows and adapt frontmatter

- ```

- Save and report:

- ```

- ✅ Frontmatter standard documented!

- **Saved to**: docs/frontmatter-standard.md

- This document now serves as the canonical reference for all frontmatter in this workspace.

- Next steps:

- 1. Review the standard

- 2. Share with team

- 3. Use `/catalyst-meta:validate-frontmatter` to check compliance

- 4. Reference when creating new workflows

- ```

- ## Advanced Usage

- ### Validate Specific Workflow

- ```

- /catalyst-meta:validate-frontmatter agents/codebase-analyzer.md

- ```

- Validates just one file.

- ### Auto-Fix Everything

- ```

- /catalyst-meta:validate-frontmatter --fix

- ```

- Automatically fixes all issues without prompting.

- ### Generate Report Only

- ```

- /catalyst-meta:validate-frontmatter --report-only > frontmatter-report.md

- ```

- Saves report to file for review.

- ### Validate by Category

- ```

- /catalyst-meta:validate-frontmatter --category research

- ```

- Only validates workflows in "research" category.

- ## Validation Categories

- ### Critical Issues (Must Fix)

- - Missing required fields

- - Invalid field values

- - Name/filename mismatch (agents)

- - Invalid tool references

- - Malformed YAML

- ### Warnings (Should Fix)

- - Short descriptions (< 20 chars)

- - Missing optional but recommended fields

- - Unusual category choices

- - Non-standard patterns

- ### Info (Nice to Have)

- - Could add more detail

- - Could specify argument-hint

- - Could add source attribution

- - Could improve formatting

- ## Auto-Fix Capabilities

- ### What Can Be Auto-Fixed

- ✅ Missing version field → Add `version: 1.0.0`

- ✅ Wrong version format → Convert to semver

- ✅ Missing model field → Add `model: inherit`

- ✅ Common tool typos → Fix to correct names

- ✅ Category typos → Fix to valid category

- ✅ YAML formatting → Standardize indentation

- ### What Requires Manual Review

- ❌ Ambiguous categories → Needs human judgment

- ❌ Short descriptions → Needs content creation

- ❌ Complex tool issues → May need workflow redesign

- ❌ Missing description → Needs understanding of purpose

- ## Important Notes

- - **Non-destructive**: Auto-fix preserves content, only fixes frontmatter

- - **Safe**: Always shows plan before applying fixes

- - **Trackable**: Reports all changes made

- - **Reversible**: Changes are standard edits, can be reverted via git

- - **Standard-based**: Uses workspace-specific conventions

- ## Integration with Other Commands

- - **Discover**: `/catalyst-meta:discover-workflows` → uses this for validation

- - **Import**: `/catalyst-meta:import-workflow` → validates imported workflows

- - **Create**: `/catalyst-meta:create-workflow` → ensures new workflows are valid

- - **Validate**: `/catalyst-meta:validate-frontmatter` (this command) → checks everything

- ## Error Handling

- ### Malformed YAML

- - Report syntax errors

- - Show line number

- - Suggest fixes

- - Cannot auto-fix (manual correction needed)

- ### Unknown Fields

- - Report unexpected fields

- - Ask: Keep / Remove?

- - Could be custom extensions

- ### Missing Files

- - Skip files that don't exist

- - Report which files were skipped

- - Continue validation

+ 1. **Glob** `plugins/*/skills/*/SKILL.md` and `plugins/*/agents/*.md`.

+ 2. For each skill: required fields present; `disable-model-invocation`/`user-invocable` polarity matches how it's actually invoked; `allowed-tools` used (never bare `tools`); no `model` or `category` field (skills-only prohibition — agents may carry either).

+ 3. For each agent: `name`, `description`, `tools` present; `name` matches the filename (kebab-case).

+ 4. Report issues grouped by file. For mechanically safe fixes (`tools:` → `allowed-tools:` rename, `vX.Y` → semver, a missing `version: 1.0.0`), propose the edit and apply with `Edit` after confirmation. Never auto-fix `disable-model-invocation`/`user-invocable` or `description` — both need a human call on intent. Full catalogue: [references/checklist.md](references/checklist.md).

- ### Permission Errors

- - Report read/write issues

- - Skip files that can't be accessed

- - Provide error details

+ ## Pairs with audit-references

- This command ensures workspace consistency and quality!

- ```

+ After a plugin-wide cleanup (skill removals, shape rewrites), run this alongside `/catalyst-meta:audit-references` — that catches broken path references, this catches frontmatter a cleanup left inconsistent (a rewrite that forgot to drop a stray `category` field, or flipped `disable-model-invocation` the wrong way).