Skip to main content
AI/MLjmagly

validate-addon

Validate an entire AIWG addon package for completeness and release readiness

Stars
141
Source
jmagly/aiwg
Updated
2026-05-31
Slug
jmagly--aiwg--validate-addon
View on GitHubRaw SKILL.md

// install — copy + paste into any project

mkdir -p .claude/skills && curl -fsSL https://raw.githubusercontent.com/jmagly/aiwg/HEAD/agentic/code/addons/aiwg-dev/skills/validate-addon/SKILL.md -o .claude/skills/validate-addon.md

Drops the SKILL.md into .claude/skills/validate-addon.md. Works with Claude Code, Cursor, and any agent that loads SKILL.md files from .claude/skills/.

Validate Addon

You check an entire AIWG addon directory for completeness and release readiness, then produce a detailed structured report covering manifest integrity, artifact completeness, placement violations, and any blocking issues.

Triggers

  • "validate this addon" → check the addon in the current or named directory
  • "is this addon ready to release" → run full release readiness check
  • "check the addon" → validate the named addon
  • "pre-release check on my addon" → run validate-addon
  • "addon readiness report" → full validation with report output
  • "validate addon at " → validate the addon at the given path

Trigger Patterns Reference

Pattern Example Action
Current directory "validate this addon" Validate addon at cwd
Named addon "check the aiwg-dev addon" Find addon by name and validate
Path-specific "validate addon at agentic/code/addons/my-addon" Validate at given path
Release gate "is this addon ready to release" Full validation, block on any FAIL
Quick check "any issues with this addon" Run validation, summarize findings

Process

  1. Locate the addon:

    • If path given: use it
    • If name given: find agentic/code/addons/<name>/manifest.json
    • If current directory: look for manifest.json in cwd or walk up to nearest addon root

  2. Read and validate manifest.json:

    • File exists at addon root
    • Valid JSON (parseable)
    • Required fields present: id, type, name, version, description
    • type equals "addon"
    • version follows CalVer format (YYYY.M.PATCH, no leading zeros)
    • core field present (boolean)
    • autoInstall field present (boolean)
    • If devOnly: true: confirm this is intentional (it excludes from aiwg use all)

  3. Check README.md:

    • File exists at addon root
    • Non-empty content

  4. Validate each skill listed in manifest: For each entry in manifest.json skills array:

    • skills/<name>/SKILL.md exists
    • description: frontmatter present
    • # Title section present
    • ## Behavior or ## Process section present
    • Collect any missing skills (in manifest but no SKILL.md) and orphaned skills (SKILL.md exists but not in manifest)

  5. Validate each agent listed in manifest: For each entry in manifest.json agents array:

    • Agent .md file exists
    • YAML frontmatter present
    • name:, description:, model:, tools: fields in frontmatter
    • Collect missing and orphaned agents

  6. Validate each rule listed in manifest: For each entry in manifest.json rules array:

    • rules/<name>.md exists
    • RULES-INDEX.md exists in rules/
    • Rule name appears in RULES-INDEX.md

  7. Check for placement violations:

    • Search corresponding provider directories (.claude/skills/, .github/agents/, etc.) for any files whose names match this addon's artifacts
    • For each match: verify a source file exists in agentic/code/
    • Flag any deployed files with no source as violations

  8. Check for .aiwg/ references in addon artifacts:

    • Search all SKILL.md, agent .md, and command .md files under the addon for @.aiwg/ path references
    • Flag any found: these only resolve inside the AIWG repository itself

  9. Compile report:

    Addon Validation: <addon-name> v<version>
Path: agentic/code/addons/<name>/

Manifest:
  PASS  manifest.json present and valid JSON
  PASS  required fields: id, type, name, version, description
  PASS  version format: 2026.4.0 (CalVer, no leading zeros)
  PASS  devOnly: true (excluded from `aiwg use all` — intentional)

README:
  PASS  README.md present

Skills (3 listed):
  PASS  validate-component: SKILL.md present, frontmatter complete
  PASS  validate-addon: SKILL.md present, frontmatter complete
  FAIL  dev-doctor: listed in manifest but SKILL.md missing

Agents (0 listed):
  PASS  no agents declared

Rules (4 listed):
  PASS  skill-placement: rule file present, in RULES-INDEX.md
  PASS  no-circular-skill-calls: rule file present, in RULES-INDEX.md
  PASS  component-completeness: rule file present, in RULES-INDEX.md
  FAIL  addon-boundaries: not found in RULES-INDEX.md

Placement violations:
  PASS  no orphaned deployed files found

.aiwg/ references:
  PASS  no .aiwg/ path references in deployable artifacts

Result: FAIL — 2 blocking issues

Blocking issues:
  1. skills/dev-doctor/SKILL.md missing — create the file or remove from manifest
  2. addon-boundaries not in rules/RULES-INDEX.md — add an entry

Warnings:
  none

  10. Report result: Surface the structured report to the user. Highlight blocking issues in the summary line. For each failure, include the specific remediation step.

Examples

Example 1: Fully valid addon

User: "Is the aiwg-dev addon ready to release?"

Output:

Addon Validation: aiwg-dev v1.0.0
Path: agentic/code/addons/aiwg-dev/

Manifest:          PASS (all required fields, valid CalVer)
README:            PASS
Skills (3):        PASS (all present and complete)
Agents (0):        PASS
Rules (4):         PASS (all present and in RULES-INDEX.md)
Placement:         PASS (no violations)
.aiwg/ refs:       PASS

Result: PASS — addon is release-ready

Example 2: Addon with gaps found

User: "check the my-new-addon addon"

Output:

Addon Validation: my-new-addon v2026.4.0
Path: agentic/code/addons/my-new-addon/

Manifest:          PASS
README:            FAIL — README.md missing
Skills (2):
  PASS  my-skill: complete
  FAIL  other-skill: SKILL.md missing (listed in manifest but file not found)
Rules (1):         PASS
Placement:         WARN — .claude/skills/orphan-skill/ found with no agentic/code/ source

Result: FAIL — 2 blocking issues, 1 warning

Blocking issues:
  1. README.md missing — create at agentic/code/addons/my-new-addon/README.md
  2. skills/other-skill/SKILL.md missing — create the file or remove from manifest

Warnings:
  W1. .claude/skills/orphan-skill/ has no source in agentic/code/ — may be a placement violation
      See: agentic/code/addons/aiwg-dev/rules/skill-placement.md

References

  • @$AIWG_ROOT/agentic/code/addons/aiwg-dev/rules/component-completeness.md — Completeness requirements per artifact type
  • @$AIWG_ROOT/agentic/code/addons/aiwg-dev/rules/skill-placement.md — Placement violation detection
  • @$AIWG_ROOT/agentic/code/addons/aiwg-dev/rules/addon-boundaries.md — .aiwg/ reference detection
  • @$AIWG_ROOT/agentic/code/addons/aiwg-dev/skills/validate-component/SKILL.md — Per-component validation