[DOCS] Plugin validation docs omit frontmatter and `hooks/hooks.json` coverage

the frontmatter coverage gap is real. we maintain ~30 skills and getting the frontmatter format right was trial and error since the docs don't fully specify it. the description field in particular is critical for auto-discovery but the docs don't explain how it's matched. would save a lot of debugging if the validation docs showed the full frontmatter schema with examples of good vs bad descriptions.

we maintain ~30 skills with frontmatter, here's one example: https://github.com/m13v/social-autoposter/blob/main/skill/SKILL.md - the format we use that works for auto-discovery.

Issue #35138 Verification

Title: [DOCS] Plugin validation docs omit frontmatter and hooks/hooks.json coverage
Issue Date: 2026-03-17
Verification Date: 2026-03-18
Status: PARTIALLY RESOLVED

---

Issue Summary

This issue reports that the plugin validation documentation described claude plugin validate mainly as JSON/manifest validation, omitting its expanded coverage of skill, agent, and command frontmatter plus hooks/hooks.json validation added in Claude Code v2.1.77.

---

Verification Results

Claim 1: plugin-marketplaces.md validation section describes the command mainly as marketplace JSON validation

Status: PARTIALLY RESOLVED
The marketplace page has been partially updated. The troubleshooting sections now reflect the expanded scope:

At line 798:

Ensure JSON syntax is valid and frontmatter is well-formed using claude plugin validate or /plugin validate

At line 803:

Run claude plugin validate . or /plugin validate . from your marketplace directory to check for issues. The validator checks plugin.json, skill/agent/command frontmatter, and hooks/hooks.json for syntax and schema errors.

However, the introductory text in the "Validation and testing" section at line 762 still reads:

Validate your marketplace JSON syntax:

This framing narrows the command's scope to "marketplace JSON syntax" when the validator now checks much more. A reader encountering this section first would get an incomplete picture of validator coverage.
Verdict: The troubleshooting subsections are updated, but the primary validation section header text still frames the command narrowly as JSON syntax validation.

Claim 2: plugins-reference.md debugging section only mentions invalid plugin.json / JSON syntax

Status: RESOLVED
The plugins reference at line 649 now reads:

Plugin not loading | Invalid plugin.json | Run claude plugin validate or /plugin validate to check plugin.json, skill/agent/command frontmatter, and hooks/hooks.json for syntax and schema errors

Verdict: The plugins reference now accurately describes the full scope of the validator.

Claim 3: plugins page documents frontmatter and hooks/hooks.json as natural cross-references

Status: NOT APPLICABLE
The issue suggested the plugins page as a natural cross-reference target but did not claim it was inaccurate. No specific gap was identified on this page beyond it being a useful place to link from.

---

Current State

| Claim | Status |
|-------|--------|
| plugin-marketplaces.md validation section frames command as JSON validation | PARTIALLY RESOLVED - troubleshooting updated, but intro text at line 762 still says "Validate your marketplace JSON syntax" |
| plugins-reference.md only mentions plugin.json / JSON syntax | RESOLVED - now mentions frontmatter and hooks/hooks.json |
| plugins page as cross-reference target | NOT APPLICABLE - no inaccuracy claimed |

---

Suggested Fix

Update the introductory text in the "Validation and testing" section of the plugin-marketplaces page (line 762) from:

Validate your marketplace JSON syntax:

To something like:

Validate your plugin structure and configuration:

This would align the introductory framing with the expanded validator scope already described in the troubleshooting subsections below.

---

References

• URL: https://code.claude.com/docs/en/plugin-marketplaces
• Line 762: "Validate your marketplace JSON syntax:" (narrow framing, not yet updated)
• Line 798: Troubleshooting bullet updated to mention frontmatter
• Line 803: Marketplace validation errors section updated with full validator scope
• URL: https://code.claude.com/docs/en/plugins-reference
• Line 649: Debugging table updated with full validator scope
• URL: https://code.claude.com/docs/en/changelog
• Line 77: v2.1.77 changelog entry confirming expanded validator coverage

---

Conclusion & Recommendation

Primary Concern: The introductory validation section on the marketplaces page still frames claude plugin validate as JSON syntax validation.
Resolution Status: PARTIALLY RESOLVED
Recommendation: KEEP OPEN
Two of three affected locations have been updated, but the primary "Validation and testing" section introduction still uses narrow "marketplace JSON syntax" framing that could mislead readers about the command's actual scope.

Issue #35138 Verification

Title: [DOCS] Plugin validation docs omit frontmatter and hooks/hooks.json coverage
Issue Date: 2026-03-17
Verification Date: 2026-03-18
Status: RESOLVED

---

Issue Summary

This issue reports that the documentation for claude plugin validate described the command primarily as JSON/manifest validation, omitting that v2.1.77 expanded it to also check skill/agent/command frontmatter and hooks/hooks.json for YAML parse errors and schema violations.

---

Verification Results

Claim 1: Validation docs frame the command as JSON-only validation

Status: RESOLVED

The plugin-marketplaces page now reads:

Run claude plugin validate . or /plugin validate . from your marketplace directory to check for issues. The validator checks plugin.json, skill/agent/command frontmatter, and hooks/hooks.json for syntax and schema errors.

This explicitly enumerates all three validation surfaces: plugin.json, frontmatter, and hooks/hooks.json.

Verdict: The validation command description now covers the full scope of what the validator checks.

Claim 2: Error table does not include frontmatter or hooks.json errors

Status: RESOLVED

The error table now includes entries for both new validation surfaces:

| Error | Cause |
|-------|-------|
| YAML frontmatter failed to parse: ... | Invalid YAML in a skill, agent, or command file |
| Invalid JSON syntax: ... (hooks.json) | Malformed hooks/hooks.json |

The table also documents the consequences: frontmatter parse failures cause the file to load with no metadata at runtime, while malformed hooks/hooks.json prevents the entire plugin from loading.

Verdict: The error table now covers YAML frontmatter parse failures and malformed hooks/hooks.json with actionable solutions.

Claim 3: Troubleshooting section only mentions invalid plugin.json

Status: RESOLVED

The troubleshooting guidance now reads:

Ensure JSON syntax is valid and frontmatter is well-formed using claude plugin validate or /plugin validate

This covers both JSON and frontmatter validation.

Verdict: The troubleshooting section now references both validation surfaces.

---

Current State

| Claim | Status |
|-------|--------|
| Validation framed as JSON-only | RESOLVED |
| Error table missing frontmatter/hooks.json entries | RESOLVED |
| Troubleshooting mentions only plugin.json | RESOLVED |

---

References

• https://code.claude.com/docs/en/plugin-marketplaces

---

Conclusion & Recommendation

Primary Concern: Plugin validation docs did not document frontmatter and hooks/hooks.json validation coverage.

Resolution Status: RESOLVED

Recommendation: CLOSE

The plugin-marketplaces page now enumerates all validation surfaces (plugin.json, frontmatter, hooks/hooks.json), includes error table entries for YAML parse failures and malformed hooks.json, and updates troubleshooting guidance accordingly.

This issue has been automatically locked since it was closed and has not had any activity for 7 days. If you're experiencing a similar issue, please file a new issue and reference this one if it's relevant.