Project Hook Setup Skill

Project Hook Setup

Per-project setup for Claude Code hooks. These hooks read from .claude/config/project.json for project-specific settings.

Purpose

Installs 5 project-specific hooks that enforce:

Test verification before marking tested
File existence before marking complete
Health checks for API projects
Dependency validation
Session entry protocol

When to Use

| Situation | Action | | --------- | ------ | | New project | Run during INIT | | .claude/hooks/ missing | Run setup | | Project config changed | Re-run setup | | Adding dependencies | Update config, re-run |

Quick Check

# Check if project hooks exist
ls .claude/hooks/

# Check if config exists
cat .claude/config/project.json

Interactive Config

Setup prompts for project configuration:

| Setting | Description | Example | | ------- | ----------- | ------- | | Project type | Framework used | fastapi, django, node | | Dev server port | Local development port | 8000 | | Health check | Command to verify server | curl -sf http://localhost:8000/health | | Test command | How to run tests | pytest | | Required env | Environment variables needed | DATABASE_URL, API_KEY | | Required services | Services to be running | redis://localhost:6379 |

Setup Steps

1. Install Hooks

# Interactive mode (prompts for config)
.skills/project-hook-setup/scripts/setup-project-hooks.sh

# Non-interactive mode (for agents/automation)
.skills/project-hook-setup/scripts/setup-project-hooks.sh --non-interactive

# Auto-confirm prompts
.skills/project-hook-setup/scripts/setup-project-hooks.sh --yes

# Use existing config
.skills/project-hook-setup/scripts/setup-project-hooks.sh --config /path/to/config.json

# Environment variable (agent mode)
CLAUDE_NON_INTERACTIVE=1 .skills/project-hook-setup/scripts/setup-project-hooks.sh

Non-interactive flags:

| Flag | Purpose | | ---- | ------- | | --non-interactive / -n | Skip all prompts (keeps existing config) | | --yes / -y | Auto-confirm all prompts | | --config / -c <path> | Use existing config file |

This:

Creates .claude/config/project.json (or uses provided config)
Copies 5 hook templates to .claude/hooks/
Sets executable permissions

2. Verify Installation

.skills/project-hook-setup/scripts/verify-project-hooks.sh

Hooks Installed

| Hook | Event | Purpose | Reads From | | ---- | ----- | ------- | ---------- | | verify-tests.py | PreToolUse | Run tests before tested | project.json → test_command | | verify-files-exist.py | PreToolUse | Check files before complete | feature-list.json | | verify-health.py | PreToolUse | Check server health | project.json → health_check | | require-dependencies.py | PreToolUse | Validate env, services | project.json | | session-entry.sh | CLI utility | Session entry protocol | project.json |

Note: session-entry.sh is a CLI utility. Use: .claude/hooks/session-entry.sh

Settings.json Configuration

Setup script configures .claude/settings.json:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {"type": "command", "command": "python3 \"$CLAUDE_PROJECT_DIR\"/.claude/hooks/verify-tests.py"},
          {"type": "command", "command": "python3 \"$CLAUDE_PROJECT_DIR\"/.claude/hooks/verify-files-exist.py"},
          {"type": "command", "command": "python3 \"$CLAUDE_PROJECT_DIR\"/.claude/hooks/verify-health.py"},
          {"type": "command", "command": "python3 \"$CLAUDE_PROJECT_DIR\"/.claude/hooks/require-dependencies.py"}
        ]
      }
    ]
  }
}

Note: Uses $CLAUDE_PROJECT_DIR for project-relative paths.

Exit Criteria (Code Verified)

# Config exists with required fields
[ -f ".claude/config/project.json" ]
jq -e '.project_type' .claude/config/project.json >/dev/null
jq -e '.health_check' .claude/config/project.json >/dev/null
jq -e '.test_command' .claude/config/project.json >/dev/null

# Hooks exist and executable
[ -d ".claude/hooks" ]
[ -x ".claude/hooks/verify-tests.py" ]
[ -x ".claude/hooks/verify-files-exist.py" ]
[ -x ".claude/hooks/verify-health.py" ]
[ -x ".claude/hooks/require-dependencies.py" ]
[ -x ".claude/hooks/session-entry.sh" ]

# Verify script passes
.skills/project-hook-setup/scripts/verify-project-hooks.sh

Scripts

| Script | Purpose | | ------ | ------- | | setup-project-hooks.sh | Main setup (config + hooks + settings + validate) | | configure-project-settings.py | Configure .claude/settings.json | | validate-settings.py | Validate hooks configured in settings.json | | prompt-project-config.sh | Interactive config creation | | verify-project-hooks.sh | Verify hook files exist | | install-hooks.sh | Copy templates to .claude/hooks/ |

Project Config Schema

.claude/config/project.json:

{
  "project_type": "fastapi|django|node|python|other",
  "dev_server_port": 8000,
  "health_check": "curl -sf http://localhost:8000/health",
  "test_command": "pytest",
  "required_env": ["DATABASE_URL", "API_KEY"],
  "required_services": ["redis://localhost:6379"]
}

Troubleshooting

| Problem | Solution | | ------- | -------- | | Config missing | Run setup-project-hooks.sh to create | | Hook can't read config | Check JSON syntax, verify required fields | | Tests not found | Update test_command in project.json | | Health check fails | Server not running or wrong port | | Permission denied | Run: chmod +x .claude/hooks/* |

Integration

This skill is called by the initializer skill during INIT state:

5. Setup hooks:
   - Check: ~/.claude/hooks/verify-state-transition.py exists (global)
   - Check: .claude/hooks/verify-tests.py exists (project)
   - If missing, load respective setup skill

Next Steps

After project hooks: Continue with feature breakdown and implementation.

Agent Skills: Project Hook Setup

Skill Files