dot-claude-plugins: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Repository Overview

Claude Code plugin marketplace providing PreToolUse hooks (enforcement), skills (capabilities), and hybrid plugins. Each plugin is independently installable and follows a progressive disclosure architecture.

Core Architecture Principles

Progressive Disclosure: Load components only when execution requires them (minimize token usage)

• Always loaded: plugin.json (metadata only)
• Auto-loaded: hooks/hooks.json (event handler definitions)
• On demand: scripts/ (execution logic), references/ (decision data), assets/ (templates)

Plugin Directory Structure:

plugin-name/
├── .claude-plugin/plugin.json    # Required: metadata
├── hooks/hooks.json               # Optional: PreToolUse event handlers
├── scripts/enforce.py             # Optional: validation logic (Python preferred)
├── tests/test-*.sh                # Required: test suite using test-framework.sh
└── README.md                      # Required: installation/usage

Hook Script Contract (PreToolUse stdin format):

{
  "tool_name": "Bash",
  "tool_input": {
    "command": "..."
  }
}

• Exit 0 = allow | Exit 2 = block | Other = log but allow
• Timeout: 1 second max (keep logic minimal)
• Errors to stderr with actionable suggestions
• Must handle: empty input, invalid JSON, missing fields

Hook Script Implementation Pattern:

#!/usr/bin/env python3
import json, sys

try:
    data = json.load(sys.stdin)
    cmd = data.get('tool_input', {}).get('command', '')

    if not cmd:
        sys.exit(0)

    # Validation logic here
    if should_block:
        sys.stderr.write("Error message with suggestion")
        sys.exit(2)

    sys.exit(0)
except Exception:
    sys.exit(0)  # Always fail gracefully

Testing Commands

# Run all test suites (master runner)
./run-all-tests.sh

# Run specific plugin tests
./test-framework.sh <plugin>/tests/test-*.sh

# Manual hook testing
echo '{"tool_name":"Bash","tool_input":{"command":"test"}}' | python3 <plugin>/scripts/script.py
echo "Exit code: $?"