Agent skill

project-hook-setup

Use when setting up project-specific hooks for Claude Code enforcement. Load during INIT state when .claude/hooks/ is missing, or when creating new project. Installs 5 hooks that read from .claude/config/project.json (tests, health, dependencies).

View SKILL.md on GitHub Repository
Stars 7
Forks 0

Install this agent skill to your Project

npx add-skill https://github.com/ingpoc/SKILLS/tree/main/project-hook-setup

SKILL.md

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

bash
# 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

bash
# 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

bash
.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:

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)

bash
# 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:

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:

markdown
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.

Recommended Agent Skills

Expand your agent's capabilities with these related and highly-rated skills.

ingpoc/SKILLS

scroll-storyteller

Use when creating interactive scroll-based storytelling experiences with mouse-following spotlight effects, animated SVG art, and the Anthropic design language. Load for explainer pages, product showcases, visual narratives, or any content needing immersive scroll storytelling with organic shapes and smooth animations. Supports GSAP-powered or lightweight CSS-only animations.

7 0
Explore
ingpoc/SKILLS

enforcement

Use when implementing hooks that BLOCK invalid actions, creating quality gates for state transitions, or enforcing tested:true verification. Load when designing enforcement mechanisms. Uses exit code 2 to block, JSON permissionDecision:deny, or updatedInput modification. Rules are instructions; hooks are enforcement.

7 0
Explore
ingpoc/SKILLS

async-programming-skill

This skill provides async/await patterns and best practices for concurrent programming

7 0
Explore
ingpoc/SKILLS

postgresql-skill

This skill provides PostgreSQL-specific patterns for database design, optimization, and transaction management

7 0
Explore
ingpoc/SKILLS

token-efficient

Use when processing 50+ items, analyzing CSV/log files, executing code in sandbox, or searching for tools. Load for data processing tasks. Achieves 98%+ token savings via in-sandbox execution, progressive disclosure, and pagination. Supports heredocs for multi-line bash.

7 0
Explore
ingpoc/SKILLS

mcp-builder

Guide for creating high-quality MCP (Model Context Protocol) servers that enable LLMs to interact with external services through well-designed tools. Use when building MCP servers to integrate external APIs or services, whether in Python (FastMCP) or Node/TypeScript (MCP SDK).

7 0
Explore

Didn't find tool you were looking for?

Be as detailed as possible for better results