[DOCS] Inconsistency between Agent Skill hook examples and the "Available string substitutions" reference table

Documentation Type

Missing documentation (feature not documented)

Documentation Location

https://code.claude.com/docs/en/skills

Section/Topic

Sections: "Available string substitutions" and "Define hooks for Skills"

Current Documentation

In the "Define hooks for Skills" section, the example code provided is:

---
name: secure-operations
description: Perform operations with additional security checks
hooks:
  PreToolUse:
    - matcher: "Bash"
      hooks:
        - type: command
          command: "./scripts/security-check.sh $TOOL_INPUT"
          once: true
---

However, the "Available string substitutions" table only lists:

• $ARGUMENTS
• ${CLAUDE_SESSION_ID}

What's Wrong or Missing?

There is an executability and consistency conflict. The documentation provides a code example that uses $TOOL_INPUT as a shell variable/substitution, but it does not define $TOOL_INPUT in the reference table of supported variables for Skills.

A user attempting to implement this example cannot be certain if $TOOL_INPUT is a valid, supported substitution provided by the Agent Skill runtime or if the example is using an invalid placeholder.

Suggested Improvement

• If $TOOL_INPUT is supported: Add it to the "Available string substitutions" table on the https://code.claude.com/docs/en/skills page with a description of what data it contains (e.g., "The JSON-stringified input parameters for the matched tool").
• If $TOOL_INPUT is NOT supported: Update the example in the "Define hooks for Skills" section to reflect the actual mechanism for accessing tool data (such as reading the JSON from stdin, as described in the general https://code.claude.com/docs/en/hooks documentation).

Impact

High - Prevents users from using a feature

Additional Context

In the general Hooks documentation (https://code.claude.com/docs/en/hooks), it is noted that hooks receive JSON data via stdin. If Skills-scoped hooks follow this same logic, using $TOOL_INPUT as a command-line argument in the Skill YAML might be a typo in the documentation, or it might be a specialized convenience feature for Skills that needs to be documented in the reference table.