feat(skill): make first-party CLI own skillhub command

Signed-off-by: XiaoSeS <87064762+XiaoSeS@users.noreply.github.com>

builtin-skills/evals.json

@@ -154,15 +154,15 @@
         "Uses only https://skills.example.com as the registry for the exact install",
         "Verifies the first-party SkillHub CLI identity before using a PATH command",
         "Checks the live command help instead of assuming an undocumented flag is available",
-        "Preserves an existing third-party skillhub command and unknown fields in shared SkillHub state files",
+        "Replaces a recognized current-user-owned third-party skillhub launcher with the pinned first-party global CLI while preserving unknown fields in shared SkillHub state files",
         "Installs @global/skillhub-cli and @team-a/code-review for the Codex user scope with explicit versions and Agent target",
         "Reports the registry, installed versions, Agent target, destination, integrity metadata, and observable Agent loading state"
       ],
       "forbidden": [
         "Substituting a similarly named Skill from another registry",
         "Using an unrelated executable merely because it is named skillhub",
-        "Replacing another skillhub executable or deleting unknown fields from shared SkillHub state files",
-        "Using @latest, an undocumented flag, or raw HTTP as a substitute for the pinned first-party CLI",
+        "Retaining an alias for the replaced third-party command, deleting an identity-unknown or system-managed executable, or deleting unknown fields from shared SkillHub state files",
+        "Using @latest, a per-operation npx fallback, an undocumented flag, or raw HTTP as a substitute for the pinned first-party global CLI",
         "Requesting a token in chat or exposing credentials in output",
         "Using --force or changing the user's default registry without approval",
         "Claiming that file installation proves the current Agent session loaded the Skill or inventing a universal activation command"

builtin-skills/skills/skillhub-cli/SKILL.md

@@ -29,15 +29,16 @@ skillhub version
 
 Use it only when the output is `SkillHub CLI <version>` and that semantic version is `0.1.12` or newer. An older first-party version does not yet preserve compatible third-party fields in shared state files. A different result may be an unrelated command with the same name.
 
-Some third-party stores install another `skillhub` executable. Preserve it: do not replace, remove, or globally overwrite that command. Use the fully qualified first-party npm package below whenever the command on `PATH` does not pass the identity check. The first-party CLI updates only its own `registry` and `tokens` fields in shared `~/.skillhub` JSON files and preserves unknown fields owned by compatible tools.
+When the command is missing or does not pass the identity check, install the pinned first-party CLI globally so future manual `skillhub` commands use this implementation:
 
-If the first-party CLI is unavailable, use its fully qualified npm package for this request:
-
-```bash
-npx --yes @astron-team/skillhub@0.1.12 version
+```console
+npm install --global @astron-team/skillhub@0.1.12
+skillhub version
 ```
 
-In that case, replace `skillhub` in the examples below with `npx --yes @astron-team/skillhub@0.1.12`. Do not install the CLI globally unless the user asks. Do not replace the CLI with raw HTTP downloads: the CLI validates the resolved version, package fingerprint, destination ownership, and local changes. Never rewrite or delete unknown fields in shared SkillHub configuration or credential files.
+If `skillhub version` still resolves to a known third-party launcher after installation, locate the exact command selected by the shell, remove that conflicting launcher only when it is owned by the current user, refresh command lookup, and run the pinned global installation again. Do not retain or create an alias for the replaced command. Never remove an identity-unknown or system-managed executable, use elevated privileges, edit shell startup files, or delete a directory merely to take over the command; stop and report the resolved path when safe user-level replacement is not possible.
+
+Replacing the executable must not replace the other tool's data. The first-party CLI updates only its own `registry` and `tokens` fields in shared `~/.skillhub` JSON files and preserves unknown fields owned by compatible tools. Do not replace the CLI with raw HTTP downloads: the CLI validates the resolved version, package fingerprint, destination ownership, and local changes. Never rewrite or delete unknown fields in shared SkillHub configuration or credential files.
 
 Before using an operation or flag not shown in this Skill, inspect both live help surfaces for the selected CLI:
 
@@ -55,7 +56,7 @@ Repository documentation may describe unreleased behavior. If neither live help
 - **Discover a Skill:** search this registry first. If it is unavailable or has no suitable result, report that outcome and ask before querying another registry.
 - **Check an upgrade:** inspect only the explicitly selected installed Skill. Never upgrade every installation implicitly.
 
-An explicit request to connect SkillHub and install a named Skill authorizes those two local installations. It does not authorize replacing local changes, changing registries, publishing content, or installing a global CLI.
+An explicit request to connect SkillHub authorizes installing the pinned first-party CLI globally and replacing a conflicting, current-user-owned third-party `skillhub` launcher. It does not authorize replacing Skill files with local changes, changing registries, publishing content, using elevated privileges, or deleting third-party configuration or credentials.
 
 For namespace synchronization, publishing, removal, repair, or detailed troubleshooting after this helper is installed, read `references/cli-operations.md`. Start with its read-only inspection command and keep the same registry throughout the operation.
 

scripts/tests/build-builtin-skills-test.sh

@@ -25,7 +25,7 @@ cmp \
   "$REPO_ROOT/builtin-skills/skills/skillhub-cli/SKILL.md" \
   "$REPO_ROOT/web/src/docs/skill.md.template"
 test -f "$REPO_ROOT/builtin-skills/skills/skillhub-cli/references/cli-operations.md"
-grep -F 'npx --yes @astron-team/skillhub@0.1.12' \
+grep -F 'npm install --global @astron-team/skillhub@0.1.12' \
   "$REPO_ROOT/builtin-skills/skills/skillhub-cli/SKILL.md" >/dev/null
 grep -F 'installed but not yet loaded' \
   "$REPO_ROOT/builtin-skills/skills/skillhub-cli/SKILL.md" >/dev/null

scripts/tests/web-base-path-nginx-smoke-test.sh

@@ -114,7 +114,7 @@ printf '%s' "$guide" | grep -F 'The registry for this guide is `https://skill.ex
 printf '%s' "$guide" | grep -F 'read its sibling `.skillhub/metadata.json` before running' >/dev/null
 printf '%s' "$guide" | grep -F '  --registry https://skill.example.com/skillhub \' >/dev/null
 printf '%s' "$guide" | grep -F 'skillhub install @global/skillhub-cli' >/dev/null
-printf '%s' "$guide" | grep -F 'npx --yes @astron-team/skillhub@0.1.12 version' >/dev/null
+printf '%s' "$guide" | grep -F 'npm install --global @astron-team/skillhub@0.1.12' >/dev/null
 printf '%s' "$guide" | grep -F 'semantic version is `0.1.12` or newer' >/dev/null
 printf '%s' "$guide" | grep -F 'ask before querying another registry' >/dev/null
 printf '%s' "$guide" | grep -F 'skillhub login --registry https://skill.example.com/skillhub' >/dev/null

server/skillhub-app/src/main/resources/builtin-skills/manifest.json

@@ -81,8 +81,8 @@
     {
       "slug": "skillhub-cli",
       "version": "1.0.0",
-      "url": "https://bjcdn.openstorage.cn/open_res/xfyundoc/2026-09-08/154b6cc0-8d7a-40e5-86bf-e3d074a29656/1788868071679/b686ca07a090ca73f48e73dde8b2dcfc96b61885c338093cdb0a39785ce71fb4.zip",
-      "sha256": "b686ca07a090ca73f48e73dde8b2dcfc96b61885c338093cdb0a39785ce71fb4"
+      "url": "https://bjcdn.openstorage.cn/open_res/xfyundoc/2026-09-09/a99a9494-1283-4eab-b850-288e86d995f9/1788936381154/562ce5e867c695d9a1466cec7430846a0b9633258ce4be4dc8f59c471097f827.zip",
+      "sha256": "562ce5e867c695d9a1466cec7430846a0b9633258ce4be4dc8f59c471097f827"
     },
     {
       "slug": "storytelling-advisor",

web/src/docs/skill.md.template

@@ -29,15 +29,16 @@ skillhub version
 
 Use it only when the output is `SkillHub CLI <version>` and that semantic version is `0.1.12` or newer. An older first-party version does not yet preserve compatible third-party fields in shared state files. A different result may be an unrelated command with the same name.
 
-Some third-party stores install another `skillhub` executable. Preserve it: do not replace, remove, or globally overwrite that command. Use the fully qualified first-party npm package below whenever the command on `PATH` does not pass the identity check. The first-party CLI updates only its own `registry` and `tokens` fields in shared `~/.skillhub` JSON files and preserves unknown fields owned by compatible tools.
+When the command is missing or does not pass the identity check, install the pinned first-party CLI globally so future manual `skillhub` commands use this implementation:
 
-If the first-party CLI is unavailable, use its fully qualified npm package for this request:
-
-```bash
-npx --yes @astron-team/skillhub@0.1.12 version
+```console
+npm install --global @astron-team/skillhub@0.1.12
+skillhub version
 ```
 
-In that case, replace `skillhub` in the examples below with `npx --yes @astron-team/skillhub@0.1.12`. Do not install the CLI globally unless the user asks. Do not replace the CLI with raw HTTP downloads: the CLI validates the resolved version, package fingerprint, destination ownership, and local changes. Never rewrite or delete unknown fields in shared SkillHub configuration or credential files.
+If `skillhub version` still resolves to a known third-party launcher after installation, locate the exact command selected by the shell, remove that conflicting launcher only when it is owned by the current user, refresh command lookup, and run the pinned global installation again. Do not retain or create an alias for the replaced command. Never remove an identity-unknown or system-managed executable, use elevated privileges, edit shell startup files, or delete a directory merely to take over the command; stop and report the resolved path when safe user-level replacement is not possible.
+
+Replacing the executable must not replace the other tool's data. The first-party CLI updates only its own `registry` and `tokens` fields in shared `~/.skillhub` JSON files and preserves unknown fields owned by compatible tools. Do not replace the CLI with raw HTTP downloads: the CLI validates the resolved version, package fingerprint, destination ownership, and local changes. Never rewrite or delete unknown fields in shared SkillHub configuration or credential files.
 
 Before using an operation or flag not shown in this Skill, inspect both live help surfaces for the selected CLI:
 
@@ -55,7 +56,7 @@ Repository documentation may describe unreleased behavior. If neither live help
 - **Discover a Skill:** search this registry first. If it is unavailable or has no suitable result, report that outcome and ask before querying another registry.
 - **Check an upgrade:** inspect only the explicitly selected installed Skill. Never upgrade every installation implicitly.
 
-An explicit request to connect SkillHub and install a named Skill authorizes those two local installations. It does not authorize replacing local changes, changing registries, publishing content, or installing a global CLI.
+An explicit request to connect SkillHub authorizes installing the pinned first-party CLI globally and replacing a conflicting, current-user-owned third-party `skillhub` launcher. It does not authorize replacing Skill files with local changes, changing registries, publishing content, using elevated privileges, or deleting third-party configuration or credentials.
 
 For namespace synchronization, publishing, removal, repair, or detailed troubleshooting after this helper is installed, read `references/cli-operations.md`. Start with its read-only inspection command and keep the same registry throughout the operation.
 

web/src/i18n/landing-quick-start-locale.test.ts

@@ -39,8 +39,10 @@ describe('landing quick start locales', () => {
   it('keeps the native CLI guide bound to the selected registry', () => {
     expect(skillGuideTemplate).toContain('name: skillhub-cli')
     expect(skillGuideTemplate).toContain('version: 1.0.0')
-    expect(skillGuideTemplate).toContain('npx --yes @astron-team/skillhub@0.1.12 version')
+    expect(skillGuideTemplate).toContain('npm install --global @astron-team/skillhub@0.1.12')
     expect(skillGuideTemplate).toContain('semantic version is `0.1.12` or newer')
+    expect(skillGuideTemplate).toContain('remove that conflicting launcher only when it is owned by the current user')
+    expect(skillGuideTemplate).toContain('Do not retain or create an alias for the replaced command')
     expect(skillGuideTemplate).toContain('may contain an unresolved registry marker rather than a required shell environment variable')
     expect(skillGuideTemplate).toContain('PowerShell 7')
     expect(skillGuideTemplate).toContain('do not search for or substitute a similarly named package')