hook-creator

Create and manage xbot lifecycle hooks with YAML configuration.

12|5|Updated Apr 26, 2026
One-click install
npx skills add https://github.com/ai-pivot/xbot --skill hook-creator-ai-pivot
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: hook-creator
Source: https://github.com/ai-pivot/xbot/tree/main/tools/embed_skills/hook-creator
Command: npx skills add https://github.com/ai-pivot/xbot --skill hook-creator-ai-pivot

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

Hook-creator helps you create and manage AI Agent lifecycle hooks so you can enforce checks, run commands, and react to events without changing the core agent logic.

Core Features & Use Cases

  • Lifecycle event hook management: Add handlers for events like PreToolUse, PostToolUse, PermissionRequest, AgentError, and CronFired to control behavior at specific moments.
  • Config-driven 3-layer overrides: Merge hooks from ~/.xbot/hooks.json, <project>/.xbot/hooks.json, and <project>/.xbot/hooks.local.json to support personal, shared, and local settings.
  • Multiple handler types: Run command scripts (with optional filtering), trigger HTTP web requests, or call MCP tools with variable interpolation.
  • Decision control and guardrails: Apply deny/defer/ask/allow semantics (priority: deny > defer > ask > allow) and enable command hooks safely via enable_command_hooks.

Quick Start

Ask xbot to create a PreToolUse hook that runs a command only when the tool input contains the pattern you specify, writes it to the correct hooks.json layer, and then reloads hooks so the change takes effect immediately.

Frequently Asked Questions about hook-creator

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I add lifecycle hooks to control agent tool execution?

Lifecycle hooks control agent tool execution by configuring YAML logic with event matchers in hooks.json. You can add handlers for events like PreToolUse, PostToolUse, or PermissionRequest to enforce checks and run commands without altering core agent logic.

What are the available handler types for lifecycle event hooks?

Lifecycle event hooks support three handler types: command scripts with optional filtering, HTTP web requests, and MCP tool calls with variable interpolation. Each type allows you to react to agent events using different execution methods.

How do I configure permission gating for agent tools?

Permission gating uses deny, defer, ask, and allow semantics to control tool execution. You configure these decision rules in your hooks.json file, with deny taking the highest priority, to safely guardrail agent actions before they run.

How does the hooks.json configuration merge across different environments?

The hooks.json configuration merges across three layers: personal (~/.xbot/hooks.json), shared project (<project>/.xbot/hooks.json), and local project (<project>/.xbot/hooks.local.json). This 3-layer merge supports personal, shared, and local settings simultaneously.

Can I trigger an HTTP webhook when an agent encounters an error?

Yes, you can react to agent errors by configuring an AgentError lifecycle hook. This hook uses an HTTP handler type to trigger a web request, allowing you to send post-tool notifications or execute error recovery logic automatically.

Do I need YAML to set up cron-fired hooks for my agent?

Yes, setting up cron-fired hooks requires YAML-configured hook logic. You define a CronFired event matcher with the correct timeout and async settings in your hooks.json file to trigger scheduled command or HTTP reactions across session runs.