/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 <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: P