Skip to content

SKILL.md hook event keys are lowercase and never register in Claude Code #81

Description

All 8 SKILL.md frontmatters wire their hooks with lowercase event keys, but Claude Code's hook event names are case-sensitive (PreToolUse, Stop). As shipped, none of these hooks register — including the path guard that the README advertises as a security control.

What ships

Every skill under plugins/agent365/skills/ carries this shape in its frontmatter:

hooks:
  preToolUse:
    - type: command
      command: node ${CLAUDE_PLUGIN_ROOT}/hooks/preToolUse/path-guard.js
      timeout: 5000
  stop:
    - type: command
      command: node ${CLAUDE_PLUGIN_ROOT}/hooks/stop/validate-<skill>.js
      timeout: 30000

Evidence that the keys do not register

  • A string census of the Claude Code 2.1.241 binary (Windows) finds 152 occurrences of PreToolUse and zero occurrences of preToolUse — the host only knows the capitalized event names.
  • The hooks documentation's troubleshooting section names exactly this error class: "Verify the event name is correct (case-sensitive): PostToolUse, not postToolUse."
  • claude plugin validate passes on this plugin, so nothing flags the frontmatter keys — the failure is silent.
  • The one hook that demonstrably fires is the plugin manifest's SessionStart (plugins/agent365/.claude-plugin/plugin.json uses the correct casing "SessionStart", running scripts/check-version.js every session). That asymmetry — manifest hook works, frontmatter hooks silent — matches the case-sensitivity explanation.

Impact

  • The path guard never runs. The README's "Safety & Security" section lists "Path guard hook" as a key safeguard: a preToolUse hook that blocks every Write and Edit call targeting a file outside the project directory or inside the plugin directory itself. None of that is active in the current shipping configuration.
  • The stop-time checks never run. The hooks/stop/validate-*.js scripts (build-output checks, configuration checks that gate the end of a session) never execute, so sessions finish without the checks these files exist to perform.

Affected files (current main)

plugins/agent365/skills/<skill>/SKILL.md preToolUse: line stop: line
make-a365-agent 19 23
a365-setup 19 23
make-ai-teammate 20 24
test-local 20 24
instrument-observability 21 25
purview-dlp-integration 22 26
a365-code-validator 24 28
add-workiq-tools 17 21

Suggested fix

Capitalize the event keys in all 8 frontmatters (PreToolUse:, Stop:) — or, if frontmatter-level hook wiring is not a supported registration path for skills in the host, move the path guard and the stop checks into the plugin manifest's hooks block, where SessionStart already lives and demonstrably fires.

Since the failure is silent and affects an advertised control, an automated check would help: assert in CI (or in whatever plugin validate covers) that frontmatter hook keys match the host's documented event names.

Related history

#62 reported hook schema errors in plugin.json under v1.0.1 (fixed by #72). The manifest side validates cleanly now, but the SKILL.md frontmatter keys still use the lowercase form that the host does not recognize.

Activity

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions