skills.rest
JaviMontano
JaviMontanoCOMMUNITY
Explore all skills by this author →
WebsiteGitHub

validate-structure

Validates Claude Code plugin directory layouts against the official plugin specification.

1|Updated Mar 22, 2026
Search Tags:#claude code#plugin validation#kebab-case#spec compliance#skill.md#directory structure#path traversal
One-click install
npx skills add https://github.com/JaviMontano/mao-plugin-qa --skill validate-structure-javimontano
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: validate-structure
Source: https://github.com/JaviMontano/mao-plugin-qa/tree/main/skills/validate-structure
Command: npx skills add https://github.com/JaviMontano/mao-plugin-qa --skill validate-structure-javimontano

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes references (resource) components.

What problem does it solve? Claude Code plugins fail to load or behave unexpectedly when their directory structure deviates from the official spec, and manually auditing folder layouts, naming conventions, and file placement is slow and error-prone. ## Core Features & Use Cases - Directory Layout Validation: Checks for plugin.json at root or legacy .claude-plugin/ location, verifies skills/, commands/, agents/, and hooks/ directories, and confirms every skill directory contains a SKILL.md file. - Naming and Security Checks: Enforces kebab-case naming on all files and directories, scans for path traversal patterns (../) and absolute paths, and verifies script shebangs and execute permissions. - Structured Severity Reports: Produces a machine-parseable findings table classifying each issue as CRITICAL, WARNING, or INFO with exact paths and spec references. - Use Case: Before publishing a new Claude Code plugin to a marketplace, run this validation to catch a missing SKILL.md, a non-kebab-case skill folder, or an unexpected file in .claude-plugin/ that would break installation. ## Quick Start Validate the directory structure of my Claude Code plugin at ./my-plugin and report any spec violations.

Frequently Asked Questions about validate-structure

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I validate a Claude Code plugin directory structure?▼

Point the validation at your plugin root path. It locates plugin.json at the root or in .claude-plugin/, checks required directories like skills/ and commands/, verifies each skill has a SKILL.md, and reports findings in a severity-classified table.

What directory structure does a Claude Code plugin require?▼

A valid plugin needs plugin.json at the root or inside .claude-plugin/. Skills must be directories containing SKILL.md under skills/, commands must be .md files under commands/, and agents must be .md files under agents/. All names must be kebab-case.

Does the validation modify or fix my plugin files?▼

No, the validation is strictly read-only. It never creates directories or modifies files; it only inspects the existing structure and reports findings with severity levels and suggested kebab-case alternatives for naming violations.

Why is my skill directory reported as a critical error?▼

A skill directory without a SKILL.md file inside is reported as CRITICAL because every skill must contain that entry-point file per the spec. Nested skill directories like skills/group/skill-name/ are also CRITICAL since they are not spec-compliant.

What are the limitations of plugin structure validation?▼

It only checks existence, location, and naming, not file contents. Symlinks are detected but not followed, and it cannot determine whether a missing optional directory is intentional or accidental, so severity reflects functionality implications only.

Related Skills

Explore More Software Engineering Skills→
sjnimssjnims

plugin-structure

Scaffold Claude Code plugins with standardized directory layouts and plugin.json manifests.

Community
Basic
steltzsteltz

sft-scaffold-plugin

Generate plugin directory structures with plugin.json and SKILL.md templates.

Community
Intermediate
LerianStudioLerianStudio
205

documentation-review

Automate documentation quality reviews with structured verdicts and recommendations.

Official
Intermediate
yoshisadayoshisada

kiln-test

Run end-to-end plugin-skill tests in real Claude subprocesses with TAP output.

Community
Intermediate