From 58a48e2670474188eb3f486734695e34d45ed2b2 Mon Sep 17 00:00:00 2001 From: dongmucat <1127093059@qq.com> Date: Sat, 9 May 2026 15:01:00 +0800 Subject: [PATCH] docs: restructure CLI README and sync guide docs with improvements MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 变更摘要： - 重构 cli/README.md 大纲结构，参考 guide 文档重新组织章节逻辑 - 补充 Windows PowerShell/CMD 环境变量设置方式到三份文档 - Command Reference 表格补全 --json、--registry、--token 等选项 - 英文 guide Registry 优先级第3条补充文件路径与中文版对齐 - 两份 guide 末尾补充 License 章节，Local Development 补 Windows 说明 - README 各章节标题添加语义化 emoji icon 关键文件： - cli/README.md - docs/skillhub/en/guide/cli.md - docs/skillhub/guide/cli.md --- cli/README.md | 408 ++++++++++++++++++++++++++-------- docs/skillhub/en/guide/cli.md | 30 ++- docs/skillhub/guide/cli.md | 28 ++- 3 files changed, 374 insertions(+), 92 deletions(-) diff --git a/cli/README.md b/cli/README.md index 98d93fda..3f64aec0 100644 --- a/cli/README.md +++ b/cli/README.md @@ -1,158 +1,392 @@ # SkillHub CLI -Manage and install skills for AI coding agents. - -SkillHub is an enterprise-grade, self-hosted skill registry that enables teams to discover, share, and install reusable skills for AI coding agents like Claude Code. This CLI provides a seamless interface to interact with SkillHub registries. +SkillHub CLI is the official command-line tool for SkillHub, designed for searching, installing, managing, and publishing Agent skill packages. ## 📦 Installation ```bash +# Install globally via npm npm install -g @astron-team/skillhub + +# Or run directly with npx +npx @astron-team/skillhub@latest version + +# Or install globally via Bun +bun add -g @astron-team/skillhub ``` ## 🚀 Quick Start -### Using the default registry - ```bash -# Login to the default registry -skillhub login +# Login +skillhub login --token sk_xxx -# Search for skills -skillhub search react +# Search skills +skillhub search pdf -# Install a skill -skillhub install @astron-team/react-component-builder +# Install skill to Agent directory +skillhub install pdf-parser --agent codex # List installed skills skillhub list + +# Publish skill +skillhub publish ./my-skill --namespace myspace ``` -### Using a custom registry +## 🌐 Registry Configuration + +The active registry is resolved in the following priority order: + +1. `--registry ` command-line argument +2. `SKILLHUB_REGISTRY` environment variable +3. `registry` in `~/.skillhub/config.json` +4. Default value `https://skill.xfyun.cn` ```bash -# Login to a custom registry -skillhub login --registry https://skillhub.yourcompany.com +# Temporarily use another registry +skillhub search pdf --registry https://skillhub.example.com -# After login, other commands will use the same registry -skillhub search react -skillhub install @yourorg/custom-skill +# Set via environment variable (Linux/macOS) +export SKILLHUB_REGISTRY=https://skillhub.example.com ``` -You can also set a default custom registry in your shell: +**Windows PowerShell:** -**🐧 Linux/macOS (Bash/Zsh):** -```bash -export SKILLHUB_REGISTRY=https://skillhub.yourcompany.com -``` - -**🪟 Windows (PowerShell):** ```powershell -$env:SKILLHUB_REGISTRY="https://skillhub.yourcompany.com" +$env:SKILLHUB_REGISTRY="https://skillhub.example.com" ``` -**🪟 Windows (CMD):** +**Windows CMD:** + ```cmd -set SKILLHUB_REGISTRY=https://skillhub.yourcompany.com +set SKILLHUB_REGISTRY=https://skillhub.example.com ``` -## 📚 Commands +## 🔐 Authentication -### 🔐 Authentication +Token resolution priority: -- `skillhub login [--registry ]` - Authenticate with a SkillHub registry -- `skillhub logout [--registry ]` - Remove stored credentials +1. `--token ` command-line argument +2. `SKILLHUB_TOKEN` environment variable +3. Token stored in `~/.skillhub/credentials.json` (per registry) -### 🎯 Skill Management - -- `skillhub search ` - Search for skills in the registry -- `skillhub install ` - Install a skill to ~/.claude/skills/ -- `skillhub uninstall ` - Remove an installed skill -- `skillhub list` - List all installed skills -- `skillhub info ` - Show detailed information about a skill - -### 🛠️ Utilities - -- `skillhub version` - Display CLI version -- `skillhub help` - Show help information -- `skillhub doctor [--json]` - Scan the current project for installed skills and merge findings into the local inventory. Existing entries outside the scan are preserved; conflicts are reported but unrelated records are not deleted. - -## 💡 Examples - -### Search and install a skill +### Login ```bash -# Search for React-related skills -skillhub search react +# Login with API token +skillhub login --token sk_xxx -# Install a specific skill -skillhub install @astron-team/react-component-builder +# Login to specific registry +skillhub login --token sk_xxx --registry https://skillhub.example.com +``` -# Verify installation +`login` validates the token, stores it in `~/.skillhub/credentials.json`, and writes the registry to `~/.skillhub/config.json`. + +### Check Current Identity + +```bash +skillhub whoami + +# Check specific registry +skillhub whoami --registry https://skillhub.example.com + +# Temporarily use different token +skillhub whoami --token sk_other +``` + +### Logout + +```bash +skillhub logout + +# Logout from specific registry +skillhub logout --registry https://skillhub.example.com +``` + +Logout only removes the token for the specified registry, preserving registry configuration and installation records. + +## 🔍 Search + +```bash +# Keyword search +skillhub search pdf + +# List all skills (empty query) +skillhub search "" --limit 50 + +# JSON output +skillhub search pdf --json +``` + +Output format: `namespace/slug version summary` + +## 📥 Install Skills + +```bash +# Install to auto-detected Agent directory +skillhub install pdf-parser + +# Specify namespace (default: global) +skillhub install pdf-parser --namespace myspace + +# Specify version +skillhub install pdf-parser --version 1.2.0 + +# Install to specific Agent +skillhub install pdf-parser --agent codex + +# Install to multiple Agents +skillhub install pdf-parser --agent codex --agent claude-code + +# Install to custom directory +skillhub install pdf-parser --dir ~/.claude/skills + +# Force overwrite existing installation +skillhub install pdf-parser --force +``` + +### Install Target Resolution + +The CLI determines the installation location using the following logic: + +1. If `--dir` is specified: Install to that directory, agent marked as `custom` +2. If `--agent` is specified: Install to the corresponding Agent's skills directory +3. If neither is specified: Auto-scan current directory to detect existing Agent config directories + - 1 Agent detected → Install directly + - Multiple Agents detected → Interactive selection (TTY mode) or error (non-interactive mode) + - No Agent detected → Fallback to `/.agents/skills/` + +> `--dir` and `--agent` cannot be used together. + +### Install Paths + +Each Agent has both project-level and user-level skills directories: + +| Agent | Project-level Path | User-level Path | +|-------|-------------------|-----------------| +| `claude-code` | `/.claude/skills/` | `~/.claude/skills/` | +| `codex` | `/.codex/skills/` | `~/.codex/skills/` | +| `cursor` | `/.cursor/skills/` | `~/.cursor/skills/` | +| `github-copilot` | `/.github-copilot/skills/` | `~/.github-copilot/skills/` | +| `gemini-cli` | `/.gemini-cli/skills/` | `~/.gemini-cli/skills/` | +| `windsurf` | `/.windsurf/skills/` | `~/.windsurf/skills/` | +| `kiro-cli` | `/.kiro-cli/skills/` | `~/.kiro-cli/skills/` | +| `roo` | `/.roo/skills/` | `~/.roo/skills/` | +| `trae` | `/.trae/skills/` | `~/.trae/skills/` | +| `trae-cn` | `/.trae-cn/skills/` | `~/.trae-cn/skills/` | +| `openhands` | `/.openhands/skills/` | `~/.openhands/skills/` | +| `openclaw` | `/.openclaw/skills/` | `~/.openclaw/skills/` | +| `opencode` | `/.opencode/skills/` | `~/.opencode/skills/` | +| `kilo` | `/.kilo/skills/` | `~/.kilo/skills/` | + +For Agents not in the list, use `--dir` to specify the installation path. + +### File Structure After Installation + +``` +.codex/skills/pdf-parser/ +├── ... # Extracted skill package files +└── .skillhub/ + └── metadata.json # Installation metadata +``` + +`metadata.json` example: + +```json +{ + "registry": "https://skill.xfyun.cn", + "namespace": "global", + "slug": "pdf-parser", + "version": "1.0.0", + "agent": "codex", + "installedAt": "2026-04-28T06:00:00.000Z" +} +``` + +## 📋 Local Management + +### List Installed Skills + +```bash +# List all installed skills skillhub list + +# Filter by Agent +skillhub list --agent codex + +# Filter by multiple Agents +skillhub list --agent codex --agent claude-code + +# Filter by directory +skillhub list --dir ~/.codex/skills + +# JSON output +skillhub list --json ``` -### Manage installed skills +### Remove Skills ```bash -# View details about an installed skill -skillhub info @astron-team/react-component-builder +# Remove all local installation targets +skillhub remove pdf-parser -# Uninstall a skill -skillhub uninstall @astron-team/react-component-builder +# Remove only specific Agent's installation +skillhub remove pdf-parser --agent codex + +# Remove all targets (skip interactive confirmation) +skillhub remove pdf-parser --all + +# Remove remote skill (requires authentication, prompts for confirmation) +skillhub remove pdf-parser --remote --namespace myspace + +# Skip remote deletion confirmation +skillhub remove pdf-parser --remote --hard --namespace myspace ``` -### Work with custom registries +> Parameter exclusivity rules: +> - `--all` cannot be used with `--agent` +> - `--remote` cannot be used with `--agent` or `--all` +> - Remote deletion in non-interactive environments requires `--hard` + +### Rebuild Local Inventory ```bash -# Login to your private registry -skillhub login --registry https://skillhub.yourcompany.com - -# After login, search and install work automatically -skillhub search internal-tools -skillhub install @yourorg/internal-skill +skillhub doctor ``` -## 🌐 Registry +`doctor` performs the following operations: -### Default registry +1. Scans `/./skills//.skillhub/metadata.json` +2. Groups by `registry + namespace + slug` +3. Backs up old `inventory.json` (if exists) +4. Writes new `inventory.json` -By default, the CLI connects to the public SkillHub registry at `https://skill.xfyun.cn`. +If the same skill has version conflicts across different targets, that skill will be skipped and reported. -### Custom registry +## 🚢 Publishing -Organizations can deploy their own private SkillHub instance. You can point the CLI to a custom registry: - -**Per-command (recommended for one-time use):** ```bash -skillhub login --registry https://skillhub.yourcompany.com +# Publish directory (auto-packaged as zip) +skillhub publish ./my-skill --namespace myspace + +# Publish existing zip file +skillhub publish ./my-skill.zip --namespace myspace + +# Specify visibility +skillhub publish ./my-skill --namespace myspace --visibility private ``` -**Shell-level default (persistent across commands):** +Visibility options: +- `public` (default) — Visible to everyone +- `namespace-only` — Visible to namespace members only +- `private` — Visible to yourself only + +After successful publication, the skill detail page URL will be displayed. + +## ⬆️ Self-Update -🐧 Linux/macOS: ```bash -export SKILLHUB_REGISTRY=https://skillhub.yourcompany.com +# Check for new version +skillhub update --check + +# Execute update +skillhub update ``` -🪟 Windows PowerShell: -```powershell -$env:SKILLHUB_REGISTRY="https://skillhub.yourcompany.com" +Update mechanism: +- Installed via npm globally: Auto-executes `npm install -g @astron-team/skillhub@latest` +- Installed via Bun globally: Auto-executes `bun add -g @astron-team/skillhub@latest` +- Run via npx: Prompts manual update command +- Unknown installation method: Prompts manual update + +## 🔧 Environment Variables + +| Variable | Description | Priority | +|----------|-------------|----------| +| `SKILLHUB_REGISTRY` | Default registry URL | Lower than `--registry` parameter | +| `SKILLHUB_TOKEN` | API token | Lower than `--token` parameter, higher than stored token | + +## 📂 Local File Structure + +``` +~/.skillhub/ +├── config.json # User configuration (registry, defaultAgent, etc.) +├── credentials.json # API tokens (stored per registry, permissions 0600) +└── inventory.json # Installed skills inventory ``` -🪟 Windows CMD: -```cmd -set SKILLHUB_REGISTRY=https://skillhub.yourcompany.com +## 📖 Command Reference + +| Command | Description | +|---------|-------------| +| `skillhub help [command]` | Display help information | +| `skillhub version [--json]` | Display CLI version | +| `skillhub login --token [--registry ] [--json]` | Save token and registry configuration | +| `skillhub logout [--registry ] [--json]` | Remove token for specified registry | +| `skillhub whoami [--registry ] [--token ] [--json]` | Validate current token and display user information | +| `skillhub search [--registry ] [--limit ] [--json]` | Search published skills | +| `skillhub install [--namespace ] [--version ] [--agent ] [--dir ] [--force] [--registry ] [--token ] [--json]` | Install a skill | +| `skillhub list [--agent ] [--dir ] [--registry ] [--json]` | List installed skills | +| `skillhub remove [--agent ] [--all] [--remote] [--hard] [--namespace ] [--registry ] [--token ] [--json]` | Remove a skill | +| `skillhub doctor [--json]` | Scan project directory and rebuild local inventory | +| `skillhub publish [--namespace ] [--visibility ] [--registry ] [--token ] [--json]` | Publish a skill | +| `skillhub update [--check] [--json]` | Check or execute CLI self-update | + +## 🔒 Security Notes + +- Tokens are stored only in user directory `~/.skillhub/credentials.json` +- On Linux/macOS, credential file permissions are automatically set to `0600` +- Tokens are never written to any project-local files +- Remote delete operations require explicit confirmation or `--hard` parameter +- `remove` command validates path safety to prevent deletion of non-skill directories + +## 🐛 Troubleshooting + +### Authentication Failure + +```bash +# Verify token validity +skillhub whoami + +# Re-login +skillhub login --token sk_xxx ``` -### Skill namespaces +### Network Error -Skills are namespaced by organization to prevent naming conflicts: +```bash +# Check if registry is accessible +curl https://skill.xfyun.cn/api/cli/v1/skills/search?q=test&limit=1 -- `@astron-team/skill-name` - Skills from the Astron team -- `@yourorg/skill-name` - Skills from your organization +# Use alternative registry +skillhub search test --registry https://skillhub.example.com +``` -When installing skills, always include the full namespaced name. +### Installation Directory Conflict + +```bash +# Use --force to overwrite +skillhub install pdf-parser --force + +# Or remove first then install +skillhub remove pdf-parser +skillhub install pdf-parser +``` + +### Corrupted Inventory + +```bash +# Rebuild inventory +skillhub doctor +``` + +## 📚 Documentation + +- [SkillHub Homepage](https://skill.xfyun.cn) +- [GitHub Repository](https://github.com/iflytek/skillhub) +- [CLI Documentation](https://github.com/iflytek/skillhub/blob/main/docs/skillhub/en/guide/cli.md) +- [Issue Tracker](https://github.com/iflytek/skillhub/issues) ## 📄 License diff --git a/docs/skillhub/en/guide/cli.md b/docs/skillhub/en/guide/cli.md index 45fd33bd..dbe7bc8f 100644 --- a/docs/skillhub/en/guide/cli.md +++ b/docs/skillhub/en/guide/cli.md @@ -40,17 +40,29 @@ The active registry is resolved in the following priority order: 1. `--registry ` command-line argument 2. `SKILLHUB_REGISTRY` environment variable -3. `registry` in user configuration +3. `registry` in `~/.skillhub/config.json` 4. Default value `https://skill.xfyun.cn` ```bash # Temporarily use another registry skillhub search pdf --registry https://skillhub.example.com -# Set via environment variable +# Set via environment variable (Linux/macOS) export SKILLHUB_REGISTRY=https://skillhub.example.com ``` +**Windows PowerShell:** + +```powershell +$env:SKILLHUB_REGISTRY="https://skillhub.example.com" +``` + +**Windows CMD:** + +```cmd +set SKILLHUB_REGISTRY=https://skillhub.example.com +``` + ## Authentication Token resolution priority: @@ -583,9 +595,15 @@ bun link cd .. make dev-all -# 3. Configure CLI to connect to local service +# 3. Configure CLI to connect to local service (Linux/macOS) export SKILLHUB_REGISTRY=http://localhost:8080 +# Windows PowerShell: +# $env:SKILLHUB_REGISTRY="http://localhost:8080" + +# Windows CMD: +# set SKILLHUB_REGISTRY=http://localhost:8080 + # 4. Test commands skillhub search test skillhub install example-skill --agent codex @@ -597,3 +615,9 @@ skillhub list - [SkillHub Homepage](https://skill.xfyun.cn) - [GitHub Repository](https://github.com/iflytek/skillhub) - [Issue Tracker](https://github.com/iflytek/skillhub/issues) + +## License + +Apache-2.0 + +Copyright 2026 iFlytek Co., Ltd. diff --git a/docs/skillhub/guide/cli.md b/docs/skillhub/guide/cli.md index fcf7cefd..6c664fbc 100644 --- a/docs/skillhub/guide/cli.md +++ b/docs/skillhub/guide/cli.md @@ -47,10 +47,22 @@ skillhub publish ./my-skill --namespace myspace # 临时使用其他 registry skillhub search pdf --registry https://skillhub.example.com -# 通过环境变量设置 +# 通过环境变量设置（Linux/macOS） export SKILLHUB_REGISTRY=https://skillhub.example.com ``` +**Windows PowerShell:** + +```powershell +$env:SKILLHUB_REGISTRY="https://skillhub.example.com" +``` + +**Windows CMD:** + +```cmd +set SKILLHUB_REGISTRY=https://skillhub.example.com +``` + ## 认证 Token 按以下优先级解析： @@ -583,9 +595,15 @@ bun link cd .. make dev-all -# 3. 配置 CLI 连接本地服务 +# 3. 配置 CLI 连接本地服务（Linux/macOS） export SKILLHUB_REGISTRY=http://localhost:8080 +# Windows PowerShell: +# $env:SKILLHUB_REGISTRY="http://localhost:8080" + +# Windows CMD: +# set SKILLHUB_REGISTRY=http://localhost:8080 + # 4. 测试命令 skillhub search test skillhub install example-skill --agent codex @@ -597,3 +615,9 @@ skillhub list - [SkillHub 主页](https://skill.xfyun.cn) - [GitHub 仓库](https://github.com/iflytek/skillhub) - [问题反馈](https://github.com/iflytek/skillhub/issues) + +## 许可证 + +Apache-2.0 + +Copyright 2026 iFlytek Co., Ltd.