normalize

name	normalize
description	Validate files against prompt reference guidelines Use when this capability is needed.
metadata	{"author":"e-stpierre"}

Normalize

Overview

Validate that prompt files and plugin READMEs conform to the exact structure defined in the template files. Ensures all prompt files exactly match the structure, section names, and content requirements defined in their respective templates.

Templates used for validation:

• docs/templates/agent-template.md for agents
• plugins/skill-builder/skills/create-skill/references/action-skill-template.md for skills
• docs/templates/readme-template.md for plugin READMEs

All templates use Mustache/Handlebars-style placeholders ({{placeholder_name}}) with HTML comment instructions. See CLAUDE.md section "Prompt Template Convention" for complete details.

Arguments

Definitions

• [--autofix] (optional): Automatically modify files to make them compliant with the templates. Without this flag, only reports issues.
• [paths...] (optional): One or more paths to files or directories to validate. If omitted, validates all prompt files and READMEs in the repository.

Values

Arguments: $ARGUMENTS

Core Principles

• Always read the template file to determine validation rules
• Never hardcode template requirements in this skill - defer to templates
• Templates are the single source of truth for structure and content
• Section names must match exactly (case-sensitive)
• Required sections are listed in the template header comment
• Optional sections are marked with "(optional)" in the template
• Report all issues with clear, actionable feedback
• Only modify files when --autofix flag is provided
• Preserve existing content and style when autofixing

Instructions

1. Determine Files to Validate

   If paths are provided via $ARGUMENTS:

   • For each file path: validate that file directly
   • For each directory path: find all .md files within

   If no paths provided, use a two-pass discovery approach for reliability:

   Pass 1: Gather all markdown files using broad patterns

   • plugins/**/*.md - All markdown files in plugins
   • .claude/skills/**/SKILL.md - Repository-level skills

   Pass 2: Filter and classify discovered files

   • Exclude non-prompt files: CHANGELOG.md, CLAUDE.example.md, and similar
   • Classify remaining files based on path patterns (see step 2)

   Verification: After discovery, report the total count of files found. If zero files are found when no arguments provided, warn that something may be wrong with the search.

2. Classify Each File and Load Template

   Determine the file type by checking if the file path contains these directory patterns:

   Path Contains	Type	Template to Read
   /agents/ or agents	Agent	docs/templates/agent-template.md
   /skills/ or skills	Skill	plugins/skill-builder/skills/create-skill/references/action-skill-template.md
   /hooks/ or hooks	Hook	(no template - skip validation)
   Filename is README.md	README	docs/templates/readme-template.md

   Classification rules:

   • Check path segments, not substrings (e.g., /agents/ not just agent)
   • README.md files in plugin roots are validated; README.md in subdirectories are skipped
   • Files like CHANGELOG.md, CLAUDE.example.md are skipped (not prompts)
   • If a file cannot be classified, skip it and note in the report

Output Guidance

Validate-only mode (default)

## Validation Results

### File Discovery

- Files found: 35
- Agents: 2
- Skills: 31
- READMEs: 2
- Skipped (non-prompt): 3 (CHANGELOG.md, CLAUDE.example.md, etc.)

### path/to/skill/SKILL.md (Skill)

Template: plugins/skill-builder/skills/create-skill/references/action-skill-template.md

**Frontmatter:**

- [PASS] All required fields present
- [PASS] name is kebab-case

**Structure:**

- [FAIL] Missing required section: "Output Guidance"
  Suggestion: Add section after "Instructions" section
- [FAIL] Section name mismatch: "## arguments" should be "## Arguments"

**Content:**

- [PASS] Instructions section uses numbered list
- [WARN] Description is 105 characters (recommended: under 100)

### plugins/my-plugin/README.md (README)

Template: docs/templates/readme-template.md

**Structure:**

- [PASS] All required sections present
- [WARN] "Agents" section present but plugin has no agents/ directory

## Summary

- Files checked: 32
- Passing: 29
- With issues: 3

Autofix mode (--autofix)

## Autofix Results

### File Discovery

- Files found: 35
- Agents: 2, Skills: 31, READMEs: 2
- Skipped: 3

### path/to/skill/SKILL.md (Skill)

Template: plugins/skill-builder/skills/create-skill/references/action-skill-template.md

- [FIXED] Added missing section: "Output Guidance"
- [FIXED] Renamed section: "## arguments" -> "## Arguments"
- [INFO] Preserved all existing content

## Summary

- Files checked: 35
- Files modified: 2
- Issues auto-fixed: 4
- Files now passing: 34

If all files pass validation:

## Validation Results

### File Discovery

- Files found: 35
- Agents: 2, Skills: 31, READMEs: 2
- Skipped: 3

All 35 files pass validation - 100% compliant with templates.

---

Converted and distributed by TomeVault — claim your Tome and manage your conversions.