validate-component

namespace	aiwg
name	validate-component
description	Validate a single AIWG component (skill, agent, or command) for completeness and correctness
platforms	["all"]

Validate Component

You check a single AIWG component — a skill, agent, or CLI command — for completeness and correctness, then produce a structured pass/fail report with specific gaps listed.

Triggers

• "validate this skill" → check the skill in the current directory or named path
• "is this component complete" → run completeness check
• "check this agent" → validate agent frontmatter and manifest registration
• "validate component at " → validate the named path
• "is this command wired up correctly" → check CLI command completeness
• "pre-PR check on this skill" → run validate-component

Trigger Patterns Reference

Pattern	Example	Action
Validate skill	"validate this skill"	Run skill completeness checks
Validate agent	"check this agent definition"	Run agent completeness checks
Validate command	"is this command wired up"	Run command completeness checks
Path-specific	"validate component at agentic/code/addons/my-addon/skills/my-skill"	Validate at given path
Pre-PR	"pre-PR check on this component"	Run all applicable checks

Process

1. Identify component type and path:

   • If no path is given, check the current working directory or the most recently edited file
   • Detect type from directory structure:
     • Path contains skills/<name>/SKILL.md → skill
     • Path contains agents/<name>.md or agents/<name>/ → agent
     • Component name appears in src/extensions/commands/definitions.ts → command

2. Run type-appropriate checks:

   For a Skill:

   • Read the SKILL.md file
   • Check: description: field present in YAML frontmatter
   • Check: # Title section present
   • Check: ## Behavior or ## Process section present
   • Check: At least one ## Examples entry
   • Find the parent addon's manifest.json (walk up directory tree)
   • Check: Skill name listed in manifest.json skills array
   • Check: File lives in agentic/code/ (not in a provider deployment directory)
   • If SKILL.md contains executedViaSkillRunner: true reference: check for circular CLI call pattern
   • Full link classification check (see Link Classification below)

   For an Agent:

   • Read the agent .md file
   • Check: YAML frontmatter block present
   • Check: name: field in frontmatter
   • Check: description: field in frontmatter
   • Check: model: field in frontmatter
   • Check: tools: field in frontmatter
   • Find parent addon's manifest.json
   • Check: Agent listed in manifest.json agents array
   • Check: File lives in agentic/code/
   • Full link classification check (see Link Classification below)

   Link Classification (applies to all component types):

   Extract every @<path> reference from the file and classify:

Examples

Example 1: Valid skill

User: "Validate the doctor skill"

Action: Read agentic/code/addons/aiwg-utils/skills/doctor/SKILL.md, find parent manifest, run all checks.

Output:

Component Validation: doctor (skill)
Path: agentic/code/addons/aiwg-utils/skills/doctor/SKILL.md

Checks:
  PASS  description frontmatter present
  PASS  title section present
  PASS  behavior section present
  PASS  examples section present
  PASS  listed in aiwg-utils manifest.json
  PASS  lives in agentic/code/

Result: PASS — all checks passed

Example 2: Incomplete skill with placement violation

User: "validate component at .claude/skills/my-new-skill"

Action: Read SKILL.md, check for completeness, check placement.

Output:

Component Validation: my-new-skill (skill)
Path: .claude/skills/my-new-skill/SKILL.md

Checks:
  PASS  description frontmatter present
  FAIL  no ## Behavior or ## Process section
  FAIL  no ## Examples section
  FAIL  placement violation: .claude/skills/ is a deployment target
  FAIL  not found in any manifest.json

Result: FAIL — 4 issues found

Required actions:
  1. Add ## Behavior section to SKILL.md
  2. Add ## Examples section to SKILL.md
  3. Move to agentic/code/addons/<your-addon>/skills/my-new-skill/SKILL.md
  4. Add "my-new-skill" to your addon's manifest.json skills array
  5. Run `aiwg use <addon>` to deploy

Example 3: Circular skill-executed command

User: "check the my-command command"

Action: Read definitions.ts, find executedViaSkillRunner: true, read associated SKILL.md, search for aiwg my-command.

Output:

Component Validation: my-command (command)
Path: src/extensions/commands/definitions.ts

Checks:
  PASS  definition entry present in definitions.ts
  PASS  executedViaSkillRunner: true (no TypeScript handler required)
  FAIL  circular call detected: SKILL.md contains "aiwg my-command" in bash block (line 47)

Result: FAIL — 1 issue found

Required actions:
  1. Rewrite SKILL.md to perform work directly via Read/Write/Bash/Task tools
     without calling back into `aiwg my-command`
  See: ${CLAUDE_PLUGIN_ROOT}/rules/no-circular-skill-calls.md

References

• @$AIWG_ROOT/${CLAUDE_PLUGIN_ROOT}/rules/component-completeness.md — Full completeness requirements
• @$AIWG_ROOT/${CLAUDE_PLUGIN_ROOT}/rules/skill-placement.md — Placement requirements
• @$AIWG_ROOT/${CLAUDE_PLUGIN_ROOT}/rules/no-circular-skill-calls.md — Circular call detection
• @$AIWG_ROOT/${CLAUDE_PLUGIN_ROOT}/rules/aiwg-dir-reference-contract.md — Normalized .aiwg/ path contract
• @$AIWG_ROOT/src/extensions/commands/definitions.ts — Command definition registry