Skip to content
Merged
Show file tree
Hide file tree
Changes from 1 commit
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Prev Previous commit
Next Next commit
[CLI] Always install skills for Claude Code, deprecate --claude (#4967)
* [CLI] Always install skills for Claude Code, deprecate --claude

* show --claude as deprecated in help instead of hiding it

* remove test
  • Loading branch information
hanouticelina authored Sep 22, 2026
commit aa8742c947e4890dcdb59c4855c53536f4a7050c
4 changes: 1 addition & 3 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -102,10 +102,8 @@ The `huggingface_hub` library allows you to interact with the [Hugging Face Hub]
The `hf` CLI is designed for people and coding agents alike: the same commands adapt their output when run by an agent. If you use Claude Code, Codex, Cursor, or another coding agent, install the `hf` CLI Skill — a command reference generated from your installed CLI:

```bash
# for Codex, Cursor, OpenCode, Pi and other agents that load skills from `.agents/skills`
# works with Claude Code, Codex, Cursor, OpenCode, Pi and any agent that loads skills from `.agents/skills`
hf skills add
# includes the above + Claude Code
hf skills add --claude
```

Learn more in the [Hugging Face CLI for AI agents guide](https://huggingface.co/docs/hub/agents-cli) and the [announcement blog post](https://huggingface.co/blog/hf-cli-for-agents).
Expand Down
4 changes: 1 addition & 3 deletions docs/source/en/guides/cli.md
Original file line number Diff line number Diff line change
Expand Up @@ -13,10 +13,8 @@ The `huggingface_hub` Python package comes with a built-in CLI called `hf`. This
> [!TIP]
> Using the `hf` CLI with AI agents? Install the Skill and check out the [Hugging Face CLI for AI Agents](https://huggingface.co/docs/hub/agents-cli) guide.
> ```bash
> # for Codex, Cursor, OpenCode, Pi and other agents that load skills from `.agents/skills`
> # works with Claude Code, Codex, Cursor, OpenCode, Pi and any agent that loads skills from `.agents/skills`
> hf skills add
> # includes the above + Claude Code
> hf skills add --claude
> ```
> The standalone installer installs it for you (see below), and `hf update` refreshes it.

Expand Down
13 changes: 6 additions & 7 deletions docs/source/en/package_reference/cli.md
Original file line number Diff line number Diff line change
Expand Up @@ -4298,8 +4298,8 @@ Install a Hugging Face skill for an AI assistant.
The default `hf-cli` skill is generated locally from the installed CLI version;
other skills are downloaded from the Hugging Face marketplace.
Default location is in the current directory (.agents/skills) or user-level (~/.agents/skills).
If `--claude` is specified, the skill is also symlinked into Claude's legacy skills directory
(`.claude/skills` or `~/.claude/skills`, honoring `CLAUDE_CONFIG_DIR` when set).
The skill is also symlinked into Claude Code's skills directory (`.claude/skills` or `~/.claude/skills`,
honoring `CLAUDE_CONFIG_DIR` when set), unless `--dest` is used.

**Usage**:

Expand All @@ -4313,7 +4313,7 @@ $ hf skills add [OPTIONS] [NAME]

**Options**:

* `--claude`: Install for Claude.
* `--claude`: (Deprecated) No longer needed: skills are always installed for Claude Code too.
* `-g, --global`: Install globally (user-level) instead of in the current project directory.
* `--dest PATH`: Install into a custom destination (path to skills directory).
* `--force`: Overwrite existing skills in the destination.
Expand All @@ -4323,8 +4323,7 @@ Examples
$ hf skills add
$ hf skills add huggingface-gradio --dest=~/my-skills
$ hf skills add --global
$ hf skills add --claude
$ hf skills add huggingface-gradio --claude --global
$ hf skills add huggingface-gradio --global

Learn more
Use `hf <command> --help` for more information about a command.
Expand Down Expand Up @@ -4385,7 +4384,7 @@ $ hf skills update [OPTIONS] [NAME]

**Options**:

* `--claude`: Update skills installed for Claude.
* `--claude`: (Deprecated) No longer needed: skills are always installed for Claude Code too.
* `-g, --global`: Use global skills directories instead of the current project.
* `--dest PATH`: Update skills in a custom skills directory.
* `--help`: Show this message and exit.
Expand All @@ -4394,7 +4393,7 @@ Examples
$ hf skills update
$ hf skills update hf-cli
$ hf skills update huggingface-gradio --dest=~/my-skills
$ hf skills update --claude
$ hf skills update -g

Learn more
Use `hf <command> --help` for more information about a command.
Expand Down
4 changes: 1 addition & 3 deletions docs/source/en/quick-start.md
Original file line number Diff line number Diff line change
Expand Up @@ -24,10 +24,8 @@ For more details, check out the [installation](installation) guide.
> The `huggingface_hub` also ships with a [`hf` CLI](./guides/cli) that lets you interact with the Hub directly from the terminal.
> If you're using AI agents (Claude Code, Codex, Cursor, ...), install the Skill to let your agent use the CLI:
> ```bash
> # for Codex, Cursor, OpenCode, Pi and other agents that load skills from `.agents/skills`
> # works with Claude Code, Codex, Cursor, OpenCode, Pi and any agent that loads skills from `.agents/skills`
> hf skills add
> # includes the above + Claude Code
> hf skills add --claude
> ```
> Check out the [Hugging Face CLI for AI Agents](https://huggingface.co/docs/hub/agents-cli) guide for more details.

Expand Down
8 changes: 4 additions & 4 deletions src/huggingface_hub/cli/_skills.py
Original file line number Diff line number Diff line change
Expand Up @@ -356,21 +356,21 @@ def _check_skill_update() -> None:
if any(tag in __version__ for tag in ["rc", "dev"]):
return
out.hint(
f"The `{DEFAULT_SKILL_ID}` skill is not installed. Run `hf skills add -g --claude`"
f"The `{DEFAULT_SKILL_ID}` skill is not installed. Run `hf skills add -g`"
" to teach your AI agents how to use the `hf` CLI."
)
return

# Suggest the command matching where the outdated skill is installed (global takes precedence).
if any(_is_skill_outdated(skill_dir) for skill_dir in global_dirs):
scope = "-g --claude"
scope = " -g"
elif any(_is_skill_outdated(skill_dir) for skill_dir in local_dirs):
scope = "--claude"
scope = ""
else:
return
out.hint(
f"The installed `{DEFAULT_SKILL_ID}` skill was generated by another `hf` version."
f" Run `hf skills update {DEFAULT_SKILL_ID} {scope}` to refresh it."
f" Run `hf skills update {DEFAULT_SKILL_ID}{scope}` to refresh it."
)


Expand Down
62 changes: 36 additions & 26 deletions src/huggingface_hub/cli/skills.py
Original file line number Diff line number Diff line change
Expand Up @@ -330,6 +330,12 @@ def _install_to(skills_dir: Path, skill_name: str, force: bool) -> Path:
raise CLIError(f"{exc}\nRe-run with --force to overwrite.") from exc


_CLAUDE_FLAG_DEPRECATED = (
"`--claude` is deprecated and will be removed in a future release:"
" skills are always installed for Claude Code too."
)


def _create_symlink(agent_skills_dir: Path, skill_name: str, central_skill_path: Path, force: bool) -> Path:
"""Create a relative symlink from agent directory to the central skill location."""
agent_skills_dir = agent_skills_dir.expanduser().resolve()
Expand All @@ -347,20 +353,16 @@ def _create_symlink(agent_skills_dir: Path, skill_name: str, central_skill_path:
return link_path


def _resolve_update_roots(
*,
claude: bool,
global_: bool,
dest: Path | None,
) -> list[Path]:
def _resolve_update_roots(*, global_: bool, dest: Path | None) -> list[Path]:
if dest is not None:
if claude or global_:
raise CLIError("--dest cannot be combined with --claude or --global.")
if global_:
raise CLIError("--dest cannot be combined with --global.")
return [dest.expanduser().resolve()]

roots: list[Path] = [constants.AGENTS_SKILLS_GLOBAL_PATH if global_ else constants.AGENTS_SKILLS_LOCAL_PATH]
if claude:
roots.append(constants.CLAUDE_SKILLS_GLOBAL_PATH if global_ else constants.CLAUDE_SKILLS_LOCAL_PATH)
if global_:
roots = [constants.AGENTS_SKILLS_GLOBAL_PATH, constants.CLAUDE_SKILLS_GLOBAL_PATH]
else:
roots = [constants.AGENTS_SKILLS_LOCAL_PATH, constants.CLAUDE_SKILLS_LOCAL_PATH]
return [root.expanduser().resolve() for root in roots]


Expand Down Expand Up @@ -419,16 +421,18 @@ def skills_list(
"hf skills add",
"hf skills add huggingface-gradio --dest=~/my-skills",
"hf skills add --global",
"hf skills add --claude",
"hf skills add huggingface-gradio --claude --global",
"hf skills add huggingface-gradio --global",
],
)
def skills_add(
name: Annotated[
str,
Argument(help="Marketplace skill name.", show_default=False),
] = DEFAULT_SKILL_ID,
claude: Annotated[bool, Option("--claude", help="Install for Claude.")] = False,
claude: Annotated[
bool,
Option("--claude", help="(Deprecated) No longer needed: skills are always installed for Claude Code too."),
] = False,
global_: Annotated[
bool,
Option(
Expand Down Expand Up @@ -456,25 +460,26 @@ def skills_add(
The default `hf-cli` skill is generated locally from the installed CLI version;
other skills are downloaded from the Hugging Face marketplace.
Default location is in the current directory (.agents/skills) or user-level (~/.agents/skills).
If `--claude` is specified, the skill is also symlinked into Claude's legacy skills directory
(`.claude/skills` or `~/.claude/skills`, honoring `CLAUDE_CONFIG_DIR` when set).
The skill is also symlinked into Claude Code's skills directory (`.claude/skills` or `~/.claude/skills`,
honoring `CLAUDE_CONFIG_DIR` when set), unless `--dest` is used.
"""
if claude:
out.warning(_CLAUDE_FLAG_DEPRECATED)
if dest is not None:
if claude or global_:
raise CLIError("--dest cannot be combined with --claude or --global.")
if global_:
raise CLIError("--dest cannot be combined with --global.")
skill_dest = _install_to(dest, name, force)
print(f"Installed '{name}' to {skill_dest}")
return

# Install to central location
# Install to central location, then expose it to Claude Code which only reads `.claude/skills`
central_path = constants.AGENTS_SKILLS_GLOBAL_PATH if global_ else constants.AGENTS_SKILLS_LOCAL_PATH
central_skill_path = _install_to(central_path, name, force)
print(f"Installed '{name}' to central location: {central_skill_path}")

if claude:
agent_target = constants.CLAUDE_SKILLS_GLOBAL_PATH if global_ else constants.CLAUDE_SKILLS_LOCAL_PATH
link_path = _create_symlink(agent_target, name, central_skill_path, force)
print(f"Created symlink: {link_path}" if link_path.is_symlink() else f"Copied '{name}' to {link_path}")
claude_path = constants.CLAUDE_SKILLS_GLOBAL_PATH if global_ else constants.CLAUDE_SKILLS_LOCAL_PATH
link_path = _create_symlink(claude_path, name, central_skill_path, force)
print(f"Created symlink: {link_path}" if link_path.is_symlink() else f"Copied '{name}' to {link_path}")


@skills_cli.command(
Expand All @@ -483,15 +488,18 @@ def skills_add(
"hf skills update",
"hf skills update hf-cli",
"hf skills update huggingface-gradio --dest=~/my-skills",
"hf skills update --claude",
"hf skills update -g",
],
)
def skills_update(
name: Annotated[
str | None,
Argument(help="Optional installed skill name to update.", show_default=False),
] = None,
claude: Annotated[bool, Option("--claude", help="Update skills installed for Claude.")] = False,
claude: Annotated[
bool,
Option("--claude", help="(Deprecated) No longer needed: skills are always installed for Claude Code too."),
] = False,
global_: Annotated[
bool,
Option(
Expand All @@ -508,7 +516,9 @@ def skills_update(
] = None,
) -> None:
"""Update installed Hugging Face marketplace skills."""
roots = _resolve_update_roots(claude=claude, global_=global_, dest=dest)
if claude:
out.warning(_CLAUDE_FLAG_DEPRECATED)
roots = _resolve_update_roots(global_=global_, dest=dest)

results = _skills.update_skills(roots, selector=name, hf_cli_content=build_skill_md())
if not results:
Expand Down
4 changes: 2 additions & 2 deletions src/huggingface_hub/cli/system.py
Original file line number Diff line number Diff line change
Expand Up @@ -71,14 +71,14 @@ def update() -> None:
raise click.exceptions.Exit(code=returncode)

if not skill_installed:
out.hint("Run `hf skills add -g --claude` to teach your AI agents how to use the `hf` CLI.")
out.hint("Run `hf skills add -g` to teach your AI agents how to use the `hf` CLI.")
return

# Refresh the globally installed skill so agents see the new command surface. Runs in a
# subprocess: the skill is generated from the CLI code, which has just been replaced on disk
# while this process still runs the previous version.
out.text(f"Updating the `{DEFAULT_SKILL_ID}` skill...")
subprocess.call([*_hf_argv(), "skills", "update", DEFAULT_SKILL_ID, "-g", "--claude"])
subprocess.call([*_hf_argv(), "skills", "update", DEFAULT_SKILL_ID, "-g"])


def _hf_argv() -> list[str]:
Expand Down
4 changes: 2 additions & 2 deletions tests/test_cli.py
Original file line number Diff line number Diff line change
Expand Up @@ -5380,14 +5380,14 @@ def _write_global_skill(self, tmp_path: Path, content: str) -> Path:
def test_hints_to_add_when_not_installed(self, capsys: pytest.CaptureFixture) -> None:
with patch.object(_skills, "__version__", "1.0.0"):
_skills.check_skill_update()
assert "hf skills add -g --claude" in capsys.readouterr().err
assert "hf skills add -g" in capsys.readouterr().err

def test_hints_to_update_when_generated_by_another_version(
self, tmp_path: Path, capsys: pytest.CaptureFixture
) -> None:
self._write_global_skill(tmp_path, "Generated with `huggingface_hub v0.0.1`.")
_skills.check_skill_update()
assert "hf skills update hf-cli -g --claude" in capsys.readouterr().err
assert "hf skills update hf-cli -g" in capsys.readouterr().err

def test_silent_when_up_to_date_and_throttled_afterwards(
self, tmp_path: Path, capsys: pytest.CaptureFixture
Expand Down
4 changes: 2 additions & 2 deletions utils/installers/install.ps1
Original file line number Diff line number Diff line change
Expand Up @@ -349,9 +349,9 @@ function Install-Skill {

Write-Log "Installing the hf-cli skill for AI agents..."
$hfExecutable = Join-Path $BIN_DIR "hf.exe"
& $hfExecutable skills add hf-cli --global --claude --force
& $hfExecutable skills add hf-cli --global --force
if (-not $?) {
Write-Log "Failed to install the hf-cli skill. Install it later with: hf skills add -g --claude" "WARNING"
Write-Log "Failed to install the hf-cli skill. Install it later with: hf skills add -g" "WARNING"
return
}
Write-Log "The hf-cli skill was installed automatically so AI agents know how to use the hf CLI."
Expand Down
4 changes: 2 additions & 2 deletions utils/installers/install.sh
Original file line number Diff line number Diff line change
Expand Up @@ -404,8 +404,8 @@ install_skill() {
fi

log_info "Installing the hf-cli skill for AI agents..."
if ! "$BIN_DIR/hf" skills add hf-cli --global --claude --force; then
log_warning "Failed to install the hf-cli skill. Install it later with: hf skills add -g --claude"
if ! "$BIN_DIR/hf" skills add hf-cli --global --force; then
log_warning "Failed to install the hf-cli skill. Install it later with: hf skills add -g"
return
fi
log_info "The hf-cli skill was installed automatically so AI agents know how to use the hf CLI."
Expand Down
Loading