Hooks & Events
Relevant source files
The following files were used as context for generating this wiki page:
The Hooks & Events system in SkillKit provides a robust mechanism for the automatic triggering of skills based on lifecycle events within a development environment. By monitoring actions such as file saves, git commits, or session starts, the system can inject relevant skill instructions or prompts directly into the AI agent's context, ensuring that specific methodologies or rules are followed without manual invocation.
This system acts as a bridge between the project's operational state and the AI agent's knowledge base. It supports a wide variety of events and provides agent-specific configuration generation for major AI coding assistants like Claude Code and Cursor.
Sources: packages/core/src/hooks/manager.ts:1-12, packages/cli/src/commands/hook.ts:1-7
Core Architecture
The architecture revolves around the HookManager, which serves as the central registry and execution engine for skill hooks. It handles the lifecycle of hooks—registration, persistence, and triggering—and manages listeners that respond to successful trigger events.
Hook Lifecycle and Management
Hooks are stored as SkillHook objects, containing metadata about the event they target, the skills they activate, and the method of injection. The HookManager maintains these in an internal Map for efficient lookup and provides methods for enabling, disabling, or updating them.
The diagram shows the relationship between the HookManager, its internal memory registry, and the persistent JSON storage used to maintain hooks across sessions.
Sources: packages/core/src/hooks/manager.ts:25-45, packages/core/src/hooks/manager.ts:145-177
Trigger Logic
When an event is triggered, the HookManager performs a multi-step evaluation:
- Event Matching: It filters hooks specifically registered for the incoming
HookEvent. - Pattern Matching: It evaluates the
matcher(often a glob or RegExp) against the trigger string (e.g., a file path). - Condition Evaluation: It executes basic logic strings (e.g.,
event == 'file:save') to further narrow down applicable hooks. - Skill Activation: For each matched hook, it prepares the skill for injection based on the configured mode (content, reference, or prompt).
This sequence illustrates how a single trigger call evaluates multiple hooks and activates associated skills.
Sources: packages/core/src/hooks/manager.ts:86-130, packages/core/src/hooks/tests/hooks.test.ts:153-189
Hook Configuration and Data Models
Hooks are persisted in a standard JSON format, typically located at .skillkit/hooks.json. This configuration defines both individual hooks and default behaviors.
Data Model: SkillHook
| Field | Type | Description |
|---|---|---|
id | string | Unique identifier (often a UUID). |
event | HookEvent | The lifecycle event that triggers this hook (e.g., file:save). |
skills | string[] | List of skill IDs to activate. |
inject | InjectionMode | How the skill is presented: reference, content, or prompt. |
matcher | string | RegExp | Optional pattern matcher (glob for files). |
condition | string | Optional logic expression for advanced filtering. |
priority | number | Execution order; higher numbers run earlier. |
enabled | boolean | Whether the hook is currently active. |
Sources: packages/core/src/hooks/manager.ts:34-45, packages/cli/src/commands/hook.ts:190-210
Supported Events
The system supports a comprehensive list of lifecycle events:
- Session Events:
session:start,session:resume,session:end - File Events:
file:open,file:save,file:create,file:delete - Task/Project Events:
task:start,task:complete,build:start,build:fail,build:success - Git Events:
commit:pre,commit:post - Quality Events:
error:occur,test:fail,test:pass
Sources: packages/cli/src/commands/hook.ts:110-120, packages/core/src/hooks/tests/hooks.test.ts:446-465
Agent Integration
A critical feature of the system is translating internal hooks into formats understood by external AI agents. The HookManager generates configuration for specific agents based on their supported triggers.
Claude Code Integration
For Claude Code, SkillKit maps its internal events to Claude's native hook system (e.g., mapping session:start to SessionStart). It generates a hooks.json structure containing commands that echo skill references.
Sources: packages/core/src/hooks/manager.ts:192-230
Cursor and Other Agents
For agents like Cursor, the system generates markdown-based rules (MDC) that instruct the agent to apply specific skills when certain file patterns or events are detected.
Sources: packages/core/src/hooks/manager.ts:241-255, packages/core/src/skill-translator.ts:500-525
CLI Usage
The HookCommand provides the user interface for managing these triggers.
| Action | Example Command | Purpose |
|---|---|---|
add | skillkit hook add file:save tdd-patterns --pattern "*.ts" | Registers a new trigger. |
list | skillkit hook list --verbose | Displays all configured hooks and status. |
remove | skillkit hook remove <id> | Deletes a hook by its ID. |
enable/disable | skillkit hook disable <id> | Toggles hook activity without deleting. |
generate | skillkit hook generate --agent cursor | Outputs agent-specific config. |
Sources: packages/cli/src/commands/hook.ts:15-25, e2e/hooks-orchestration.e2e.test.ts:40-100
Injection Modes
The inject property determines how a skill is delivered to the AI agent during a hook trigger:
reference: Injects a reference (e.g.,@skill-name) for the agent to resolve.content: Loads the full content of theSKILL.mdfile directly into the context.prompt: Injects a natural language instruction (e.g., "Please apply the [skill] to this task").
Sources: packages/core/src/hooks/manager.ts:375-395, packages/core/src/hooks/tests/hooks.test.ts:193-215
Summary
The Hooks & Events system enables "auto-pilot" mode for skills within the SkillKit ecosystem. By automating the activation of skills through lifecycle events and glob matching, it reduces the cognitive overhead for developers and ensures that coding methodologies are applied consistently across different AI agents. The HookManager provides the logic for this automation, while the CLI offers a simple interface for registration and agent-specific configuration generation.