[DOCS] Skills docs missing `paths` frontmatter YAML-list glob syntax

Documentation Type

Missing documentation (feature not documented)

Documentation Location

https://code.claude.com/docs/en/skills#frontmatter-reference

Section/Topic

Frontmatter reference for SKILL.md YAML fields

Current Documentation

The skills page currently says:

Skills are configured through YAML frontmatter at the top of SKILL.md and the markdown content that follows. All fields are optional. Only description is recommended so Claude knows when to use the skill. | name | No | Display name for the skill. If omitted, uses the directory name. Lowercase letters, numbers, and hyphens only (max 64 characters). | | description | Recommended | What the skill does and when to use it. Claude uses this to decide when to apply the skill. If omitted, uses the first paragraph of markdown content. | | argument-hint | No | Hint shown during autocomplete to indicate expected arguments. Example: [issue-number] or [filename] [format]. | | disable-model-invocation | No | Set to true to prevent Claude from automatically loading this skill. Use for workflows you want to trigger manually with /name. Default: false. | | user-invocable | No | Set to false to hide from the / menu. Use for background knowledge users shouldn't invoke directly. Default: true. | | allowed-tools | No | Tools Claude can use without asking permission when this skill is active. | | model | No | Model to use when this skill is active. | | effort | No | Effort level when this skill is active. Overrides the session effort level. Default: inherits from session. Options: low, medium, high, max (Opus 4.6 only). | | context | No | Set to fork to run in a forked subagent context. | | agent | No | Which subagent type to use when context: fork is set. | | hooks | No | Hooks scoped to this skill's lifecycle. See Hooks in skills and agents for configuration format. | | shell | No | Shell to use for ` !command blocks in this skill. Accepts bash (default) or powershell. Setting powershell runs inline shell commands via PowerShell on Windows. Requires CLAUDE_CODE_USE_POWERSHELL_TOOL=1`. |

The rules docs already show list-based paths syntax:

Rules can be scoped to specific files using YAML frontmatter with the paths field. These conditional rules only apply when Claude is working with files matching the specified patterns. --- paths: - "src/api/**/.ts" --- You can specify multiple patterns and use brace expansion to match multiple extensions in one pattern: --- paths: - "src/*/.{ts,tsx}" - "lib/*/.ts" - "tests/*/*.test.ts" ---

What's Wrong or Missing?

Changelog v2.1.84 says:

Rules and skills paths: frontmatter now accepts a YAML list of globs

However, the current docs only show this syntax for rules. The skills documentation still omits the paths frontmatter field entirely, so users cannot discover either:

1. that a skill can be scoped to matching file globs
2. that skill paths: can now be written as a YAML list of globs

Because the frontmatter reference ends at shell, a reader following the skills docs has no documented example of path-scoped skills in v2.1.84.

Suggested Improvement

Add paths to the frontmatter tables on both the skills and slash-commands pages, and include a short example using the new YAML-list syntax.

Suggested table row:

| paths | No | Limit automatic skill loading to files matching one or more glob patterns. Accepts a single glob or a YAML list of globs. |

Suggested example:

---
name: api-conventions
description: API design patterns for this codebase
paths:
- "src/api/**/*.ts"
- "lib/**/*.ts"
---

Add one sentence explaining that the skill only auto-loads when Claude is working with matching files, and consider cross-linking to the rules docs for the shared glob semantics.

Impact

Medium - Makes feature difficult to understand

Additional Context

Affected Pages:

| Page | Line(s) | Context |
|------|---------|---------|
| https://code.claude.com/docs/en/skills | 189-202 | Frontmatter reference table lists supported SKILL.md fields but omits paths |
| https://code.claude.com/docs/en/slash-commands | 189-202 | Mirrored skill frontmatter reference omits paths there as well |

Total scope: 2 pages affected

Cross-reference:

| Page | Context |
|------|---------|
| https://code.claude.com/docs/en/memory | Rules docs already show paths: as a YAML list of globs, including multiple-pattern examples |

Source: Changelog v2.1.84

Exact changelog entry:

Rules and skills paths: frontmatter now accepts a YAML list of globs