jmagly/validate-component

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 <path>" → 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:

   | Pattern | Result | Message | |---------|--------|---------| | @$AIWG_ROOT/<path> | PASS | AIWG core ref (install-relative) | | @$TOKEN/<path> — TOKEN set in env | PASS | Registered corpus token | | @$TOKEN/<path> — TOKEN NOT in env | WARN | env var TOKEN not set; add to .env or export | | @.aiwg/<path> — path in Tier 1/2 allowlist | PASS | Normalized project memory | | @.aiwg/<path> — not in any memory.creates | FAIL | non-normalized .aiwg/ path — repo-local only | | @.claude/<path> | FAIL | deployment target — forbidden in distributable source | | @agentic/code/<path> | WARN | legacy bare ref — migrate to @$AIWG_ROOT/agentic/code/ | | @src/<path> | WARN | legacy bare ref — migrate to @$AIWG_ROOT/src/ | | @docs/<path> | WARN | legacy bare ref — migrate to @$AIWG_ROOT/docs/ | | @tools/<path> | WARN | legacy bare ref — migrate to @$AIWG_ROOT/tools/ | | Relative path within component | PASS | Local ref |

   Build the Tier 2 allowlist by reading all manifest.json files in agentic/code/ and collecting memory.creates[*].path values. Combine with Tier 1 (.aiwg/AIWG.md, .aiwg/frameworks/).

   For a CLI Command:

   • Read src/extensions/commands/definitions.ts
   • Check: Command entry exists in definitions
   • Check: Command has either executedViaSkillRunner: true OR a handler entry
   • If executedViaSkillRunner: true: find the associated SKILL.md and verify it does not contain aiwg <command-name> in any bash block
   • If handler expected: check src/cli/handlers/ for the handler file and registration in allHandlers

3. Compile report:

   Format results as a structured report:

   Component Validation: <component-name> (<type>)
   Path: <absolute-or-relative-path>
   
   Checks:
     PASS  description frontmatter present
     PASS  title section present
     PASS  behavior section present
     FAIL  no examples section found
     PASS  listed in manifest.json
     FAIL  not in agentic/code/ (found in .claude/skills/ — placement violation)
     WARN  @.aiwg/planning/my-design.md is not a normalized path (repo-local only)
   
   Result: FAIL — 2 issues found
   
   Required actions:
     1. Add ## Examples section to SKILL.md
     2. Move SKILL.md to agentic/code/addons/<addon>/skills/<name>/SKILL.md
        then re-deploy with: aiwg use <addon>
   

4. Surface the report to the user with the result line prominent.

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: agentic/code/addons/aiwg-dev/rules/no-circular-skill-calls.md

References

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