Ariff-claude-plugins plugin-checker

install

source · Clone the upstream repo

git clone https://github.com/a-ariff/ariff-claude-plugins

Claude Code · Install into ~/.claude/skills/

T=$(mktemp -d) && git clone --depth=1 https://github.com/a-ariff/ariff-claude-plugins "$T" && mkdir -p ~/.claude/skills && cp -r "$T/plugins/plugin-checker/skills/plugin-checker" ~/.claude/skills/a-ariff-ariff-claude-plugins-plugin-checker && rm -rf "$T"

manifest: plugins/plugin-checker/skills/plugin-checker/SKILL.md

source content

Plugin Checker Skill

This skill provides comprehensive validation guidelines for Claude Code plugins, helping identify structural issues, misconfigurations, and best practice violations.

Validation Checklist

1. Plugin Manifest Validation

Check

.claude-plugin/plugin.json

Required:

File exists at
```
.claude-plugin/plugin.json
```
Valid JSON syntax
```
name
```
field present and valid

Name validation:

Uses kebab-case (lowercase letters, numbers, hyphens)
Length between 3-50 characters
No spaces or special characters
Starts with a letter

Optional fields (if present):

```
version
```
follows semver (X.Y.Z)
```
description
```
is a non-empty string
```
author
```
has
```
name
```
field (string)
```
author.email
```
is valid email format (if present)

2. Directory Structure Validation

Required structure:

plugin-name/
├── .claude-plugin/
│   └── plugin.json    ← REQUIRED

Valid optional directories:

```
agents/
```
- Contains
```
.md
```
files only
```
skills/
```
- Contains subdirectories with
```
SKILL.md
```
```
commands/
```
- Contains
```
.md
```
files only
```
hooks/
```
- Contains
```
hooks.json
```
```
scripts/
```
- Contains executable scripts

Invalid patterns to flag:

❌
```
AGENTS.md
```
at root (should be
```
agents/*.md
```
)
❌
```
SKILL.md
```
at root (should be
```
skills/*/SKILL.md
```
)
❌ Nested
```
.claude-plugin/
```
directories
❌ Files directly in
```
skills/
```
(should be in subdirs)

3. Agent File Validation

For each file in

agents/*.md

Frontmatter checks:

File starts with
```
---
```
Valid YAML frontmatter
```
name
```
field present
```
description
```
field present

Name field:

Lowercase letters, numbers, hyphens only
3-50 characters
Matches filename (recommended)

Description field:

Contains trigger conditions
Has at least one
```
<example>
```
block (recommended)
Example has
```
user:
```
,
```
assistant:
```
,
```
<commentary>
```

Model field (if present):

Valid value:
```
inherit
```
,
```
sonnet
```
,
```
opus
```
,
```
haiku
```

Color field (if present):

Valid value:
```
blue
```
,
```
cyan
```
,
```
green
```
,
```
yellow
```
,
```
magenta
```
,
```
red
```

Tools field (if present):

Is an array
Contains valid tool names

Content check:

Has system prompt after frontmatter
System prompt is substantial (>20 chars)

4. Skill Directory Validation

For each directory in

skills/*/

Structure:

Contains
```
SKILL.md
```
file
```
SKILL.md
```
has YAML frontmatter

Frontmatter:

```
name
```
field present
```
description
```
field present with trigger phrases

Optional subdirectories:

```
references/
```
- Additional documentation
```
examples/
```
- Working examples
```
scripts/
```
- Utility scripts

5. Command File Validation

For each file in

commands/*.md

Frontmatter:

```
description
```
field present
```
argument-hint
```
is string (if present)
```
allowed-tools
```
is array (if present)

Naming:

Filename is kebab-case
No spaces or special characters

6. Hooks Validation

For

hooks/hooks.json

JSON structure:

Valid JSON syntax
Has
```
hooks
```
object at root (or in
```
description
```
+
```
hooks
```
)

Event names (if present):

Hook entries:

```
matcher
```
field present (for tool events)
```
hooks
```
array present
Each hook has
```
type
```
("command" or "prompt")
Command hooks have
```
command
```
field
Prompt hooks have
```
prompt
```
field

Path portability:

Uses
```
${CLAUDE_PLUGIN_ROOT}
```
for plugin paths
No hardcoded absolute paths

Script references:

Referenced scripts exist
Scripts are executable (have shebang)

7. Security Checks

Credentials:

No hardcoded API keys or tokens
No passwords in configuration
Environment variables used for secrets

URLs:

MCP servers use HTTPS/WSS (not HTTP/WS)

Scripts:

No obvious command injection vulnerabilities
Input validation present
Variables properly quoted

Common Issues and Fixes

Issue: "plugin not found"

Cause: Missing or invalid plugin.json Fix: Create

.claude-plugin/plugin.json

with valid JSON and

name

field

Issue: "agents not loading"

Cause: Agents not in correct location Fix: Move to

agents/

directory with

.md

extension

Issue: "skill not triggering"

Cause: Weak trigger description or wrong structure Fix:

Ensure
```
skills/{name}/SKILL.md
```
structure
Add specific trigger phrases to description

Issue: "hooks not running"

Cause: Invalid hooks.json or script permissions Fix:

Validate JSON syntax
Make scripts executable:
```
chmod +x scripts/*.sh
```
Use
```
${CLAUDE_PLUGIN_ROOT}
```
in paths

Issue: "command not appearing"

Cause: Missing frontmatter or wrong location Fix: Ensure

commands/*.md

with

description

in frontmatter

Validation Commands

Quick structure check:

# Check plugin.json exists and is valid
jq . my-plugin/.claude-plugin/plugin.json

# List all components
find my-plugin -name "*.md" -o -name "*.json" | head -20

# Check hooks.json
jq . my-plugin/hooks/hooks.json 2>/dev/null || echo "No hooks.json"

Test plugin locally:

claude --plugin-dir /path/to/my-plugin

Debug mode:

claude --debug --plugin-dir /path/to/my-plugin

Validation Report Format

When reporting validation results:

## Plugin Validation Report

### Plugin: [name]
Location: [path]

### Summary
[PASS/FAIL] - [brief assessment]

### Critical Issues (must fix)
- [ ] `path/to/file` - [issue] - [fix]

### Warnings (should fix)
- [ ] `path/to/file` - [issue] - [recommendation]

### Components Found
- Agents: [count] files
- Skills: [count] directories
- Commands: [count] files
- Hooks: [present/not present]

### Positive Findings
- [What's done correctly]

### Recommendations
1. [Priority fix]
2. [Improvement suggestion]

Quick Validation Script

#!/bin/bash
# validate-plugin.sh <plugin-dir>

PLUGIN_DIR="${1:-.}"

echo "=== Plugin Validation ==="

# Check plugin.json
if [ -f "$PLUGIN_DIR/.claude-plugin/plugin.json" ]; then
  echo "✓ plugin.json exists"
  NAME=$(jq -r '.name' "$PLUGIN_DIR/.claude-plugin/plugin.json" 2>/dev/null)
  if [ -n "$NAME" ] && [ "$NAME" != "null" ]; then
    echo "✓ name: $NAME"
  else
    echo "✗ ERROR: name field missing or invalid"
  fi
else
  echo "✗ CRITICAL: .claude-plugin/plugin.json not found"
fi

# Check agents
if [ -d "$PLUGIN_DIR/agents" ]; then
  AGENT_COUNT=$(find "$PLUGIN_DIR/agents" -name "*.md" | wc -l)
  echo "✓ agents/: $AGENT_COUNT files"
fi

# Check skills
if [ -d "$PLUGIN_DIR/skills" ]; then
  SKILL_COUNT=$(find "$PLUGIN_DIR/skills" -name "SKILL.md" | wc -l)
  echo "✓ skills/: $SKILL_COUNT SKILL.md files"
fi

# Check commands
if [ -d "$PLUGIN_DIR/commands" ]; then
  CMD_COUNT=$(find "$PLUGIN_DIR/commands" -name "*.md" | wc -l)
  echo "✓ commands/: $CMD_COUNT files"
fi

# Check hooks
if [ -f "$PLUGIN_DIR/hooks/hooks.json" ]; then
  if jq empty "$PLUGIN_DIR/hooks/hooks.json" 2>/dev/null; then
    echo "✓ hooks/hooks.json: valid JSON"
  else
    echo "✗ hooks/hooks.json: invalid JSON"
  fi
fi

echo "=== Validation Complete ==="

References

Plugin structure: https://code.claude.com/docs/en/plugins-reference
Hooks reference: https://code.claude.com/docs/en/hooks
Official examples: https://github.com/anthropics/claude-code/tree/main/plugins