[DOCS] `--bare` help text "Skills still resolve via /skill-name" is ambiguous about filesystem-discovered skills

Documentation Type

Unclear/confusing documentation

Documentation Location

claude --help (CLI output, v2.1.220)

Section/Topic

--bare flag description in claude --help — the sentence "Skills still resolve via /skill-name"

Current Documentation

claude --help currently says, within the --bare description:

  --bare                                Minimal mode: skip hooks, LSP, plugin
                                        sync, attribution, auto-memory,
                                        background prefetches, keychain reads,
                                        and CLAUDE.md auto-discovery. Sets
                                        CLAUDE_CODE_SIMPLE=1. Anthropic auth is
                                        strictly ANTHROPIC_API_KEY or
                                        apiKeyHelper via --settings (OAuth and
                                        keychain are never read). 3P providers
                                        (Bedrock/Vertex/Foundry) use their own
                                        credentials. Skills still resolve via
                                        /skill-name. Explicitly provide context
                                        via: --system-prompt[-file],
                                        --append-system-prompt[-file], --add-dir
                                        (CLAUDE.md dirs), --mcp-config,
                                        --settings, --agents, --plugin-dir.

What's Wrong or Missing?

The sentence "Skills still resolve via /skill-name" reads as a reassurance that skills keep working in bare mode. In practice it is true only for skills supplied explicitly on the command line — filesystem-discovered skills do not resolve at all.

Testing both paths makes the distinction clear. With a skill at .claude/skills/wombat/SKILL.md in the working directory:

$ claude --bare -p "/wombat"
Unknown command: /wombat

With the same skill supplied explicitly through a plugin directory:

$ claude --bare --plugin-dir ./wombat-plugin -p "/wombat"
Not logged in · Please run /login

The second command reaches authentication, which means the skill resolved; only the first fails at command resolution. So the sentence is defensible, but its scope is not stated, and the natural reading in context — a list of things bare mode skips, followed by "Skills still resolve" — is the opposite of the actual behavior for skills on disk.

The headless documentation is unambiguous on this point and does not contradict the behavior. https://code.claude.com/docs/en/headless says:

Add --bare to reduce startup time by skipping auto-discovery of hooks, skills, plugins, MCP servers, auto memory, and CLAUDE.md.

So the website says skills are skipped, and --help says skills still resolve. Both describe real behavior, but the two read as contradictory unless you already know that "skills" means different things in each sentence.

This matters more than it otherwise would because of the note on the same docs page:

--bare is the recommended mode for scripted and SDK calls, and will become the default for -p in a future release.

When --bare becomes the default for -p, scripts that rely on filesystem skill discovery will stop finding those skills. A reader who took "Skills still resolve via /skill-name" at face value would not anticipate that.

Suggested Improvement

Qualify the sentence so the scope is explicit. For example:

Filesystem skill discovery is skipped; skills supplied via --plugin-dir
still resolve via /skill-name.

That keeps the useful information — explicitly-provided skills are invocable by name — while removing the implication that skills in .claude/skills/ or ~/.claude/skills/ continue to work.

It would also help to name the recommended migration path in one place: package skills as a plugin and pass --plugin-dir, which is the form that survives --bare becoming the default for -p.

Impact

Medium - Makes feature difficult to understand

Additional Context

Verified on macOS with Claude Code 2.1.220; the same behavior and the same --help string are present in 2.1.181.

The Unknown command: /wombat failure occurs before authentication, so it is a genuine skill-resolution failure rather than an artifact of bare mode's stricter credential handling. That is what the contrast between the two commands above establishes: identical auth setup, different resolution outcome.