Feature request: add a SkillInvocation hook event

Open 💬 0 comments Opened Aug 21, 2026 by mpuhacz

Use case. Skill usage is part of the audit trail that hook integrations build for tool calls and prompts today. Codex hooks ([features] hooks = true) expose tool calls, prompts, and session lifecycle events to external handlers. Skill invocations are the one action that hooks cannot see. Explicit $skill activation injects the skill text into the prompt and does not create a tool call. As a result, PreToolUse does not fire. Implicit activation is visible only as a generic shell read of SKILL.md.

What Codex has today. Codex detects skill invocations on both paths, in codex-rs/core/src/skills.rs:

  • Explicit path: emit_explicit_skill_invocations builds a SkillInvocation record for each injected skill. session/turn.rs calls it directly after load_skill_prompts.
  • Implicit path: maybe_emit_implicit_skill_invocation uses detect_implicit_skill_invocation and removes duplicate invocations in each turn.
  • Both paths send each invocation to three consumers: the codex.skill.injected OTEL counter, analytics_events_client.track_skill_invocations, and the extension on_skill_invocation contributors.

External hook handlers are the only consumer that cannot receive this data.

Proposed approach. Add HookEventName::SkillInvocation as a notification event. The event does not block and returns no decision. Example payload:

{
  "hook_event_name": "SkillInvocation",
  "skill_name": "...",
  "skill_path": "/.../SKILL.md",
  "scope": "user|repo|system|admin",
  "invocation_type": "explicit|implicit",
  "turn_id": "...",
  "session_id": "..."
}

The two emit sites in skills.rs can send the event next to the analytics call. The detection, the duplicate removal, and the payload data exist there today. The event implementation can mirror hooks/src/events/user_prompt_submit.rs: matcher-less select_handlers, serialize, dispatch. The plumbing can go through core/src/hook_runtime.rs like the other events.

I can test the change against a nightly build.

View original on GitHub ↗