Aiwg validate-metadata

Validate AIWG extension definitions against the metadata schema and report errors with field names, line numbers, and remediation hints

install

source · Clone the upstream repo

git clone https://github.com/jmagly/aiwg

Claude Code · Install into ~/.claude/skills/

T=$(mktemp -d) && git clone --depth=1 https://github.com/jmagly/aiwg "$T" && mkdir -p ~/.claude/skills && cp -r "$T/.agents/skills/validate-metadata" ~/.claude/skills/jmagly-aiwg-validate-metadata && rm -rf "$T"

manifest: .agents/skills/validate-metadata/SKILL.md

source content

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>`
Type-scoped	"validate just the skills"	Run `aiwg validate-metadata --type skills`
Fix mode	"validate and report errors clearly"	Run `aiwg validate-metadata --verbose`

Behavior

When triggered:

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

Run the appropriate command:

# Default: validate all extensions
aiwg validate-metadata

# Verbose output with line numbers and hints
aiwg validate-metadata --verbose

# Scope to a specific type
aiwg validate-metadata --type agents
aiwg validate-metadata --type skills
aiwg validate-metadata --type commands
aiwg validate-metadata --type behaviors

# Validate a single file
aiwg validate-metadata agentic/code/addons/aiwg-utils/skills/my-skill/SKILL.md

# Machine-readable JSON output (for CI)
aiwg validate-metadata --json

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 --verbose

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 skills metadata"

Extraction: Type-scoped to skills

Action:

aiwg validate-metadata --type 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 --json

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