[DOCS] Inconsistent documentation for `allowed-tools` syntax (YAML List vs. CLI string)

Documentation Type

Missing documentation (feature not documented)

Documentation Location

• https://code.claude.com/docs/en/skills#restrict-tool-access-with-allowed-tools - https://code.claude.com/docs/en/cli-reference - https://code.claude.com/docs/en/settings#permission-rule-syntax

Section/Topic

• CLI Reference (flags) - Permission rule syntax (Settings)

Current Documentation

The Skills documentation states:

"You can specify tools as a comma-separated string or a YAML list: ... allowed-tools: [Read, Grep, Glob]"

However, the CLI Reference for --allowedTools only shows:

--allowedTools "Bash(git log:*)" "Bash(git diff:*)" "Read"

The Settings page for permissions.allow only shows examples using strings within JSON:

{
  "permissions": {
    "allow": [
      "Bash(npm run lint)",
      "Bash(npm run test:*)",
      "Read(~/.zshrc)"
    ]
  }
}

What's Wrong or Missing?

According to the 2.1.0 changelog, support was added for YAML-style lists in frontmatter for cleaner declarations. While the documentation for Skills was updated to show this, the general Permission rule syntax section in the Settings documentation and the CLI Reference still imply that tools are primarily handled as space-separated or comma-separated strings.

There is no explicit mention that the allowed-tools field in settings.json or Skill frontmatter can consistently use native JSON/YAML arrays instead of a single formatted string. This creates a "nitpick" inconsistency where a user might think the list syntax is only for Skills and not applicable to general project permissions.

Suggested Improvement

• Update the CLI Reference to clarify that while the CLI flag accepts space-separated strings, the equivalent configuration in settings.json or Skill frontmatter supports native array/list formats.
• Update the Permission rule syntax section in docs/en/settings.md to include an example of an array-based tool list.

Suggested text for settings.md:

"When defining permissions in configuration files (settings.json or Skill frontmatter), you can provide rules as a single comma-separated string or as a native YAML/JSON array for better readability."

Example:

# In .claude/skills/my-skill/SKILL.md
allowed-tools:
  - Read
  - Bash(ls)
  - Grep

Impact

High - Prevents users from using a feature

Additional Context

• Changelog 2.1.0 reference: "Added support for YAML-style lists in frontmatter allowed-tools field for cleaner skill declarations."
• Ensuring this is documented in the primary "Settings" and "CLI Reference" pages will help users who are looking for global configuration options rather than just Skill-specific ones.