tomevault-io Claude Plugin Audit
Validates plugin structure, components, and quality against best practices.
Steps
- Load the
outfitter:claude-pluginsskill for plugin structure knowledge - Analyze plugin at target path (default: current directory)
- Check each component type against standards
- Generate findings with severity and fix recommendations
Audit Scope
| Component | Checks |
|---|---|
plugin.json |
Required fields, version format, valid JSON |
| Commands | Frontmatter, description quality, argument hints |
| Agents | Name/description match, tool restrictions, examples |
| Skills | SKILL.md structure, frontmatter, progressive disclosure |
| Hooks | Valid matchers, script permissions, timeout values |
Severity Levels
| Level | Indicator | Meaning |
|---|---|---|
| Critical | ◆◆ |
Blocks functionality, must fix |
| Warning | ◆ |
Best practice violation, should fix |
| Info | ◇ |
Suggestion, optional improvement |
Output Format
# Plugin Audit: {PLUGIN_NAME}
**Path**: {PATH}
**Status**: {PASS|WARNINGS|FAIL}
**Issues**: {CRITICAL} critical, {WARNINGS} warnings, {INFO} info
## Critical Issues
- `◆◆` {component}: {issue}
- **Fix**: {specific remediation}
## Warnings
- `◆` {component}: {issue}
- **Fix**: {specific remediation}
## Suggestions
- `◇` {component}: {suggestion}
## Summary
{1-2 sentence overall assessment}
Checks by Component
plugin.json
- File exists at
.claude-plugin/plugin.json - Valid JSON syntax
-
namepresent and valid (lowercase, hyphens, 2-64 chars) -
versionpresent and semver format -
descriptionpresent and meaningful - No unknown top-level fields
Commands
- Frontmatter has
description - Description is action-oriented
-
argument-hintuses<required>/[optional]syntax - No broken file references (
@path) - Bash commands in backticks are valid
Agents
-
namematches filename (without.md) -
descriptionhas trigger conditions and examples -
toolsfield uses correct syntax (comma-separated) -
modelis valid if specified
Skills
- SKILL.md exists in skill directory
- Frontmatter has
nameanddescription - Name matches directory name
- Description includes trigger keywords
- Under 500 lines (progressive disclosure)
- Referenced files exist
Hooks
- Valid hook types (PreToolUse, PostToolUse, etc.)
- Matchers use valid glob/tool patterns
- Scripts have execute permissions
- Timeouts are reasonable (< 30s default)
Auto-Fixable Issues
These can be fixed automatically:
| Issue | Auto-Fix |
|---|---|
Missing description in command |
Generate from filename |
| Script missing execute permission | chmod +x |
| Trailing whitespace in YAML | Trim |
Missing version in plugin.json |
Add "1.0.0" |
Flag auto-fixable issues in output:
- `◆` commands/deploy.md: Missing description [auto-fixable]
- **Fix**: Add `description: "Deploy to environment"`
Rules
Always:
- Check every component type present
- Provide specific file paths in findings
- Include concrete fix instructions
- Flag auto-fixable issues
Never:
- Modify files (audit only)
- Skip components due to quantity
- Give vague recommendations
Converted and distributed by TomeVault — claim your Tome and manage your conversions.