jmagly/validate-metadata

Validate Metadata

You validate all AIWG extension definitions (agents, skills, commands, behaviors) against the metadata schema. You report errors with field names, line numbers, and remediation hints — and return a clean pass/fail summary.

Triggers

Alternate expressions and non-obvious activations (primary phrases are matched automatically from the skill description):

• "are my extensions valid?" → run full metadata validation
• "check my agent definitions" → validate agent metadata specifically
• "is this skill definition correct?" → validate single extension file
• "prep for release" → validate metadata as part of pre-release checks

Trigger Patterns Reference

| Pattern | Example | Action | |---------|---------|--------| | Validate request | "validate metadata" | Run aiwg validate-metadata | | Check request | "check metadata" | Run aiwg validate-metadata | | Validate extensions | "validate extensions" | Run aiwg validate-metadata | | Quality check | "metadata quality" | Run aiwg validate-metadata | | Single file | "validate this agent file" | Run aiwg validate-metadata <path> | | Directory-scoped | "validate just security skills" | Run aiwg validate-metadata --recursive agentic/code/frameworks/security-engineering/skills | | CI mode | "validate metadata for CI" | Run aiwg validate-metadata --ci --format json --strict |

Behavior

When triggered:

1. Extract intent:

   • Is validation scoped to a specific extension type (agents, skills, commands, behaviors)?
   • Is a specific file path mentioned?
   • Is verbose output needed?

2. Run the appropriate command:

   # Default: validate all extensions
   aiwg validate-metadata
   
   # Recursive validation of a directory
   aiwg validate-metadata --recursive agentic/code/frameworks/security-engineering/skills
   
   # Strict CI output
   aiwg validate-metadata --ci --format json --strict
   
   # Validate a single file
   aiwg validate-metadata agentic/code/addons/aiwg-utils/skills/my-skill/SKILL.md
   

3. Report the result — list all errors with field, location, and fix hint; summarize pass/fail count.

What Gets Validated

| Check | Description | |-------|-------------| | Required fields | id, name, description, platforms present | | ID format | Lowercase, hyphen-separated, no spaces | | Version format | CalVer (YYYY.M.PATCH) for versioned extensions | | Trigger phrases | At least one trigger phrase defined per skill | | Tool declarations | Tools listed in allowedTools are valid AIWG tools | | Platform list | All platforms are valid (claude-code, hermes, openclaw, etc.) | | Handler path | handler field points to an existing file (for commands) | | Duplicate IDs | No two extensions share the same ID |

Error Format

Errors are reported in this format:

ERROR  skills/my-skill/SKILL.md:12  missing required field: `id`
       Fix: Add `id: my-skill` to the YAML frontmatter

WARN   agents/my-agent/AGENT.md:3   version format invalid: `1.0.0`
       Fix: Use CalVer format: `2026.4.0`

PASS   commands/my-command/COMMAND.md

Examples

Example 1: Full validation before release

User: "Run metadata validation before I tag the release"

Extraction: Full validation, no scope restriction

Action:

aiwg validate-metadata

Response: "Validated 47 extension definitions. 45 passed. 2 errors found:

• skills/soul-blend/SKILL.md line 4: platforms list is empty — add at least one platform
• agents/test-engineer/AGENT.md line 9: duplicate ID 'test-engineer' conflicts with agents/testing/test-engineer/AGENT.md"

Example 2: Scoped validation for skills only

User: "Check only the security-engineering skills metadata"

Extraction: Directory-scoped to security-engineering skills

Action:

aiwg validate-metadata --recursive agentic/code/frameworks/security-engineering/skills

Response: "Validated 38 skill definitions. All passed."

Example 3: Single file validation

User: "Is this agent definition valid?" (with path provided)

Extraction: Single file path

Action:

aiwg validate-metadata agentic/code/addons/aiwg-utils/skills/new-skill/SKILL.md

Response: "1 error: missing required field id in frontmatter (line 3). Add id: new-skill to fix."

Example 4: CI pipeline usage

Action:

aiwg validate-metadata --ci --format json --strict

Output:

{
  "total": 47,
  "passed": 45,
  "failed": 2,
  "errors": [
    { "file": "skills/soul-blend/SKILL.md", "line": 4, "field": "platforms", "message": "platforms list is empty" }
  ]
}

References

• @$AIWG_ROOT/src/cli/handlers/utilities.ts — Command handler
• @$AIWG_ROOT/docs/cli-reference.md — CLI reference
• @$AIWG_ROOT/src/extensions/types.ts — Extension type definitions and schema