Proactive Patterns: Creating Auto-Triggering Components

Purpose

Expertise in designing skills, agents, and commands that activate proactively based on context, keywords, events, or checkpoints. Use this skill when creating components that should trigger automatically rather than requiring explicit invocation.

The Four Trigger Types

IMPORTANT CLARIFICATION: The “Keyword-Based (Skills)” section previously documented here was INCORRECT. Skills do NOT auto-load based on ## Activation Keywords sections - that was a documentation convention, not a real feature. Skills are discovered via the description field in SKILL.md YAML frontmatter.

1. Description-Based (Skills) - CORRECTED

Skills are discovered when Claude determines they’re relevant based on YAML frontmatter.

How it actually works:

Skills must be in subdirectory: .claude/skills/skill-name/SKILL.md
SKILL.md needs YAML frontmatter with name and description
Claude reads description and autonomously decides when to use skill
NO keyword matching - Claude uses semantic understanding of description

Design guidelines:

---
name: python-testing
description: Expertise in Python testing patterns including pytest, fixtures, mocking, and coverage. Use when user asks about testing, pytest, fixtures, or test coverage.
---

When to use:

Domain knowledge that should be available contextually
Conventions that apply when topics are discussed
Background expertise for specific areas

2. Description-Based (Agents)

Agents can be invoked proactively based on their description.

How it works:

Agent description field defines when to use
Including “Use PROACTIVELY when…” signals automatic invocation
Claude matches context against description

Design guidelines:

# Good - specific trigger condition
description: Use PROACTIVELY when user wants to organize files. Applies SEACOW thinking.

# Good - clear scope
description: Use PROACTIVELY after completing significant tasks to suggest improvements.

# Bad - too vague
description: Helps with files.

# Bad - no proactive signal
description: Organizes files using SEACOW framework.

Format:

Use PROACTIVELY when [specific condition]. [What it does in 10-15 words].

When to use:

Tasks that should happen automatically at certain points
Agents that provide value without explicit request
Workflow helpers that should be offered, not demanded

3. Event-Based (Hooks)

Hooks intercept events before they happen.

How it works:

Hook files define event type and pattern
Events: bash, file, stop, prompt, all
Can warn (show message) or block (prevent action)

Hook file format:

# Hook Name

## Event
bash | file | stop | prompt | all

## Pattern
[regex pattern to match]

## Action
warn | block

## Message
[What to show the user]

Example - Prevent dangerous commands:

# No Force Push

## Event
bash

## Pattern
git push.*--force|git push -f

## Action
block

## Message
Force push blocked. Use a safer alternative or explicitly override.

When to use:

Safety guardrails (prevent dangerous actions)
Reminders before certain operations
Enforcing conventions
Audit/logging triggers

Available events:

Event	Triggers On
`bash`	Before shell commands
`file`	Before file operations
`stop`	Before conversation ends
`prompt`	Before AI responds
`all`	Any tool use

Context Persistence Hooks (Manus Pattern)

These hooks maintain goal focus during long sessions. From the planning-with-files pattern.

The core principle: Context window = RAM (volatile, limited). Filesystem = Disk (persistent, unlimited). Anything important gets written to disk.

When to use:

Multi-step tasks (3+ phases)
Research spanning many tool calls
Sessions where goal drift is a risk

How to Enable

Add hooks to .claude/settings.local.json (create if it doesn’t exist):

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Write|Edit|Bash",
        "hooks": [
          {
            "type": "command",
            "command": "bash .claude/scripts/read-plan.sh 2>/dev/null || true"
          }
        ]
      }
    ],
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "echo '[Reminder] Update task_plan.md if phase complete' && [ -d knowledge-base ] && echo '[Knowledge] Capture insights → 00-inbox/ | Distill learnings → 02-learnings/'"
          }
        ]
      }
    ],
    "Stop": [
      {
        "hooks": [
          {
            "type": "command",
            "command": ".claude/scripts/check-complete.sh"
          },
          {
            "type": "command",
            "command": "bash .claude/scripts/check-knowledge.sh 2>/dev/null || true"
          }
        ]
      }
    ]
  }
}

Note: If you already have a settings.local.json, merge the hooks section into your existing file.

Scripts

The hooks use three scripts in .claude/scripts/:

Script	Hook	Purpose
`read-plan.sh`	PreToolUse	Smart plan reader — shows plan or detects empty `task_plan.md` and prompts to populate/delete
`check-complete.sh`	Stop	Verifies all phases in `task_plan.md` are marked complete before session end
`check-knowledge.sh`	Stop	Shows knowledge-base status and prompts for captures/promotions (silently skips if no `knowledge-base/`)

Copy during setup:

mkdir -p .claude/scripts
cp ~/.claude/scripts/read-plan.sh .claude/scripts/
cp ~/.claude/scripts/check-complete.sh .claude/scripts/
cp ~/.claude/scripts/check-knowledge.sh .claude/scripts/
chmod +x .claude/scripts/*.sh

The PostToolUse KB reminder ([ -d knowledge-base ] && echo ...) only fires when knowledge-base/ exists. Standard projects without a knowledge-base see only the plan reminder.

What Each Hook Does

Hook	Trigger	Purpose
PreToolUse	Before Write/Edit/Bash	Re-reads `task_plan.md` to refresh goals
PostToolUse	After Write/Edit	Reminds to update plan status
Stop	Before session ends	Verifies all phases complete via `check-complete.sh`

Creating task_plan.md

Run /task-plan to create a properly structured plan, or create manually. The hooks expect a plan file with this structure:

# Task: [Your Task Name]

### Phase 1: [Phase Name]
**Status:** pending | in_progress | complete

- [ ] Step 1
- [ ] Step 2

### Phase 2: [Phase Name]
**Status:** pending

- [ ] Step 1

The check-complete.sh script counts ### Phase headers and **Status:** complete lines to verify completion

Gradient Flow Hooks (Beyond Session Focus)

The Manus hooks above handle session focus (hot zone). For full temperature gradient support, the hooks also prompt knowledge capture:

PostToolUse — Mid-Session KB Awareness: The PostToolUse hook conditionally reminds about knowledge capture when knowledge-base/ exists:

[Reminder] Update task_plan.md if phase complete
[Knowledge] Capture insights → 00-inbox/ | Distill learnings → 02-learnings/

The second line only appears in projects with a knowledge-base/ directory.

Stop — Session End KB Review (check-knowledge.sh): At session end, check-knowledge.sh shows zone counts and prompts:

Inbox items to process (promote to working or learnings)
Working drafts to finalize (promote to learnings or reference)
Empty KB warning (prompt for any session insights)

Gradient Transition Prompts:

Trigger	Mechanism	Prompt
After every Write/Edit	PostToolUse (conditional)	“Capture insights → 00-inbox/ / Distill → 02-learnings/“
Session end	check-knowledge.sh	”Inbox has N items — process before stopping?”
Session end	check-knowledge.sh	”Working has N drafts — any ready to promote?”
Session end (empty KB)	check-knowledge.sh	”KB is empty. Any insights worth capturing?”

Temperature-Aware Frontmatter:

When creating files, include temperature in frontmatter:

---
date created: 2026-01-17
temperature: inbox | working | learnings | reference | archive
tags: []
---

This enables future automation (scripts that find stale inbox items, etc.).

See Also: docs/CONCEPTS.md → “Context Temperature Gradient”

4. Command-Based (Explicit)

Commands require explicit /slash invocation but are discoverable.

How it works:

Command files in .claude/commands/
Invoked with /command-name
Can accept arguments
Not proactive, but easily accessible

Command file format:

---
allowed-tools: Read, Write, Glob, Grep
argument-hint: "[optional arguments description]"
---

# Command prompt/instructions here

[What the command should do when invoked]

Example:

---
allowed-tools: Read, Write, Glob, AskUserQuestion
argument-hint: "[effort-level: minimal|standard|comprehensive]"
---

# Initialize Workspace

When invoked, analyze the current workspace and offer to scaffold it for AI-assisted work.

1. Check if CLAUDE.md exists
2. If not, ask about effort level
3. Create appropriate structure

When to use:

Actions users should explicitly trigger
Discoverable workflows (shows in command list)
Tasks with argument variations
Entry points to complex workflows

Choosing the Right Trigger

I want to…	Use
Load knowledge when topic relevant	Description (Skill YAML)
Offer help at certain conditions	Description (Agent)
Prevent/warn about actions	Hook
Let user explicitly invoke	Command

Decision Flow

Should this trigger automatically?
│
├─ NO → Command (explicit /slash)
│
└─ YES → What triggers it?
         │
         ├─ Topic/context relevant → Skill (YAML description)
         │
         ├─ Condition in workflow → Agent (description-based)
         │
         └─ Specific event (bash/file) → Hook

Combining Trigger Types

Components can use multiple trigger mechanisms:

Skill + Agent Combo

Skill provides knowledge (description-triggered)
Agent uses skill for actions (description-triggered)

User asks about testing patterns
  → pytest-skill loads (description relevant)
  → workflow-improver notices pattern (checkpoint)
  → Offers to create test helper agent

Command + Hook Combo

Command provides explicit invocation
Hook provides automatic safety

/deploy command exists for explicit deploys
Hook warns on any direct production file changes
Both protect production, different mechanisms

Anti-Patterns

Vague Skill Descriptions

# Bad - when does this load?
description: Helps with stuff

Vague Agent Descriptions

# Bad - when does this trigger?
description: Helps with stuff

Over-Blocking Hooks

# Bad - frustrating user experience
## Event: all
## Pattern: .*
## Action: block

Examples

Example 1: Domain Expertise Skill

---
name: kubernetes-expertise
description: Deep expertise in Kubernetes patterns and best practices. Use when user asks about k8s, kubectl, pods, deployments, services, ingress, helm, or cluster management.
---

# Kubernetes Expertise

## Purpose
Deep expertise in Kubernetes patterns and best practices.

---

## Content
[Kubernetes conventions, common patterns, troubleshooting tips]

Triggers when: Claude determines k8s expertise is relevant to conversation

Example 2: Proactive Review Agent

name: code-reviewer
description: Use PROACTIVELY when user completes writing a function or file. Reviews code for issues.
tools:
  - Read
  - Grep
skills:
  - code-review-conventions

Triggers when: Function/file writing completes

Example 3: Safety Hook

# No Secrets in Code

## Event
file

## Pattern
(password|secret|api_key)\s*=\s*['"][^'"]+['"]

## Action
warn

## Message
Potential secret detected in code. Consider using environment variables.

Triggers when: File write contains potential secrets

Testing Proactive Components

For Skills

Ask about a topic that matches the description
Verify skill knowledge appears in response
Adjust description if too broad/narrow

For Agents

Create the condition described
Check if agent is offered/invoked
Refine description for accuracy

For Hooks

Attempt the action that should trigger
Verify warning/block appears
Test edge cases

For Commands

Type /command-name
Verify it appears in command list
Test with arguments if applicable