Skills
skills/oimiragieo/agent-studio/hook-creator

hook-creator

SKILL.md

Hook Creator Skill

Creates, validates, and registers hooks for the multi-agent orchestration framework.

ROUTER UPDATE REQUIRED (CRITICAL - DO NOT SKIP)

After creating ANY hook, you MUST update documentation:

1. Add to .claude/hooks/README.md under appropriate category
2. Register in config.yaml or settings.json if required
3. Update learnings.md with hook summary

Verification:

grep "<hook-name>" .claude/hooks/README.md || echo "ERROR: hooks/README.md NOT UPDATED!"

WHY: Hooks not documented are invisible and unmaintainable.

Overview

This skill creates hooks for the Claude Code framework:

  • Pre-tool execution - Safety validation before commands run
  • Post-tool execution - Logging, memory updates, telemetry
  • Session lifecycle - Initialize context, cleanup on exit
  • Memory management - Auto-extract learnings, format memory files
  • Routing enforcement - Ensure Router-First protocol compliance

Hook Types

Type Location Purpose When Triggered
Safety .claude/hooks/safety/ Validate commands, block dangerous ops Before Bash/Write/Edit
Memory .claude/hooks/memory/ Auto-update learnings, extract insights After task completion
Routing .claude/hooks/routing/ Enforce router-first protocol On UserPromptSubmit
Session .claude/hooks/session/ Initialize/cleanup sessions Session start/end

Hook-Agent Archetype Reference

When creating hooks, determine which agent archetypes will be governed by the new hook. See .claude/docs/@HOOK_AGENT_MAP.md for:

  • Section 1: Full hook-agent matrix
  • Section 2: Archetype hook sets (Router, Implementer, Reviewer, Documenter, Orchestrator, Researcher)

After creating a hook, you MUST add it to both the matrix AND update affected agents' ## Enforcement Hooks sections.

Claude Code Hook Types

Hook Event When Triggered Use Case
PreToolUse Before tool executes Validation, blocking, permission checks
PostToolUse After tool completes Logging, cleanup, notifications
UserPromptSubmit Before model sees message Routing, intent analysis, filtering

Workflow Steps

Step 0: Existence Check and Updater Delegation (MANDATORY - FIRST STEP)

BEFORE creating any hook file, check if it already exists:

  1. Check if hook already exists:

    test -f .claude/hooks/<category>/<hook-name>.cjs && echo "EXISTS" || echo "NEW"

  2. If hook EXISTS:

    • DO NOT proceed with creation

    • Invoke artifact-updater workflow instead:

      Skill({
  skill: 'artifact-updater',
  args: '--type hook --path .claude/hooks/<category>/<hook-name>.cjs --changes "<description of requested changes>"',
});

    • Return updater result and STOP

  3. If hook is NEW:

    • Continue with Step 0.5 below

Step 0.1: Smart Duplicate Detection (MANDATORY)

Before proceeding with creation, run the 3-layer duplicate check:

const { checkDuplicate } = require('.claude/lib/creation/duplicate-detector.cjs');
const result = checkDuplicate({
  artifactType: 'hook',
  name: proposedName,
  description: proposedDescription,
  keywords: proposedKeywords || [],
});

Handle results:

  • EXACT_MATCH: Stop creation. Route to hook-updater skill instead: Skill({ skill: 'hook-updater' })
  • REGISTRY_MATCH: Warn user — artifact is registered but file may be missing. Investigate before creating. Ask user to confirm.
  • SIMILAR_FOUND: Display candidates with scores. Ask user: "Similar artifact(s) exist. Continue with new creation or update existing?"
  • NO_MATCH: Proceed to Step 0.5 (companion check).

Override: If user explicitly passes --force, skip this check entirely.

Step 0.5: Companion Check

Before proceeding with creation, run the ecosystem companion check:

  1. Use companion-check.cjs from .claude/lib/creators/companion-check.cjs
  2. Call checkCompanions("hook", "{hook-name}") to identify companion artifacts
  3. Review the companion checklist — note which required/recommended companions are missing
  4. Plan to create or verify missing companions after this artifact is complete
  5. Include companion findings in post-creation integration notes

This step is informational (does not block creation) but ensures the full artifact ecosystem is considered.

Reference Hook

Use .claude/lib/routing/routing-table.cjs as the canonical routing reference.

Before finalizing any hook, compare against routing-table structure:

  • Has proper CommonJS exports (module.exports)
  • Exports required functions for hook type (validate, main, etc.)
  • Has comprehensive test file (.test.cjs)
  • Has proper error handling (try/catch, graceful fallbacks)
  • Returns correct response format for hook type

Step 1: Gather Hook Requirements

Before creating a hook, gather:

  1. Purpose: What should this hook do?
  2. Trigger: When should it run? (pre-tool, post-tool, session event)
  3. Target tools: Which tools does it apply to? (Bash, Write, Edit, Read)
  4. Behavior: Block operation or warn only?
  5. Exit codes: What indicates success/failure?
// Example requirements gathering
{
  purpose: "Validate git push commands to prevent force push",
  trigger: "pre-tool (Bash)",
  target_tools: ["Bash"],
  behavior: "block if force push detected",
  exit_codes: { 0: "allow", 1: "block" }
}

Step 2: Determine Hook Type and Location

If hook does... Type Location
Validates commands Safety .claude/hooks/safety/
Modifies routing Routing .claude/hooks/routing/
Updates memory Memory .claude/hooks/memory/
Session init/cleanup Session .claude/hooks/session/

Naming Convention: <action>-<target>.cjs

Examples:

  • validate-git-force-push.cjs
  • enforce-tdd-workflow.cjs
  • extract-workflow-learnings.cjs
  • memory-reminder.cjs

Step 3: Generate Hook Code (CJS Format)

All hooks use CommonJS format and follow this template:

'use strict';

/**
 * {Hook Name}
 *
 * Type: {pre|post}-{tool} | session-{start|end} | user-prompt
 * Purpose: {One line description}
 * Trigger: {When this hook runs}
 *
 * Exit codes:
 * - 0: Allow operation (with optional warning)
 * - 1: Block operation (when in blocking mode)
 *
 * Environment:
 *   {HOOK_NAME}_MODE=block|warn|off (default: warn unless explicitly required)
 */

const fs = require('fs');
const path = require('path');

// Find project root by looking for .claude directory
function findProjectRoot() {
  let dir = __dirname;
  while (dir !== path.parse(dir).root) {
    if (fs.existsSync(path.join(dir, '.claude'))) {
      return dir;
    }
    dir = path.dirname(dir);
  }
  return process.cwd();
}

const PROJECT_ROOT = findProjectRoot();
const ENFORCEMENT_MODE = process.env.HOOK_NAME_MODE || 'warn';

/**
 * Parse hook input from Claude Code
 * Claude Code passes JSON via process.argv[2] for hooks
 * @returns {Object|null} Parsed hook input or null
 */
function parseHookInput() {
  try {
    if (process.argv[2]) {
      return JSON.parse(process.argv[2]);
    }
  } catch (e) {
    // Fallback for testing or invalid input
  }
  return null;
}

/**
 * Validate hook - called by Claude Code or programmatically
 * @param {Object} context - Hook context with tool info
 * @param {string} context.tool - Tool name (Bash, Write, Edit, Read)
 * @param {Object} context.parameters - Tool parameters
 * @returns {Object} Validation result with valid (boolean), error (string), and optional warning (string)
 */
function validate(context) {
  const { tool, parameters } = context;

  // YOUR VALIDATION LOGIC HERE

  // Return validation result
  return { valid: true, error: '' };
}

/**
 * Main execution for CLI hook usage
 */
function main() {
  // Skip if enforcement is off
  if (ENFORCEMENT_MODE === 'off') {
    process.exit(0);
  }

  const hookInput = parseHookInput();
  if (!hookInput) {
    process.exit(0);
  }

  // Get tool name and input
  const toolName = hookInput.tool_name || hookInput.tool;
  const toolInput = hookInput.tool_input || hookInput.input || {};

  // Run validation
  const result = validate({ tool: toolName, parameters: toolInput });

  if (!result.valid) {
    if (ENFORCEMENT_MODE === 'block') {
      console.error(`BLOCKED: ${result.error}`);
      process.exit(1);
    } else {
      console.warn(`WARNING: ${result.error}`);
      process.exit(0);
    }
  }

  if (result.warning) {
    console.warn(`WARNING: ${result.warning}`);
  }

  process.exit(0);
}

// Run main if executed directly
if (require.main === module) {
  main();
}

// Export for programmatic use and testing
module.exports = {
  validate,
  findProjectRoot,
  PROJECT_ROOT,
};

Step 4: Create Test File

Every hook MUST have a corresponding test file:

'use strict';

const { validate } = require('./hook-name.cjs');

describe('Hook Name', () => {
  test('allows valid operations', () => {
    const result = validate({
      tool: 'Bash',
      parameters: { command: 'git status' },
    });
    expect(result.valid).toBe(true);
    expect(result.error).toBe('');
  });

  test('blocks dangerous operations', () => {
    const result = validate({
      tool: 'Bash',
      parameters: { command: 'git push --force' },
    });
    expect(result.valid).toBe(false);
    expect(result.error).toContain('force push');
  });

  test('handles missing parameters gracefully', () => {
    const result = validate({
      tool: 'Bash',
      parameters: {},
    });
    expect(result.valid).toBe(true);
  });
});

Step 5: Register Hook (If Needed)

Some hooks require registration in config files:

For pre/post-tool hooks (settings.json):

{
  "hooks": {
    "pre-tool": [".claude/hooks/safety/hook-name.cjs"],
    "post-tool": [".claude/hooks/memory/hook-name.cjs"]
  }
}

For event hooks (config.yaml):

hooks:
  UserPromptSubmit:
    - path: .claude/hooks/routing/hook-name.cjs
      type: command
  SessionStart:
    - path: .claude/hooks/session/hook-name.cjs
      type: command

Step 6: Update Documentation (MANDATORY - BLOCKING)

After creating a hook, update .claude/hooks/README.md:

#### {Hook Name} (`hook-name.cjs`)

{Description of what the hook does}

**When it runs:** {Trigger condition}
**What it checks/does:** {Detailed behavior}

Verify with:

grep "hook-name" .claude/hooks/README.md || echo "ERROR: Not documented!"

Step 7: System Impact Analysis (MANDATORY)

This analysis is MANDATORY. Hook creation is INCOMPLETE without it.

After creating a hook:

  1. Settings Registration (BLOCKING)

    • Add to .claude/settings.json PreToolUse/PostToolUse/etc.
    • Verify with: grep "hook-name" .claude/settings.json

  2. Test Coverage (BLOCKING)

    • Create .test.cjs file with minimum 10 test cases
    • Run tests: node .claude/hooks/<category>/<name>.test.cjs

  3. Documentation

    • Update .claude/docs/ if hook adds new capability
    • Add usage examples

  4. Related Hooks

    • Check if hook affects other hooks in same trigger category
    • Document interaction patterns

Full Checklist:

[HOOK-CREATOR] System Impact Analysis for: <hook-name>

1. HOOK FILE CREATED
   [ ] Created at .claude/hooks/<type>/<hook-name>.cjs
   [ ] Follows CJS format with validate() export
   [ ] Has main() function for CLI execution
   [ ] Handles graceful degradation (warn by default)

2. TEST FILE CREATED (minimum 10 test cases)
   [ ] Created at .claude/hooks/<type>/<hook-name>.test.cjs
   [ ] Tests valid operations (3+ cases)
   [ ] Tests blocked operations (3+ cases)
   [ ] Tests edge cases (3+ cases)
   [ ] Tests error handling (1+ cases)

3. DOCUMENTATION UPDATED
   [ ] Added to .claude/hooks/README.md
   [ ] Documented trigger conditions
   [ ] Documented exit codes

4. REGISTRATION (BLOCKING)
   [ ] Added to settings.json (pre/post-tool hooks)
   [ ] Added to config.yaml (event hooks)
   [ ] Verified: grep "<hook-name>" .claude/settings.json

5. MEMORY UPDATED
   [ ] Added to learnings.md with hook summary

6. HOOK-AGENT MAP UPDATED (MANDATORY)
   [ ] Added new hook to @HOOK_AGENT_MAP.md Section 1 matrix
   [ ] Determined which agent archetypes are affected (based on hook trigger/tool target)
   [ ] Updated affected agents' `## Enforcement Hooks` sections
   [ ] Verified: `grep "<hook-name>" .claude/docs/@HOOK_AGENT_MAP.md || echo "ERROR: Hook not in agent map!"`

BLOCKING: If ANY item above is missing, hook creation is INCOMPLETE.

Step 8: Post-Creation Hook Registration (Phase 1 Integration)

This step is CRITICAL. After creating the hook artifact, you MUST register it in the hook discovery system.

Phase 1 Context: Phase 1 is responsible for tool and hook validation/discovery. Hooks created without registration are invisible to the system and will not be loaded at startup.

After hook file is written and tested:

  1. Create/Update Hook Registry Entry in appropriate location:

    If registry doesn't exist, create .claude/context/artifacts/hook-registry.json:

    {
  "hooks": [
    {
      "name": "{hook-name}",
      "id": "{hook-name}",
      "description": "{Brief description from hook}",
      "category": "{safety|routing|memory|session|validation|audit}",
      "type": "{pre-tool|post-tool|user-prompt|session-start|session-end}",
      "version": "1.0.0",
      "targetTools": ["{Tool1}", "{Tool2}"],
      "enforcementMode": "{block|warn|off}",
      "defaultEnabled": true,
      "filePath": ".claude/hooks/{category}/{hook-name}.cjs",
      "testFilePath": ".claude/hooks/{category}/{hook-name}.test.cjs",
      "environmentVariable": "{HOOK_NAME}_MODE"
    }
  ]
}

  2. Validate Hook Against Schema:

    Ensure hook validates against .claude/schemas/hook-schema.json (if exists):

    # Validate hook structure
node -e "
  const hook = require('./.claude/hooks/{category}/{hook-name}.cjs');
  if (hook.validate) console.log('✓ Has validate() export');
  if (hook.PROJECT_ROOT) console.log('✓ Has PROJECT_ROOT');
  if (hook.findProjectRoot) console.log('✓ Has findProjectRoot()');
"

  3. Register Hook in Loader:

    Update .claude/lib/hooks/hook-loader.cjs (if exists) to include new hook:

    const HOOKS_MANIFEST = {
  '{hook-name}': {
    path: './.claude/hooks/{category}/{hook-name}.cjs',
    type: '{pre-tool|post-tool}',
    matcher: '{Bash|Write|Edit|Read}', // Optional
    enabled: true,
    enforcementMode: process.env.{HOOK_NAME}_MODE || 'warn'
  }
};

  4. Register Hook in Configuration:

    For pre/post-tool hooks - Update .claude/settings.json:

    {
  "hooks": {
    "pre-tool": ["./.claude/hooks/safety/{hook-name}.cjs"],
    "post-tool": ["./.claude/hooks/memory/{hook-name}.cjs"]
  }
}

    For event hooks - Update .claude/config.yaml:

    hooks:
  UserPromptSubmit:
    - path: ./.claude/hooks/routing/{hook-name}.cjs
      type: command
  SessionStart:
    - path: ./.claude/hooks/session/{hook-name}.cjs
      type: command

  5. Document in .claude/hooks/README.md:

    Add entry under appropriate category:

    #### {Hook Name} (`{hook-name}.cjs`)

{Detailed description of what the hook does.}

**When it runs:** {Trigger condition - e.g., "Before every Bash command", "After task completion"}

**What it checks/does:**

- {Check/action 1}
- {Check/action 2}
- {Check/action 3}

**Enforcement mode:** `process.env.{HOOK_NAME}_MODE` (default: `warn`)

**Test file:** `.claude/hooks/{category}/{hook-name}.test.cjs`

**Related hooks:** {List any hooks that interact with this one}

  6. Update Memory:

    Append to .claude/context/memory/learnings.md:

    ## Hook: {hook-name}

- **Type:** {pre-tool|post-tool|event}
- **Category:** {safety|routing|memory|session|validation}
- **Purpose:** {Detailed purpose}
- **Trigger:** {When it runs}
- **Enforcement:** {Block/warn/off by default}
- **Integration Notes:** {Any special considerations}

Why this matters: Without hook registration:

  • Hooks are not loaded at startup
  • Hook validation doesn't occur
  • System cannot discover available hooks
  • Safety validators are bypassed
  • "Invisible artifact" pattern emerges

Phase 1 Integration: Hook registry is the discovery mechanism for Phase 1, enabling the system to validate hooks against schema, load them at startup, and enforce safety rules consistently.

Step 9: Integration Verification (BLOCKING - DO NOT SKIP)

This step verifies the artifact is properly integrated into the ecosystem.

Before calling TaskUpdate({ status: "completed" }), you MUST run the Post-Creation Validation workflow:

  1. Run the 10-item integration checklist:

    node .claude/tools/cli/validate-integration.cjs .claude/hooks/<category>/<hook-name>.cjs

  2. Verify exit code is 0 (all checks passed)

  3. If exit code is 1 (one or more checks failed):

    • Read the error output for specific failures
    • Fix each failure:
      • Missing hook registry -> Create registry entry (Step 8)
      • Missing settings.json entry -> Register hook (Step 8)
      • Missing documentation -> Add to hooks/README.md
      • Missing memory update -> Update learnings.md
      • Missing test file -> Create .test.cjs file
    • Re-run validation until exit code is 0

  4. Only proceed when validation passes

This step is BLOCKING. Do NOT mark task complete until validation passes.

Why this matters: The Party Mode incident showed that fully-implemented artifacts can be invisible to the Router if integration steps are missed. This validation ensures no "invisible artifact" pattern.

Reference: .claude/workflows/core/post-creation-validation.md

CLI Reference

# Create hook using CLI tool
node .claude/tools/hook-creator/create-hook.mjs \
  --name "hook-name" \
  --type "PreToolUse|PostToolUse|UserPromptSubmit" \
  --purpose "Description of what the hook does" \
  --category "safety|routing|memory|audit|security|validation|custom" \
  --matcher "Edit|Write|Bash"  # Optional: tool matcher regex

# List all hooks
node .claude/tools/hook-creator/create-hook.mjs --list

# Validate hook structure
node .claude/tools/hook-creator/create-hook.mjs --validate "<path>"

# Assign to agents
node .claude/tools/hook-creator/create-hook.mjs --assign "name" --agents "agent1,agent2"

# Unregister hook
node .claude/tools/hook-creator/create-hook.mjs --unregister "<path>"

# Test with sample input
echo '{"tool_name":"Edit","tool_input":{"file_path":"test.js"} }' | node .claude/hooks/<category>/<hook-name>.cjs

Hook Patterns Reference

Pattern 1: Safety Validator (Pre-Tool)

For validating commands before execution:

'use strict';

/**
 * Validate Git Force Push
 * Prevents accidental force pushes to protected branches
 */

const PROTECTED_BRANCHES = ['main', 'master', 'production'];

function validate(context) {
  const { tool, parameters } = context;

  if (tool !== 'Bash') {
    return { valid: true, error: '' };
  }

  const command = parameters?.command || '';

  // Check for force push
  if (command.includes('git push') && (command.includes('--force') || command.includes('-f'))) {
    // Check if pushing to protected branch
    for (const branch of PROTECTED_BRANCHES) {
      if (command.includes(branch)) {
        return {
          valid: false,
          error: `Force push to ${branch} blocked. Use --force-with-lease instead.`,
        };
      }
    }

    return {
      valid: true,
      error: '',
      warning: 'Force push detected. Ensure you know what you are doing.',
    };
  }

  return { valid: true, error: '' };
}

module.exports = { validate };

Pattern 2: Memory Extractor (Post-Tool)

For extracting learnings after task completion:

'use strict';

/**
 * Extract Workflow Learnings
 * Automatically captures patterns from completed workflows
 */

const fs = require('fs');
const path = require('path');

function findProjectRoot() {
  let dir = __dirname;
  while (dir !== path.parse(dir).root) {
    if (fs.existsSync(path.join(dir, '.claude'))) return dir;
    dir = path.dirname(dir);
  }
  return process.cwd();
}

const LEARNINGS_PATH = path.join(findProjectRoot(), '.claude/context/memory/learnings.md');

function extractLearnings(context) {
  const { tool, parameters, result } = context;

  // Only process completed tasks
  if (!result || result.status !== 'completed') {
    return { extracted: false };
  }

  // Extract patterns from result
  const learnings = [];

  if (result.patterns) {
    learnings.push(...result.patterns);
  }

  if (result.decisions) {
    learnings.push(...result.decisions);
  }

  if (learnings.length === 0) {
    return { extracted: false };
  }

  // Append to learnings file
  const entry = `\n## [${new Date().toISOString().split('T')[0]}] ${context.taskName || 'Task'}\n\n`;
  const content = learnings.map(l => `- ${l}`).join('\n');

  fs.appendFileSync(LEARNINGS_PATH, entry + content + '\n');

  return { extracted: true, count: learnings.length };
}

module.exports = { extractLearnings };

Pattern 3: Routing Enforcer (User Prompt)

For enforcing routing protocols:

'use strict';

/**
 * Router First Enforcer
 * Ensures all requests go through the Router agent
 */

function validate(context) {
  const { prompt, currentAgent } = context;

  // Skip if already routed
  if (currentAgent === 'router') {
    return { valid: true, error: '' };
  }

  // Skip slash commands (handled by skill system)
  if (prompt && prompt.trim().startsWith('/')) {
    return { valid: true, error: '' };
  }

  // Suggest routing
  return {
    valid: true,
    error: '',
    warning: 'Consider using Router to spawn appropriate agent via Task tool.',
  };
}

module.exports = { validate };

Pattern 4: Session Initializer

For session lifecycle management:

'use strict';

/**
 * Session Memory Initializer
 * Reminds agents to read memory files at session start
 */

const fs = require('fs');
const path = require('path');

function findProjectRoot() {
  let dir = __dirname;
  while (dir !== path.parse(dir).root) {
    if (fs.existsSync(path.join(dir, '.claude'))) return dir;
    dir = path.dirname(dir);
  }
  return process.cwd();
}

const MEMORY_FILES = [
  '.claude/context/memory/learnings.md',
  '.claude/context/memory/issues.md',
  '.claude/context/memory/decisions.md',
];

function initialize() {
  const root = findProjectRoot();

  console.log('\n' + '='.repeat(50));
  console.log(' SESSION MEMORY REMINDER');
  console.log('='.repeat(50));
  console.log('\n  Before starting work, read these memory files:');

  for (const file of MEMORY_FILES) {
    const fullPath = path.join(root, file);
    if (fs.existsSync(fullPath)) {
      const stats = fs.statSync(fullPath);
      const modified = stats.mtime.toISOString().split('T')[0];
      console.log(`  - ${file} (updated: ${modified})`);
    }
  }

  console.log('\n' + '='.repeat(50) + '\n');

  return { initialized: true };
}

// Run on direct execution
if (require.main === module) {
  initialize();
}

module.exports = { initialize };

Examples

Security Validation Hook

node .claude/tools/hook-creator/create-hook.mjs \
  --name "secret-detector" \
  --type "PreToolUse" \
  --purpose "Blocks commits containing secrets or credentials" \
  --category "security" \
  --matcher "Bash"

Audit Logging Hook

node .claude/tools/hook-creator/create-hook.mjs \
  --name "operation-logger" \
  --type "PostToolUse" \
  --purpose "Logs all file modifications to audit trail" \
  --category "audit"

Intent Analysis Hook

node .claude/tools/hook-creator/create-hook.mjs \
  --name "intent-classifier" \
  --type "UserPromptSubmit" \
  --purpose "Classifies user intent for intelligent routing" \
  --category "routing"

Workflow Integration

This skill is part of the unified artifact lifecycle. For complete multi-agent orchestration:

Router Decision: .claude/workflows/core/router-decision.md

  • How the Router discovers and invokes this skill's artifacts

Artifact Lifecycle: .claude/workflows/core/skill-lifecycle.md

  • Discovery, creation, update, deprecation phases
  • Version management and registry updates
  • CLAUDE.md integration requirements

External Integration: .claude/workflows/core/external-integration.md

  • Safe integration of external artifacts
  • Security review and validation phases

Cross-Reference: Creator Ecosystem

This skill is part of the Creator Ecosystem. After creating a hook, consider if companion artifacts are needed:

Gap Discovered Required Artifact Creator to Invoke When
Domain knowledge needs a reusable skill skill Skill({ skill: 'skill-creator' }) Gap is a full skill domain
Existing skill has incomplete coverage skill update Skill({ skill: 'skill-updater' }) Close skill exists but incomplete
Capability needs a dedicated agent agent Skill({ skill: 'agent-creator' }) Agent to own the capability
Existing agent needs capability update agent update Skill({ skill: 'agent-updater' }) Close agent exists but incomplete
Domain needs code/project scaffolding template Skill({ skill: 'template-creator' }) Reusable code patterns needed
Behavior needs pre/post execution guards hook Skill({ skill: 'hook-creator' }) Enforcement behavior required
Process needs multi-phase orchestration workflow Skill({ skill: 'workflow-creator' }) Multi-step coordination needed
Artifact needs structured I/O validation schema Skill({ skill: 'schema-creator' }) JSON schema for artifact I/O
User interaction needs a slash command command Skill({ skill: 'command-creator' }) User-facing shortcut needed
Repeated logic needs a reusable CLI tool tool Skill({ skill: 'tool-creator' }) CLI utility needed
Narrow/single-artifact capability only inline Document within this artifact only Too specific to generalize

Integration Workflow

After creating a hook that needs additional capabilities:

// 1. Hook created but needs dedicated skill
Skill({ skill: 'skill-creator' });
// Create skill that encapsulates hook logic

// 2. Hook needs to be assigned to agent
// Update agent's workflow to include hook awareness

// 3. Hook needs workflow for testing
// Create workflow in .claude/workflows/<hook-name>-test-workflow.md

Post-Creation Checklist for Ecosystem Integration

After hook is fully created and validated:

[ ] Does hook need a skill wrapper? -> Use skill-creator
[ ] Does hook need dedicated agent? -> Use agent-creator
[ ] Does hook need testing workflow? -> Create workflow
[ ] Should hook be enabled by default? -> Update config.yaml
[ ] Does hook interact with other hooks? -> Document in README.md
[ ] Run post-creation validation -> node .claude/tools/cli/validate-integration.cjs .claude/hooks/<category>/<hook-name>.cjs

Iron Laws of Hook Creation

These rules are INVIOLABLE. Breaking them causes silent failures.

1. NO HOOK WITHOUT validate() EXPORT
   - Every hook MUST export validate() function
   - Hooks without validate() cannot be called programmatically

2. NO HOOK WITHOUT main() FOR CLI
   - Every hook MUST have main() for CLI execution
   - Run only when require.main === module

3. NO HOOK WITHOUT ENFORCEMENT CONTROLS
   - Support 'block|warn|off' via environment variable
   - Default to 'warn' unless explicitly required to block
   - Never crash on malformed input

4. NO HOOK WITHOUT ERROR HANDLING
   - Wrap JSON.parse in try/catch
   - Handle missing parameters gracefully
   - Return valid: true when unsure (fail open, not closed)

5. NO HOOK WITHOUT TEST FILE
   - Every hook needs <hook-name>.test.cjs
   - Test valid, invalid, and edge cases

6. NO HOOK WITHOUT DOCUMENTATION
   - Add to .claude/hooks/README.md
   - Document trigger, behavior, exit codes

7. CROSS-PLATFORM PATHS
   - Use path.join() not string concatenation
   - Handle both / and \ path separators
   - Use path.normalize() for comparison

8. NO CREATION WITHOUT SYSTEM IMPACT ANALYSIS
   - Check if hook requires settings.json registration
   - Check if hook requires config.yaml registration
   - Update @HOOK_AGENT_MAP.md with new hook row (MANDATORY)
   - Update affected agents' Enforcement Hooks sections (MANDATORY)
   - Check if related hooks need updating
   - Document all system changes made

9. IRON LAW I: PRE-TOOL HOOKS MUST VALIDATE AGAINST JSON SCHEMA
   - PreToolUse hooks MUST compile and validate input against the companion
     schemas/input.schema.json using AJV or equivalent before allowing execution
   - Pattern: compile(schema) → validate(input) → exit 2 on schema failure
   - Never block (exit 2) on schema-load errors — fail open, not closed
   - Search: site:github.com "preToolUse" "ajv" "validate" filetype:cjs

10. IRON LAW III: POST-TOOL HOOKS MUST EMIT OBSERVABILITY EVENTS
    - PostToolUse hooks MUST append a structured JSON line to
      .claude/context/runtime/tool-events.jsonl via the centralized emitter:
      const { sendEvent } = require('.claude/tools/observability/send-event.cjs')
    - Required fields: tool_name, agent_id, session_id, outcome, timestamp
    - Never crash on emit failure (try/catch, fail open)
    - Inspect events: node .claude/tools/observability/send-event.cjs --tail 20

Integration Points

  • Ecosystem Assessor: Hook creator integrates with ecosystem assessment for reverse lookups
  • Agent Creator: Agents can reference hooks in their frontmatter
  • Skill Creator: Skills can define hooks in their hooks/ directory
  • Settings.json: Hooks are auto-registered with proper triggers and matchers
  • Config.yaml: Event hooks registered for UserPromptSubmit, SessionStart, etc.

Architecture Compliance

File Placement (ADR-076)

  • Hooks: .claude/hooks/{category}/ (safety, routing, memory, session, validation, audit)
  • Hook tests: .claude/hooks/{category}/{name}.test.cjs (co-located with hooks)
  • Tests: tests/ (integration tests for hooks)
  • Related docs: .claude/docs/
  • Hook registry: .claude/hooks/README.md

Documentation References (CLAUDE.md v2.2.1)

  • Reference files use @notation: @ENFORCEMENT_HOOKS.md, @TOOL_REFERENCE.md
  • Located in: .claude/docs/@*.md
  • See: CLAUDE.md Section 1.3 (ENFORCEMENT HOOKS reference)

Shell Security (ADR-077)

  • NEW SAFETY HOOKS: bash-cwd-validator.cjs, shell-injection-validator.cjs, variable-quoting-validator.cjs (ADR-077 Phase 2)
  • PHASE 3 HOOKS: shellcheck-validator.cjs, command-allowlist-validator.cjs (reference implementations)
  • Hook tests MUST validate shell security patterns
  • See: .claude/docs/SHELL-SECURITY-GUIDE.md
  • Apply to: all safety hooks, pre-tool hooks, validation hooks

Recent ADRs

  • ADR-075: Router Config-Aware Model Selection
  • ADR-076: File Placement Architecture Redesign
  • ADR-077: Shell Command Security Architecture

File Placement & Standards

Output Location Rules

This skill outputs to: .claude/hooks/<category>/

Categories:

  • safety/ - Safety validators (command validation, security checks, shell security)
  • routing/ - Router enforcement hooks
  • memory/ - Memory management hooks
  • session/ - Session lifecycle hooks
  • validation/ - Input/output validation hooks

Mandatory References

  • File Placement: See .claude/docs/FILE_PLACEMENT_RULES.md
  • Developer Workflow: See .claude/docs/DEVELOPER_WORKFLOW.md
  • Artifact Naming: See .claude/docs/ARTIFACT_NAMING.md

Enforcement

File placement is enforced by file-placement-guard.cjs hook. Invalid placements will be blocked in production mode.

Memory Protocol (MANDATORY)

Before creating a hook:

cat .claude/context/memory/learnings.md

Check for:

  • Previously created hooks
  • Known hook patterns
  • User preferences for hook behavior

After completing:

  • New hook created -> Append to .claude/context/memory/learnings.md
  • Issue with hook -> Append to .claude/context/memory/issues.md
  • Hook design decision -> Append to .claude/context/memory/decisions.md

ASSUME INTERRUPTION: Your context may reset. If it's not in memory, it didn't happen.

Ecosystem Alignment Contract (MANDATORY)

This creator skill is part of a coordinated creator ecosystem. Any artifact created here must align with and validate against related creators:

  • agent-creator for ownership and execution paths
  • skill-creator for capability packaging and assignment
  • tool-creator for executable automation surfaces
  • hook-creator for enforcement and guardrails
  • rule-creator and semgrep-rule-creator for policy and static checks
  • template-creator for standardized scaffolds
  • workflow-creator for orchestration and phase gating
  • command-creator for user/operator command UX

Cross-Creator Handshake (Required)

Before completion, verify all relevant handshakes:

  1. Artifact route exists in .claude/CLAUDE.md and related routing docs.
  2. Discovery/registry entries are updated (catalog/index/registry as applicable).
  3. Companion artifacts are created or explicitly waived with reason.
  4. validate-integration.cjs passes for the created artifact.
  5. Skill index is regenerated when skill metadata changes.

Research Gate (Exa + arXiv — BOTH MANDATORY)

For new patterns, templates, or workflows, research is mandatory:

  1. Use Exa for implementation and ecosystem patterns:
    • mcp__Exa__web_search_exa({ query: '<topic> 2025 best practices' })
    • mcp__Exa__get_code_context_exa({ query: '<topic> implementation examples' })
  2. Search arXiv for academic research (mandatory for AI/ML, agents, evaluation, orchestration, memory/RAG, security):
    • Via Exa: mcp__Exa__web_search_exa({ query: 'site:arxiv.org <topic> 2024 2025' })
    • Direct API: WebFetch({ url: 'https://arxiv.org/search/?query=<topic>&searchtype=all&start=0' })
  3. Record decisions, constraints, and non-goals in artifact references/docs.
  4. Keep updates minimal and avoid overengineering.

arXiv is mandatory (not fallback) when topic involves: AI agents, LLM evaluation, orchestration, memory/RAG, security, static analysis, or any emerging methodology.

Regression-Safe Delivery

  • Follow strict RED -> GREEN -> REFACTOR for behavior changes.
  • Run targeted tests for changed modules.
  • Run lint/format on changed files.
  • Keep commits scoped by concern (logic/docs/generated artifacts).

Optional: Evaluation Quality Gate

Run the shared evaluation framework to verify hook quality:

node .claude/skills/skill-creator/scripts/eval-runner.cjs --skill hook-creator

Grader assertions for hook artifacts:

  • Exit codes correct: Hook exits 0 (allow) or 2 (block) only; exit 1 is never used (treated as error, not block per SE-03)
  • 100ms performance budget: Hook body completes in under 100ms; no network calls, no blocking I/O, no long computation in the hot path
  • Fail-open vs fail-closed policy: Security hooks (routing, creator, write) are fail-closed (process.exit(2) on errors); advisory and PostToolUse hooks are fail-open (process.exit(0) on errors)
  • Graceful error handling: Hook body is wrapped in try/catch; unexpected errors exit 0 (non-critical) or 2 (security-critical) — never crash without an exit code
  • Registration complete: Hook is registered in .claude/settings.json and documented in @ENFORCEMENT_HOOKS.md

See .claude/skills/skill-creator/EVAL_WORKFLOW.md for full evaluation protocol and grader/analyzer agent usage.

Weekly Installs
55
Repository
oimiragieo/agent-studio
GitHub Stars
16
First Seen
Jan 27, 2026
Security Audits
Gen Agent Trust HubPass
SocketPass
SnykWarn
Installed on
github-copilot52
opencode51
gemini-cli51
codex51
cursor51
amp50