Skip to content

Commit 62b8e19

Browse files
Wauplinclaudehanouticelina
authored
[CLI] Install & refresh the hf-cli skill (installer, update, hints) (#4608)
* [CLI] Install and refresh the hf-cli skill from installer, update and hints - installer: opt-in `--include-skills` / `-IncludeSkills` runs `hf skills add hf-cli -g --claude` - `hf update`: refreshes the globally installed hf-cli skill (subprocess, new code on disk) - `hf <anything>`: suggests `hf skills add`/`hf skills update` at most once a day, never auto-installs Co-Authored-By: Claude Opus 5 (1M context) <[email protected]> * [CLI] Drop the removal disclaimer from the installer skill step Co-Authored-By: Claude Opus 5 (1M context) <[email protected]> * [CLI] Move skills directories to the global constants Co-Authored-By: Claude Opus 5 (1M context) <[email protected]> * [CI] Check the installers with --include-skills Co-Authored-By: Claude Opus 5 (1M context) <[email protected]> * [CLI] Clarify skill install/update wording in docs Co-Authored-By: Claude Opus 5 (1M context) <[email protected]> * Update docs/source/en/guides/cli.md * [CLI] Make the installer skill install opt-out (--exclude-skill) Co-Authored-By: Claude Opus 5 (1M context) <[email protected]> * [CLI] Drop the hf-cli skill from installer uninstall instructions Co-Authored-By: Claude Opus 5 (1M context) <[email protected]> * [CLI] Don't reinstall the hf-cli skill on `hf update` if opted out `hf update` re-runs the standalone installer, which now installs the skill by default. Check whether the skill is installed globally first and pass --exclude-skill / -ExcludeSkill when it isn't, so an opt-out is not silently undone. Also fixes flag passing for the PowerShell installer: `iwr ... | iex -Flag` cannot take parameters, use a scriptblock instead. Co-Authored-By: Claude Opus 5 (1M context) <[email protected]> * [CLI] Skip the daily skill hint on `hf update` `hf update` handles the `hf-cli` skill itself, so the startup hint was either redundant (same `hf skills add` suggestion) or contradictory (suggesting a manual update right before doing it). Co-Authored-By: Claude Opus 5 (1M context) <[email protected]> * [CLI] Address review: symlink fallback on Windows, skip skill hint on dev/rc - `hf skills add --claude` falls back to a copy when symlinks aren't available (Windows without Developer Mode / admin rights). `hf skills update` walks both roots, so the copy stays in sync. - The daily 'skill is not installed' hint is skipped on pre-release / dev versions, same rule as the PyPI update check. * [CLI] Drop the two extra skill tests added in the previous commit Keeps only the necessary change to `test_hints_to_add_when_not_installed`: it must pin `__version__` to a stable value, otherwise the dev version now short-circuits the hint. * Update src/huggingface_hub/cli/skills.py --------- Co-authored-by: Claude Opus 5 (1M context) <[email protected]> Co-authored-by: Celina Hanouti <[email protected]>
1 parent c292e47 commit 62b8e19

12 files changed

Lines changed: 352 additions & 34 deletions

File tree

‎.github/workflows/check-installers.yml‎

Lines changed: 27 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -32,6 +32,9 @@ jobs:
3232
INSTALL_DIR="$HF_TEST_ROOT/install"
3333
BIN_DIR="$HF_TEST_ROOT/bin"
3434
35+
# Skills are installed under `~`: point HOME at the test root to keep the run hermetic.
36+
export HOME="$HF_TEST_ROOT"
37+
3538
HF_HOME="$INSTALL_DIR" HF_CLI_BIN_DIR="$BIN_DIR" utils/installers/install.sh --no-modify-path
3639
3740
export PATH="$BIN_DIR:$PATH"
@@ -41,6 +44,18 @@ jobs:
4144
exit 1
4245
fi
4346
47+
# The hf-cli skill is installed by default, generated by the installed version
48+
SKILL_MD="$HOME/.agents/skills/hf-cli/SKILL.md"
49+
if [ ! -f "$SKILL_MD" ]; then
50+
echo "hf-cli skill not installed at $SKILL_MD" >&2
51+
exit 1
52+
fi
53+
HF_VERSION=$(hf version --format quiet)
54+
if ! grep -q "huggingface_hub v$HF_VERSION" "$SKILL_MD"; then
55+
echo "hf-cli skill not aligned with hf version $HF_VERSION" >&2
56+
exit 1
57+
fi
58+
4459
NO_COLOR=1 hf --help
4560
4661
rm -rf "$HF_TEST_ROOT"
@@ -62,6 +77,8 @@ jobs:
6277
6378
$env:HF_HOME = $installDir
6479
$env:HF_CLI_BIN_DIR = $binDir
80+
# Skills are installed under the user profile: point it at the test root to keep the run hermetic.
81+
$env:USERPROFILE = $hfTestRoot
6582
& "$PWD/utils/installers/install.ps1" -NoModifyPath
6683
6784
$env:PATH = "$binDir;$env:PATH"
@@ -77,6 +94,16 @@ jobs:
7794
throw 'incorrect hf version output'
7895
}
7996
97+
# The hf-cli skill is installed by default, generated by the installed version
98+
$skillMd = Join-Path $hfTestRoot '.agents\skills\hf-cli\SKILL.md'
99+
if (-not (Test-Path $skillMd)) {
100+
throw "hf-cli skill not installed at $skillMd"
101+
}
102+
$hfVersion = (& hf.exe version --format quiet).Trim()
103+
if (-not (Select-String -Path $skillMd -SimpleMatch "huggingface_hub v$hfVersion" -Quiet)) {
104+
throw "hf-cli skill not aligned with hf version $hfVersion"
105+
}
106+
80107
$env:NO_COLOR = '1'
81108
& hf.exe --help
82109
if ($LASTEXITCODE -ne 0) {

‎docs/source/en/guides/cli.md‎

Lines changed: 12 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -18,6 +18,7 @@ The `huggingface_hub` Python package comes with a built-in CLI called `hf`. This
1818
> # includes the above + Claude Code
1919
> hf skills add --claude
2020
> ```
21+
> The standalone installer installs it for you (see below), and `hf update` refreshes it.
2122
2223
## Getting started
2324
@@ -37,6 +38,16 @@ On Windows:
3738
>>> powershell -ExecutionPolicy ByPass -c "irm https://hf.co/cli/install.ps1 | iex"
3839
```
3940

41+
The installer also installs the [`hf-cli` skill](https://huggingface.co/docs/hub/agents-cli) globally, for Claude Code and any agent reading `~/.agents/skills`. Pass `--exclude-skill` to skip it:
42+
43+
```bash
44+
>>> curl -LsSf https://hf.co/cli/install.sh | bash -s -- --exclude-skill
45+
```
46+
47+
```powershell
48+
>>> powershell -ExecutionPolicy ByPass -c "& ([scriptblock]::Create((irm https://hf.co/cli/install.ps1))) -ExcludeSkill"
49+
```
50+
4051
Once installed, you can check that the CLI is correctly set up:
4152

4253
```bash
@@ -122,7 +133,7 @@ To upgrade to the latest version, run:
122133
>>> hf update
123134
```
124135

125-
This detects how `hf` was installed (Homebrew, standalone installer, or pip) and runs the matching update command.
136+
This detects how `hf` was installed (Homebrew, standalone installer, or pip) and runs the matching update command. If the `hf-cli` skill is installed globally, it is refreshed as well so agents see the new command surface. If it isn't, it stays uninstalled: updating never brings it back if you skipped or removed it.
126137

127138
By default, the CLI also prints a one-line yellow warning to stderr when a newer version is available on PyPI. To silence it (e.g. in offline CI), set `HF_HUB_DISABLE_UPDATE_CHECK=1`.
128139

‎docs/source/en/package_reference/environment_variables.md‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -185,7 +185,9 @@ You can set `HF_HUB_DISABLE_TELEMETRY=1` as environment variable to globally dis
185185

186186
By default, the `hf` CLI checks PyPI for a newer release at startup (at most once every 24 hours) and prints a one-line yellow warning to stderr when one is available, suggesting `hf update`. The check is already a no-op on dev and pre-release versions.
187187

188-
Set `HF_HUB_DISABLE_UPDATE_CHECK=1` to skip the PyPI request and silence the warning entirely. Useful in offline CI environments or when you prefer a quieter shell output.
188+
It also checks (at most once every 24 hours, purely locally) whether the `hf-cli` skill is installed and generated by the running version, and suggests `hf skills add` / `hf skills update` if not. The check only prints a hint, it never touches your skills directories.
189+
190+
Set `HF_HUB_DISABLE_UPDATE_CHECK=1` to skip the PyPI request and silence both hints entirely. Useful in offline CI environments or when you prefer a quieter shell output.
189191

190192
### HF_HUB_DISABLE_XET
191193

‎src/huggingface_hub/cli/_cli_utils.py‎

Lines changed: 12 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -1022,29 +1022,35 @@ def _fetch_latest_brew_version() -> str | None:
10221022
return None
10231023

10241024

1025-
def run_update() -> int:
1025+
def run_update(*, exclude_skill: bool = False) -> int:
10261026
"""Run the install-method-appropriate update command for the `hf` CLI.
10271027
1028+
Set `exclude_skill` to tell the standalone installer not to (re)install the `hf-cli` skill.
1029+
10281030
Raises CLIError if the installation method can't be determined.
10291031
Returns the subprocess exit code on success/failure of the update itself.
10301032
"""
1031-
cmd = _get_huggingface_hub_update_command()
1033+
cmd = _get_huggingface_hub_update_command(exclude_skill=exclude_skill)
10321034
if cmd is None:
10331035
raise CLIError(
10341036
"Cannot determine how to update huggingface_hub (unknown installation method). Please update manually."
10351037
)
10361038
return subprocess.call(cmd)
10371039

10381040

1039-
def _get_huggingface_hub_update_command() -> list[str] | None:
1041+
def _get_huggingface_hub_update_command(*, exclude_skill: bool = False) -> list[str] | None:
10401042
"""Return the command to update huggingface_hub as an argv list, or None if the installation method is unknown."""
10411043
match installation_method():
10421044
case "brew":
10431045
return ["brew", "upgrade", "hf"]
10441046
case "hf_installer" if os.name == "nt":
1045-
return ["powershell", "-NoProfile", "-Command", "iwr -useb https://hf.co/cli/install.ps1 | iex"]
1047+
# `iwr ... | iex` cannot take parameters: create a scriptblock so flags reach the installer.
1048+
flags = " -ExcludeSkill" if exclude_skill else ""
1049+
script = f"& ([scriptblock]::Create((iwr -useb https://hf.co/cli/install.ps1))){flags}"
1050+
return ["powershell", "-NoProfile", "-Command", script]
10461051
case "hf_installer":
1047-
return ["bash", "-c", "curl -LsSf https://hf.co/cli/install.sh | bash -"]
1052+
flags = " -s -- --exclude-skill" if exclude_skill else " -"
1053+
return ["bash", "-c", f"curl -LsSf https://hf.co/cli/install.sh | bash{flags}"]
10481054
case "pip":
10491055
return [sys.executable, "-m", "pip", "install", "-U", "huggingface_hub"]
10501056
case _:
@@ -1059,7 +1065,7 @@ def _get_transformers_update_command() -> list[str] | None:
10591065
"powershell",
10601066
"-NoProfile",
10611067
"-Command",
1062-
"iwr -useb https://hf.co/cli/install.ps1 | iex -WithTransformers",
1068+
"& ([scriptblock]::Create((iwr -useb https://hf.co/cli/install.ps1))) -WithTransformers",
10631069
]
10641070
case "hf_installer":
10651071
return ["bash", "-c", "curl -LsSf https://hf.co/cli/install.sh | bash -s -- --with-transformers"]

‎src/huggingface_hub/cli/_skills.py‎

Lines changed: 79 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -4,18 +4,23 @@
44
import re
55
import shutil
66
import tempfile
7+
import time
78
from collections.abc import Callable
89
from dataclasses import dataclass, replace
910
from pathlib import Path, PurePosixPath
1011
from typing import Any, Literal
1112

13+
from huggingface_hub import __version__, constants
1214
from huggingface_hub._buckets import BucketFile
1315
from huggingface_hub.errors import CLIError
1416

15-
from ..utils import disable_progress_bars
17+
from ..utils import disable_progress_bars, logging
1618
from ._cli_utils import get_hf_api
19+
from ._output import out
1720

1821

22+
logger = logging.get_logger(__name__)
23+
1924
DEFAULT_SKILL_ID = "hf-cli"
2025
DEFAULT_SKILLS_BUCKET_ID = "huggingface/skills"
2126
MARKETPLACE_PATH = "marketplace.json"
@@ -309,3 +314,76 @@ def _apply_single_update(
309314
return replace(base, status="source_unreachable", detail=str(exc))
310315

311316
return replace(base, status="up_to_date")
317+
318+
319+
### `hf-cli` SKILL CHECKER
320+
321+
322+
# Version stamp written in the generated SKILL.md (see `build_skill_md`).
323+
_GENERATED_VERSION_RE = re.compile(r"Generated with `huggingface_hub v([^`]+)`")
324+
325+
326+
def check_skill_update() -> None:
327+
"""Hint at installing or updating the `hf-cli` skill, at most once every 24 hours.
328+
329+
Only prints a hint: installing or updating stays an explicit user action.
330+
331+
Skipped entirely if `HF_HUB_DISABLE_UPDATE_CHECK` is set. Called at the entry point of
332+
the CLI, so any error is caught and logged to avoid breaking the CLI.
333+
"""
334+
try:
335+
_check_skill_update()
336+
except Exception:
337+
logger.debug("Error while checking for hf-cli skill update.", exc_info=True)
338+
339+
340+
def _check_skill_update() -> None:
341+
if constants.HF_HUB_DISABLE_UPDATE_CHECK:
342+
return
343+
344+
# Skip if already checked in the last 24 hours
345+
stamp_path = Path(constants.CHECK_FOR_SKILL_UPDATE_DONE_PATH)
346+
if stamp_path.exists() and (time.time() - stamp_path.stat().st_mtime) < 24 * 3600:
347+
return
348+
stamp_path.parent.mkdir(parents=True, exist_ok=True)
349+
stamp_path.touch()
350+
351+
global_dirs = _installed_hf_cli_dirs(constants.AGENTS_SKILLS_GLOBAL_PATH, constants.CLAUDE_SKILLS_GLOBAL_PATH)
352+
local_dirs = _installed_hf_cli_dirs(constants.AGENTS_SKILLS_LOCAL_PATH, constants.CLAUDE_SKILLS_LOCAL_PATH)
353+
354+
if not global_dirs and not local_dirs:
355+
# Don't push the skill on pre-release / dev versions (same rule as the PyPI update check).
356+
if any(tag in __version__ for tag in ["rc", "dev"]):
357+
return
358+
out.hint(
359+
f"The `{DEFAULT_SKILL_ID}` skill is not installed. Run `hf skills add -g --claude`"
360+
" to teach your AI agents how to use the `hf` CLI."
361+
)
362+
return
363+
364+
# Suggest the command matching where the outdated skill is installed (global takes precedence).
365+
if any(_is_skill_outdated(skill_dir) for skill_dir in global_dirs):
366+
scope = "-g --claude"
367+
elif any(_is_skill_outdated(skill_dir) for skill_dir in local_dirs):
368+
scope = "--claude"
369+
else:
370+
return
371+
out.hint(
372+
f"The installed `{DEFAULT_SKILL_ID}` skill was generated by another `hf` version."
373+
f" Run `hf skills update {DEFAULT_SKILL_ID} {scope}` to refresh it."
374+
)
375+
376+
377+
def _installed_hf_cli_dirs(*roots: Path) -> list[Path]:
378+
dirs = [(root.expanduser() / DEFAULT_SKILL_ID).resolve() for root in roots]
379+
return [skill_dir for skill_dir in dict.fromkeys(dirs) if skill_dir.is_dir()]
380+
381+
382+
def _is_skill_outdated(skill_dir: Path) -> bool:
383+
"""Whether the installed `hf-cli` SKILL.md was generated by another `hf` version."""
384+
try:
385+
content = (skill_dir / "SKILL.md").read_text(encoding="utf-8")
386+
except OSError:
387+
return False
388+
match = _GENERATED_VERSION_RE.search(content)
389+
return match is None or match.group(1) != __version__

‎src/huggingface_hub/cli/hf.py‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -24,6 +24,7 @@
2424
from huggingface_hub.cli._cp import CP_EXAMPLES, make_cp
2525
from huggingface_hub.cli._errors import format_known_exception
2626
from huggingface_hub.cli._output import out
27+
from huggingface_hub.cli._skills import check_skill_update
2728
from huggingface_hub.cli.auth import auth_cli
2829
from huggingface_hub.cli.buckets import buckets_cli, sync
2930
from huggingface_hub.cli.cache import cache_cli
@@ -123,6 +124,10 @@ def main():
123124
if not constants.HF_DEBUG:
124125
logging.set_verbosity_info()
125126
check_cli_update("huggingface_hub")
127+
# Don't nag while the user is already managing skills, nor on `hf update` which handles the
128+
# skill itself (it would print a redundant or contradictory hint before doing so).
129+
if sys.argv[1:2] not in (["skills"], ["update"]):
130+
check_skill_update()
126131

127132
try:
128133
app()

‎src/huggingface_hub/cli/skills.py‎

Lines changed: 16 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -20,6 +20,7 @@
2020

2121
from click import Command, Context, Group
2222

23+
from huggingface_hub import constants
2324
from huggingface_hub.errors import CLIError
2425

2526
from ..utils import disable_progress_bars
@@ -86,10 +87,6 @@
8687
- Update the CLI with `hf update` (uses the correct command for the detected install method)
8788
"""
8889

89-
CENTRAL_LOCAL = Path(".agents/skills")
90-
CENTRAL_GLOBAL = Path("~/.agents/skills")
91-
CLAUDE_LOCAL = Path(".claude/skills")
92-
CLAUDE_GLOBAL = Path("~/.claude/skills")
9390
# Flags worth explaining in the common-options glossary. Self-explanatory flags
9491
# (--namespace, --yes, --private, …) are omitted even if they appear frequently.
9592
_COMMON_FLAG_ALLOWLIST = {"--token", "--quiet", "--type", "--format", "--revision"}
@@ -334,7 +331,12 @@ def _create_symlink(agent_skills_dir: Path, skill_name: str, central_skill_path:
334331
link_path = agent_skills_dir / skill_name
335332

336333
_remove_existing(link_path, force)
337-
link_path.symlink_to(os.path.relpath(central_skill_path, agent_skills_dir))
334+
try:
335+
link_path.symlink_to(os.path.relpath(central_skill_path, agent_skills_dir))
336+
except OSError:
337+
# Windows needs Developer Mode or admin rights for symlinks.
338+
# Fall back to a copy: `hf skills update` walks both roots, so the copy stays in sync.
339+
shutil.copytree(central_skill_path, link_path)
338340

339341
return link_path
340342

@@ -350,9 +352,9 @@ def _resolve_update_roots(
350352
raise CLIError("--dest cannot be combined with --claude or --global.")
351353
return [dest.expanduser().resolve()]
352354

353-
roots: list[Path] = [CENTRAL_GLOBAL if global_ else CENTRAL_LOCAL]
355+
roots: list[Path] = [constants.AGENTS_SKILLS_GLOBAL_PATH if global_ else constants.AGENTS_SKILLS_LOCAL_PATH]
354356
if claude:
355-
roots.append(CLAUDE_GLOBAL if global_ else CLAUDE_LOCAL)
357+
roots.append(constants.CLAUDE_SKILLS_GLOBAL_PATH if global_ else constants.CLAUDE_SKILLS_LOCAL_PATH)
356358
return [root.expanduser().resolve() for root in roots]
357359

358360

@@ -374,10 +376,10 @@ def skills_list(
374376
) -> None:
375377
"""List available skills from the Hugging Face marketplace."""
376378
install_locations: list[tuple[str, Path]] = [
377-
("project", CENTRAL_LOCAL),
378-
("project (claude)", CLAUDE_LOCAL),
379-
("global", CENTRAL_GLOBAL),
380-
("global (claude)", CLAUDE_GLOBAL),
379+
("project", constants.AGENTS_SKILLS_LOCAL_PATH),
380+
("project (claude)", constants.CLAUDE_SKILLS_LOCAL_PATH),
381+
("global", constants.AGENTS_SKILLS_GLOBAL_PATH),
382+
("global (claude)", constants.CLAUDE_SKILLS_GLOBAL_PATH),
381383
]
382384
installed: dict[str, set[str]] = {}
383385
for label, root in install_locations:
@@ -458,14 +460,14 @@ def skills_add(
458460
return
459461

460462
# Install to central location
461-
central_path = CENTRAL_GLOBAL if global_ else CENTRAL_LOCAL
463+
central_path = constants.AGENTS_SKILLS_GLOBAL_PATH if global_ else constants.AGENTS_SKILLS_LOCAL_PATH
462464
central_skill_path = _install_to(central_path, name, force)
463465
print(f"Installed '{name}' to central location: {central_skill_path}")
464466

465467
if claude:
466-
agent_target = CLAUDE_GLOBAL if global_ else CLAUDE_LOCAL
468+
agent_target = constants.CLAUDE_SKILLS_GLOBAL_PATH if global_ else constants.CLAUDE_SKILLS_LOCAL_PATH
467469
link_path = _create_symlink(agent_target, name, central_skill_path, force)
468-
print(f"Created symlink: {link_path}")
470+
print(f"Created symlink: {link_path}" if link_path.is_symlink() else f"Copied '{name}' to {link_path}")
469471

470472

471473
@skills_cli.command(

0 commit comments

Comments
 (0)