[DOCS] Skills docs conflict on `name:` vs directory basename for invocation and argument hints

Documentation Type

Incorrect/outdated documentation

Documentation Location

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

Section/Topic

Write SKILL.md, Frontmatter reference, and Pass arguments to skills

Current Documentation

The skills page currently says:

Every skill needs a SKILL.md file with two parts: YAML frontmatter between --- markers that tells Claude when to use the skill, and markdown content with the instructions Claude follows when the skill runs. The directory name becomes the command you type, and the description helps Claude decide when to load the skill automatically.

Later in the same page, the frontmatter table says:

name | Display name for the skill. If omitted, uses the directory name. Lowercase letters, numbers, and hyphens only (max 64 characters). argument-hint | Hint shown during autocomplete to indicate expected arguments. Example: [issue-number] or [filename] [format].

Related docs currently say:

To enable only specific Skills, pass their names. Names match the name field in SKILL.md or the Skill's directory name. Use plugin:skill for plugin-provided Skills.

And the plugin reference says:

When a skill path points to a directory that contains a SKILL.md directly, for example "skills": ["./"] pointing to the plugin root, the frontmatter name field in SKILL.md determines the skill's invocation name. This gives a stable name regardless of the install directory. If name is not set in the frontmatter, the directory basename is used as a fallback.

What's Wrong or Missing?

Claude Code v2.1.149 changelog says:

Fixed argument-hint and progressive arg suggestions not appearing after Tab-completing a skill whose frontmatter name: differs from its directory basename

A. The main Skills page still implies the directory basename is always the command name

The primary skills guide says "The directory name becomes the command you type," while the frontmatter table describes name only as a display field. That does not explain the supported case where a skill's frontmatter name: differs from its directory basename.

B. The docs do not define which name autocomplete and argument metadata follow

No current page explains whether Tab completion, argument-hint, and progressive argument suggestions should be keyed to the frontmatter name, the directory basename, or both. Users cannot tell whether a renamed skill is supported or whether missing hints mean their skill is misconfigured.

C. Related pages use inconsistent naming rules

The main skills page, Agent SDK skills page, and plugin reference describe different name-resolution behavior. The docs need one authoritative rule for skill identity and invocation when name: is present.

Suggested Improvement

Update the skills documentation to define one canonical naming rule for skills when name: differs from the directory basename.

Add a short example such as a skill stored in .claude/skills/release-helper/SKILL.md with:

name: release
argument-hint: [version] [channel]

Then state explicitly:

• which slash command users should invoke
• which name appears in autocomplete after Tab completion
• which name argument-hint and progressive argument suggestions attach to
• which name SDK callers should pass in skills: [...]

Align https://code.claude.com/docs/en/skills, https://code.claude.com/docs/en/agent-sdk/skills, and https://code.claude.com/docs/en/plugins-reference to use the same rule and terminology.

Impact

Medium - Makes feature difficult to understand

Additional Context

Affected Pages:

| Page | Line(s) | Context |
|------|---------|---------|
| https://code.claude.com/docs/en/skills | 59, 209-212 | Main skill naming rule plus name and argument-hint frontmatter fields |
| https://code.claude.com/docs/en/agent-sdk/skills | 77 | Says skill names match the name field or directory name |
| https://code.claude.com/docs/en/plugins-reference | 555-557 | Says frontmatter name can determine invocation name, with basename as fallback |
| https://code.claude.com/docs/en/changelog | 29 | v2.1.149 confirms renamed-skill Tab completion should still show argument metadata |

Total scope: 4 pages affected

Version: behavior clarified by changelog entry in v2.1.149