nodnarbnitram__claude-code-extensions/CLAUDE.md

OpenSpec Instructions

These instructions are for AI assistants working in this project.

Always open @/openspec/AGENTS.md when the request:

• Mentions planning or proposals (words like proposal, spec, change, plan)
• Introduces new capabilities, breaking changes, architecture shifts, or big performance/security work
• Sounds ambiguous and you need the authoritative spec before coding

Use @/openspec/AGENTS.md to learn:

• How to create and apply change proposals
• Spec format and conventions
• Project structure and guidelines

Keep this managed block so 'openspec update' can refresh the instructions.

CLAUDE.md

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

Repository Purpose

This repository is a working project for creating and managing Claude Code extensions: agents, hooks, commands, skills, and output styles. When users request new extensions, you should create them here using the patterns and templates defined below.

Extension Creation

IMPORTANT: When creating extensions, use the appropriate tool:

For Agents: Use meta-agent at .claude/agents/meta-agent.md

• Fetches the latest Claude Code documentation
• Generates complete, production-ready agent files
• Writes directly to .claude/agents/

For Skills: Use the /create-skill command

• Syntax: /create-skill <name> "<description>" [doc-urls...]
• Uses the skill skeleton template at templates/skill-skeleton/
• Generates SKILL.md and README.md with proper structure
• Evaluates and creates optional directories (templates/, scripts/, references/)
• Writes directly to .claude/skills/

Project Structure

.claude/
├── settings.json          # Hook configuration (all lifecycle events registered)
├── agents/                # Organized by category: core, orchestrators, universal, specialized
├── hooks/                 # Python scripts for lifecycle events
│   └── utils/            # Shared utilities (llm/, tts/)
├── commands/             # Reusable slash commands
└── skills/               # Model-invoked capabilities (flat structure)

templates/
└── skill-skeleton/       # Starter template for new skills

docs/claude-code/         # Official Claude Code documentation
├── sub-agents.md
├── hooks.md
├── hooks-reference.md
├── commands-reference.md
├── agent-skills.md
└── output-styles.md

logs/                     # Runtime logs (generated by hooks)

Plugin Architecture

This repository supports dual-mode installation: as modular Claude Code plugins OR as standalone extensions.

Multi-Plugin Structure

The repository provides 5 focused plugins (Phase 1), not a monolithic bundle:

.claude-plugin/
├── marketplace.json                    # Marketplace configuration
└── plugins/
    ├── cce-core/
    │   └── plugin.json                # Core plugin manifest
    ├── cce-kubernetes/
    │   └── plugin.json                # Kubernetes plugin manifest
    ├── cce-cloudflare/
    │   └── plugin.json                # Cloudflare plugin manifest
    ├── cce-esphome/
    │   └── plugin.json                # ESPHome plugin manifest
    └── cce-web-react/
        └── plugin.json                # React plugin manifest

Key Principle: Users install only what they need for their tech stack.

Dual-Mode Architecture

┌─────────────────────────────────────────┐
│  claude-code-extensions Repository      │
├─────────────────────────────────────────┤
│                                         │
│  ┌──────────────┐  ┌─────────────────┐ │
│  │ Plugin Mode  │  │ Standalone Mode │ │
│  ├──────────────┤  ├─────────────────┤ │
│  │ Uses:        │  │ Uses:           │ │
│  │ • .claude-   │  │ • .claude/      │ │
│  │   plugin/    │  │   directly      │ │
│  │ • Namespaced │  │ • Unprefixed    │ │
│  │   commands   │  │   commands      │ │
│  │   /cce:*     │  │   /git-commit   │ │
│  │   /cce-k8s:* │  │   /prime        │ │
│  │ • Plugin     │  │ • Manual        │ │
│  │   installer  │  │   installer     │ │
│  └──────────────┘  └─────────────────┘ │
│                                         │
│  Both modes use the SAME source files  │
│  in .claude/agents/, .claude/hooks/,   │
│  .claude/commands/, .claude/skills/    │
└─────────────────────────────────────────┘

Hook Path Resolution

To support both modes, all hooks use fallback path syntax:

{
  "hooks": {
    "PreToolUse": [{
      "hooks": [{
        "type": "command",
        "command": "uv run \"${CLAUDE_PLUGIN_ROOT:-$CLAUDE_PROJECT_DIR}\"/.claude/hooks/pre_tool_use.py"
      }]
    }]
  }
}

How it works:

• Plugin mode: ${CLAUDE_PLUGIN_ROOT} is set → evaluates to plugin cache path
• Standalone mode: ${CLAUDE_PLUGIN_ROOT} is unset → falls back to $CLAUDE_PROJECT_DIR

Command Namespacing

Installation Mode	Namespace	Example Commands
Plugin: cce-core	/cce:*	/cce:git-commit, /cce:prime
Plugin: cce-kubernetes	/cce-kubernetes:*	/cce-kubernetes:health
Standalone	Unprefixed	/git-commit, /prime, /k8s-health

No code changes required - Claude Code handles namespacing automatically based on plugin configuration.

Testing in Plugin Mode

# 1. Validate plugin structure
/plugin validate .

# 2. Install from local path for testing
/plugin marketplace add /path/to/claude-code-extensions
/plugin install cce-core@cce-marketplace

# 3. Test commands with namespace
/cce:git-commit
/cce:prime

# 4. Verify agents appear
/agents  # Should show cce-core agents

# 5. Update plugin after changes
/plugin update cce-core

Plugin Manifest Structure

Each plugin manifest (.claude-plugin/plugins/*/plugin.json) defines:

{
  "name": "cce-core",
  "version": "1.0.0",
  "description": "Essential Claude Code extensions",
  "author": { "name": "Claude Code Extensions Contributors" },
  "homepage": "https://github.com/nodnarbnitram/claude-code-extensions",
  "repository": "https://github.com/nodnarbnitram/claude-code-extensions",
  "license": "MIT",
  "keywords": ["core", "essential", "hooks"],
  "agents": [
    "./.claude/agents/core/",
    "./.claude/agents/orchestrators/",
    "./.claude/agents/universal/",
    "./.claude/agents/meta-agent.md"
  ],
  "skills": [
    "./.claude/skills/commit-helper/",
    "./.claude/skills/code-reviewer/"
  ],
  "commands": [
    "./.claude/commands/git-commit.md",
    "./.claude/commands/prime.md"
  ],
  "hooks": "./.claude/settings.json"
}

Custom paths specify exact agent/skill/command locations - multiple plugins can reference subdirectories under .claude/.

Creating Agents

Agents are Markdown files with YAML frontmatter stored in .claude/agents/ (project) or ~/.claude/agents/ (user).

Agent File Format

---
name: agent-name
description: When this agent should be invoked (be specific and action-oriented)
tools: Read, Grep, Glob, Bash  # Optional - omit to inherit all tools
---

# Agent System Prompt

Your agent's instructions go here. Be specific about:
- The agent's role and expertise
- When it should be used (include "MUST BE USED" or "use PROACTIVELY" for auto-delegation)
- Step-by-step workflow
- Expected output format
- Delegation patterns to other agents

Organization Structure

Organize agents in subdirectories by category (optional but recommended):

• core/: Quality/analysis agents
• orchestrators/: Coordination agents
• universal/: Framework-agnostic agents
• specialized/<tech>/: Framework-specific agents

Key Principles

1. Single responsibility: Each agent focuses on one domain
2. Explicit triggers: Use "MUST BE USED" in descriptions for proactive delegation
3. Tool restrictions: Limit tools to what's needed (improves security and focus)
4. Delegation patterns: Orchestrators delegate; specialists implement
5. Output formats: Define structured output when reports/analysis are needed

Creating Hooks

Hooks are shell commands executed at lifecycle events. Python hooks use uv run --script for dependency management.

Hook Lifecycle Events

• SessionStart: When Claude Code starts/resumes
• UserPromptSubmit: Before Claude processes user input
• PreToolUse: Before any tool executes (can block)
• PostToolUse: After tool completes
• PreCompact: Before context compaction
• SubagentStop: When subagent completes
• Stop: When main agent finishes responding
• Notification: When Claude Code sends notifications

Python Hook Template

#!/usr/bin/env -S uv run --script
# /// script
# requires-python = ">=3.11"
# dependencies = [
#     "python-dotenv",
# ]
# ///

import json
import sys
from pathlib import Path

def main():
    try:
        # Read JSON input from stdin
        input_data = json.load(sys.stdin)

        # Extract relevant fields
        # For PreToolUse/PostToolUse: tool_name, tool_input
        # For UserPromptSubmit: session_id, prompt
        # For SessionStart: session_id, source

        # Your hook logic here

        # Exit codes:
        # 0 = success, continue
        # 2 = block operation, show error to Claude
        sys.exit(0)

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

if __name__ == '__main__':
    main()

Register Hooks

Use /hooks command or edit .claude/settings.json:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "uv run \"$CLAUDE_PROJECT_DIR\"/.claude/hooks/pre_tool_use.py"
          }
        ]
      }
    ]
  }
}

Hook Patterns from This Repository

1. Logging pattern: All hooks append JSON to logs/<hook_name>.json
2. Safety checks: pre_tool_use.py includes patterns for blocking dangerous commands
3. Context loading: session_start.py can inject git status, project context files, GitHub issues
4. Graceful failure: Always sys.exit(0) on errors to prevent blocking Claude Code

Creating Commands

Commands are Markdown files that define reusable prompts, stored in .claude/commands/ (project) or ~/.claude/commands/ (user).

Command File Format

---
description: Brief description shown in /help
argument-hint: [arg1] [arg2]  # Optional
allowed-tools: Bash(git add:*), Bash(git status:*)  # Optional
model: claude-3-5-haiku-20241022  # Optional
---

# Command Instructions

Your prompt goes here. Use:
- $ARGUMENTS for all arguments
- $1, $2, $3 for individual arguments
- @file/path for file references
- !`bash command` for executed commands (requires allowed-tools)

Example Command

---
description: Review PR and create commit
argument-hint: [pr-number]
allowed-tools: Bash(git:*)
---

Review PR #$1 and create a git commit:

1. Check current git status: !`git status`
2. Review changes: !`git diff HEAD`
3. Create commit following repo conventions

Creating Output Styles

Output styles modify Claude Code's system prompt to change its behavior and personality. Stored in .claude/output-styles/ (project) or ~/.claude/output-styles/ (user).

Output Style Format

---
name: Style Name
description: Brief description of what this style does
---

# Custom System Prompt

You are an interactive CLI tool that helps users with [specific purpose].

## Behaviors

[Define specific behaviors, tone, output format]

Key Differences

• Output Styles: Modify main agent's system prompt (affect all interactions)
• Agents: Separate context for specific tasks
• Commands: Reusable prompts (stored user messages)

Creating Skills

Skills are model-invoked capabilities that Claude autonomously discovers and uses. Unlike slash commands (user-invoked), skills activate based on task context and description matching.

Skill Directory Structure

Skills are stored in .claude/skills/skill-name/ (project) or ~/.claude/skills/skill-name/ (user). Each skill is a directory containing at minimum a SKILL.md file.

.claude/skills/
└── skill-name/
    ├── SKILL.md        # Required - main instructions
    ├── README.md       # Optional - auto-trigger keywords
    ├── scripts/        # Optional - automation scripts
    ├── references/     # Optional - supporting docs
    └── assets/         # Optional - templates, configs

SKILL.md Format

---
name: skill-name
description: What it does AND when to use it (include trigger keywords)
allowed-tools: Read, Grep, Glob  # Optional - restricts tool access
---

# Skill Title

## Instructions

Step-by-step guidance for Claude.

## Best Practices

Key patterns and guidelines.

## Example

Concrete usage examples.

Skill Skeleton Template

Use templates/skill-skeleton/ as a starter for new skills:

# Manual creation
cp -r templates/skill-skeleton .claude/skills/my-skill
# Then edit SKILL.md with your content

# Or use the skill-creator agent
> Use the skill-creator to create a skill for [purpose]

Description Best Practices

The description field is critical for discovery. Include:

• What the skill does
• When Claude should use it
• Specific keywords users would mention

Good:

description: Extract text and tables from PDF files, fill forms, merge documents. Use when working with PDF files, forms, or document extraction.

Bad:

description: Helps with documents

Optional README.md

For complex skills, add a README.md with auto-trigger keywords:

## Auto-Trigger Keywords

### Primary Keywords
- pdf extraction
- form filling
- merge pdf

### Secondary Keywords
- document processing
- acrobat

### Error Pattern Keywords
- "Unable to read PDF"
- "Form field not found"

Tool Restrictions

Use allowed-tools for security-sensitive skills:

# Read-only skill
allowed-tools: Read, Grep, Glob

# No tool restrictions (inherits all)
# Simply omit the allowed-tools field

Key Principles

1. Flat structure: No category subdirectories (skills are discovered by description)
2. Specific descriptions: Include what AND when with trigger keywords
3. Progressive disclosure: Claude loads additional files only when needed
4. Model-invoked: Skills activate automatically based on context
5. Tool restrictions: Use allowed-tools for read-only or limited-scope skills

For detailed guidance, see docs/claude-code/agent-skills.md.

Development Workflow

Testing Hooks Locally

# Create test input
echo '{"tool_name": "Bash", "tool_input": {"command": "ls"}}' > test.json

# Test hook
uv run ./.claude/hooks/pre_tool_use.py < test.json
echo $?  # Check exit code

Enabling/Disabling Safety Checks

The pre_tool_use.py hook has:

• .env file blocking: ENABLED (lines 93-96)
• Dangerous rm command blocking: ENABLED (lines 103-105)

Comment/uncomment these blocks to adjust safety policies.

Plugin Validation and Testing

When working with plugins, validate structure and test in both modes:

# Validate all plugin manifests
/plugin validate .

# Test plugin mode installation (local)
/plugin marketplace add /path/to/claude-code-extensions
/plugin install cce-core@cce-marketplace
/plugin install cce-kubernetes@cce-marketplace

# Test commands with namespaces
/cce:git-commit
/cce-kubernetes:health

# Verify agents loaded
/agents  # Should show plugin agents

# Test standalone mode (existing workflow)
./install_extensions.py install --dry-run ~/test-project
./install_extensions.py install ~/test-project
cd ~/test-project && claude
> /git-commit  # Should work unprefixed

Critical: Always test both modes to ensure backward compatibility.

Best Practices

1. Version control agents/commands: Check .claude/agents/ and .claude/commands/ into git
2. Document decisions: Add comments in hook scripts explaining safety patterns
3. Test incrementally: Test each hook/agent/command individually
4. Use matchers wisely: Narrow hook matchers to avoid unnecessary executions
5. Fail gracefully: Hooks should never crash Claude Code
6. Leverage existing patterns: Study the hooks in this repo before creating new ones

Key Architecture Patterns

Safety Pattern (PreToolUse hooks)

Hooks can validate and block operations:

• Check for dangerous commands (is_dangerous_rm_command pattern in pre_tool_use.py)
• Prevent access to sensitive files (.env blocking enabled)
• Log all operations for audit
• Exit code 2 blocks operation and shows error to Claude

Context Preservation Pattern (Agents)

Each agent operates in isolated context:

• Prevents context pollution in main conversation
• Enables longer overall sessions
• Allows specialized instructions per domain

Important

• Update the README.md whenever adding new agents, hooks, commands, skills, or output-styles
• See CONTRIBUTING.md for detailed contribution guidelines and development workflow

References

All documentation in docs/claude-code/ is official Claude Code reference material. Refer to these when creating extensions.