Validate Manifest

"The manifest is the contract between the plugin and the runtime. A broken contract breaks trust."

Validates that plugin.json is well-formed JSON, contains all required and recommended fields, and that its declared counts and references match the actual plugin contents. [EXPLICIT]

---

Procedure

Step 1 -- Parse JSON

• Look for plugin.json at plugin root first (official spec location), then fall back to .claude-plugin/plugin.json (legacy location). Report INFO if found at legacy path.
• Attempt strict JSON parse. If it fails:
  • Check for trailing commas after last array/object element -- report CRITICAL: Trailing comma at line N. [EXPLICIT]
  • Check for JavaScript-style comments (//, /* */) -- report CRITICAL: Comments not allowed in JSON. [EXPLICIT]
  • Check for single quotes instead of double quotes -- report CRITICAL: JSON requires double quotes. [EXPLICIT]
• If JSON is unparseable after diagnostics, STOP and report. Subsequent steps require valid JSON.

Step 2 -- Validate Required Fields

• name: Must exist, must be a string, must match kebab-case pattern ^[a-z][a-z0-9]*(-[a-z0-9]+)*$. CRITICAL if missing or invalid.

Step 2b -- Validate Strongly Recommended Fields

Per the official plugin spec, only name is strictly required. The following are strongly recommended:

• version: Should match semver ^\\d+\\.\\d+\\.\\d+$ (e.g., 1.0.0). No v prefix. WARNING if missing or invalid format.
• description: Should be a string with length > 20 characters. WARNING if missing, INFO if too short.

Step 3 -- Validate Recommended Fields

• author: Should exist as a string (e.g., "Jane") or an object with at minimum a name string (e.g., {"name": "Jane"}). Both formats are valid per the official spec. WARNING if missing.
• license: Should exist as a string (e.g., MIT, GPL-3.0, All Rights Reserved). WARNING if missing.
• keywords: Should exist as an array with 3+ string entries. WARNING if missing or fewer than 3.
• repository: INFO if missing (helpful for discoverability but not required).

Step 4 -- Consistency Checks

• name vs. directory: The name field should match the plugin's root directory name. WARNING if mismatch.
• Skill count: If manifest declares a skill count or lists skills, verify against actual skills/*/SKILL.md count. WARNING on mismatch.
• Command count: Same check for commands vs. actual commands/*.md files. WARNING on mismatch.
• Agent count: Same check for agents vs. actual agents/*.md files. WARNING on mismatch.
• Version reasonability: If version is 0.0.0, report INFO: Placeholder version detected.

Step 5 -- Forbidden Fields

• plugin.json MUST NOT contain: scripts, hooks, settings, dependencies, devDependencies.
• These belong in other files (hooks.json, settings.json, package.json).
• Report CRITICAL for hooks or scripts keys (indicates confusion with package.json).
• Report WARNING for settings key (belongs in settings.json).

Step 6 -- Generate Manifest Report

• Produce findings table: | Severity | Field | Finding | Current Value |.
• Include a manifest completeness score: (present required + present recommended) / total expected fields as percentage.
• If all required fields valid and no CRITICAL findings: "Manifest validation PASSED".

---

Quality Criteria

• JSON parse errors include the exact line number and character position when possible.
• Every field check states the expected format alongside the actual value found.
• Consistency checks compare declared vs. actual counts with specific numbers.
• The completeness percentage gives an at-a-glance quality indicator.
• Required vs recommended vs optional field severity levels match the official plugin spec.

Assumptions & Limits

• Read-only. This skill never modifies plugin.json.
• Per the official spec, only name is strictly required. Marking version/description as CRITICAL would over-enforce beyond the spec.
• Cannot validate that author URLs or repository URLs are reachable -- only checks format.
• Does not validate the content quality of fields (e.g., whether the description is useful), only their presence and format.
• Consistency checks depend on the plugin's actual directory contents -- if skills/ is empty, the count check passes trivially.

Good vs Bad

Bad finding:

WARNING: version field is missing. [EXPLICIT]

Missing: no expected format, no guidance. [EXPLICIT]

Good finding:

WARNING | version | Missing. Expected: semver string (e.g., "1.0.0"). | (absent)

Includes: severity, field name, expected format with example, current value. [EXPLICIT]

Anti-Patterns

1. Accepting version: "1.0" as valid semver (must be three components). [EXPLICIT]
2. Not detecting the v prefix in version strings (v1.0.0 is invalid). [EXPLICIT]
3. Rejecting author: "Jane" (string) — the official spec accepts both string and object formats for author. [EXPLICIT]
4. Ignoring extra unknown fields without at least an INFO note. [EXPLICIT]

Edge Cases

1. plugin.json with BOM (byte order mark) -- strip before parsing, report INFO. [EXPLICIT]
2. Very large description (>500 chars) -- INFO suggesting it may be too verbose for tooling. [EXPLICIT]
3. Unicode characters in name field -- CRITICAL, names must be ASCII kebab-case. [EXPLICIT]
4. Duplicate keys in JSON (technically valid but undefined behavior) -- WARNING. [EXPLICIT]
5. Empty keywords array [] -- WARNING, same as missing. [EXPLICIT]

Usage

Example invocations:

• "/validate-manifest" — Run the full validate manifest workflow
• "validate manifest on this project" — Apply to current context