Plugin CheckerSAFE

High-performance AI coding agent CLI written in Rust with zero unsafe code

The instruction file, verbatim from the audited commit — this is the text the model reads, and the surface the audit's instruction layer examines. Quoted here so you can judge it without cloning anything.

---
name: plugin-checker
description: >-
  Use this skill when asked to "validate plugin", "check plugin structure",
  "verify plugin", "audit plugin", "is my plugin correct", "plugin issues",
  or when troubleshooting plugin problems.
---

# 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):**
- [ ] `PreToolUse`
- [ ] `PostToolUse`
- [ ] `Stop`
- [ ] `SubagentStop`
- [ ] `SessionStart`
- [ ] `SessionEnd`
- [ ] `UserPromptSubmit`
- [ ] `PreCompact`
- [ ] `Notification`
- [ ] `PermissionRequest`

**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:
```bash
# 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:
```bash
claude --plugin-dir /path/to/my-plugin
```

Debug mode:
```bash
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]

SAFEgrade B · trust 89/100 Nothing in the source contradicts what it says it does. Grade A is reserved for packages that have also passed the behavioural sandbox.

What the source does

Filesystem

none-observed

Network

none-observed

Shell

none-observed

Dependencies

pinned

Secrets in source

none-found

Findings (1)

.beads/beads.jsonl

Gates applied: no_behavioural_pass.