Summary

Add hook events that fire when the agent reads and completes using a skill, enabling automated skill quality monitoring and optimization workflows.

Motivation

I'm building a skill optimizer that automatically reviews skill executions and suggests improvements. Currently, I have to scan session transcripts looking for SKILL.md file reads to detect skill usage — this is inefficient and misses the completion boundary.

With proper skill lifecycle hooks, I could:

1. Know exactly when a skill is invoked
2. Know when the agent has finished using that skill's guidance
3. Trigger quality review/optimization workflows automatically
4. Track skill usage metrics accurately

Proposed Events

skill:read

Fires when agent reads a SKILL.md file (detected via read tool + path matching).

{
  type: "skill",
  action: "read",
  context: {
    skillName: string,      // e.g. "sonos", "github"
    skillPath: string,      // full path to SKILL.md
    sessionKey: string,
    timestamp: Date
  }
}

skill:complete

Fires when the agent completes a task that was guided by a skill. This is trickier — could be:

• Explicit signal from agent (e.g. thinking/tool call pattern)
• Heuristic: N turns after skill:read without re-reading
• Turn boundary after skill-related tool calls

{
  type: "skill",
  action: "complete",
  context: {
    skillName: string,
    skillPath: string,
    sessionKey: string,
    startTimestamp: Date,
    endTimestamp: Date,
    toolsUsed: string[],    // tools called while skill was active
    success: boolean        // if determinable
  }
}

Use Case

// hooks/skill-optimizer/handler.js
export default async function(event) {
  if (event.type !== 'skill') return;
  
  if (event.action === 'complete') {
    // Queue skill for optimization review
    await triggerSkillReview({
      skill: event.context.skillName,
      sessionKey: event.context.sessionKey,
      duration: event.context.endTimestamp - event.context.startTimestamp
    });
  }
}

Current Workaround

Daily cron job scans session transcripts for SKILL.md reads, then triggers reviews. This is:

• Delayed (not real-time)
• Resource-intensive (parsing all transcripts)
• Imprecise (can't detect completion boundary)

Related

• Feature Request: Real-time tool invocation hook events (tool:start, tool:end) #2538 (tool:start/tool:end hooks) — closed during triage but had working PR [WIP] feat: Add tool hooks bridge for external UI visibility #2908
• Hooks: Expose onAgentEvent to internal hooks for lifecycle event access #10634 (onAgentEvent lifecycle access)

Skill hooks would complement tool hooks — skills are higher-level workflows composed of multiple tool calls.

Environment

• OpenClaw version: 2026.2.1
• Use case: Automated skill quality optimization system