[DOCS] Incorrect usage of `$FILE` shell variable in Plugin Migration Guide hook example

Documentation Type

Unclear/confusing documentation

Documentation Location

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

Section/Topic

The section "Convert existing configurations to plugins", specifically the "Migrate hooks" step.

Current Documentation

The example hooks.json code block currently shows:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [{ "type": "command", "command": "npm run lint:fix $FILE" }]
      }
    ]
  }
}

What's Wrong or Missing?

The example uses the shell variable $FILE in the command string ("npm run lint:fix $FILE").

However, according to the Hooks Reference, Claude Code hooks do not automatically inject a $FILE environment variable into the shell execution environment. Instead, hooks receive context (including file paths) as a JSON object via stdin.

Using this example code as written will likely result in the command executing npm run lint:fix with an empty argument (or failing), rather than linting the specific file that was just edited. This misleads users into thinking simple shell variables are available for file paths without parsing stdin.

Suggested Improvement

The example should be updated to reflect how hooks actually retrieve file paths (by parsing stdin).

Option A (Preferred - Script Reference):
Update the example to point to a script, which is best practice for plugins anyway.

"hooks": [{ "type": "command", "command": "${CLAUDE_PLUGIN_ROOT}/scripts/lint-fix.sh" }]

Option B (Inline fix):
If keeping it inline is necessary, show how to pipe the input properly (though this is messy in JSON strings):

"hooks": [{ "type": "command", "command": "jq -r '.tool_input.file_path' | xargs npm run lint:fix" }]

Impact

High - Prevents users from using a feature

Additional Context

• Hooks Reference: docs/en/hooks.md states: "Hooks receive JSON data via stdin containing session information and event-specific data."
• Hooks Guide: docs/en/hooks-guide.md explicitly uses jq to extract file paths in its examples: "command": "jq -r '.tool_input.file_path' | { read file_path; ... }"