/validate-metadata

namespace: aiwg
name: validate-metadata
platforms: [all]
description: Validate AIWG extension definitions against the metadata schema and report errors with field names, line numbers, and remediation hints

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