scriptoriumadmin/skillhub
1
0
Fork 0
mirror of https://github.com/iflytek/skillhub.git synced 2026-10-10 03:27:54 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 3

docs(cli): expand CLI usage guide

Browse source 
Document the full CLI workflow so users can understand configuration precedence, install targets, local state files, troubleshooting, and local verification steps.
This commit is contained in:
dongmucat 2026-04-28 15:53:11 +08:00
parent b30de8d7af
commit 26ea7e914b
2 changed files with 852 additions and 52 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

450
docs/skillhub/en/guide/cli.md
View file

@ -53,6 +53,12 @@ export SKILLHUB_REGISTRY=https://skillhub.example.com
## Authentication
Token resolution priority:
1. `--token <token>` command-line argument
2. `SKILLHUB_TOKEN` environment variable
3. Token stored in `~/.skillhub/credentials.json` (per registry)
### Login
```bash
@ -63,37 +69,53 @@ skillhub login --token sk_xxx
skillhub login --token sk_xxx --registry https://skillhub.example.com
```
Tokens are stored only in the user directory `~/.skillhub/credentials.json`, never in project files.
`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, preserving registry configuration and installation records.
Logout only removes the token for the specified registry, preserving registry configuration and installation records.
## Search
```bash
# Keyword search
skillhub search pdf
skillhub search "" --limit 20
# List all skills (empty query)
skillhub search "" --limit 50
# JSON output
skillhub search pdf --json
```
## Installation
Output format: `namespace/slug version summary`
## Install Skills
```bash
# Install to auto-detected Agent directory
skillhub install pdf-parser
# Specify namespace
# Specify namespace (default: global)
skillhub install pdf-parser --namespace myspace
# Specify version
@ -112,38 +134,86 @@ skillhub install pdf-parser --dir ~/.claude/skills
skillhub install pdf-parser --force
```
### Supported Agents
### Install Target Resolution
Built-in support for the following Tier 1 Agents:
The CLI determines the installation location using the following logic:
- `claude-code` - Claude Code
- `codex` - Codex
- `cursor` - Cursor
- `github-copilot` - GitHub Copilot
- `gemini-cli` - Gemini CLI
- `openhands` - OpenHands
- `windsurf` - Windsurf
- `openclaw` - OpenClaw
- `kiro-cli` - Kiro CLI
- `roo` - Roo
- `trae` - Trae
- `trae-cn` - Trae CN
- `opencode` - OpenCode
- `kilo` - Kilo
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 `<cwd>/.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` | `<project>/.claude/skills/` | `~/.claude/skills/` |
| `codex` | `<project>/.codex/skills/` | `~/.codex/skills/` |
| `cursor` | `<project>/.cursor/skills/` | `~/.cursor/skills/` |
| `github-copilot` | `<project>/.github-copilot/skills/` | `~/.github-copilot/skills/` |
| `gemini-cli` | `<project>/.gemini-cli/skills/` | `~/.gemini-cli/skills/` |
| `windsurf` | `<project>/.windsurf/skills/` | `~/.windsurf/skills/` |
| `kiro-cli` | `<project>/.kiro-cli/skills/` | `~/.kiro-cli/skills/` |
| `roo` | `<project>/.roo/skills/` | `~/.roo/skills/` |
| `trae` | `<project>/.trae/skills/` | `~/.trae/skills/` |
| `trae-cn` | `<project>/.trae-cn/skills/` | `~/.trae-cn/skills/` |
| `openhands` | `<project>/.openhands/skills/` | `~/.openhands/skills/` |
| `openclaw` | `<project>/.openclaw/skills/` | `~/.openclaw/skills/` |
| `opencode` | `<project>/.opencode/skills/` | `~/.opencode/skills/` |
| `kilo` | `<project>/.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
```
### Remove Local Skills
### Remove Skills
```bash
# Remove all local installation targets
@ -152,25 +222,56 @@ skillhub remove pdf-parser
# Remove only specific Agent's installation
skillhub remove pdf-parser --agent codex
# Remove remote skill
# 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
```
> 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
skillhub doctor
```
`doctor` scans `.*/skills/<slug>/.skillhub/metadata.json` under the current project and rebuilds `inventory.json`.
`doctor` performs the following operations:
1. Scans `<cwd>/.<agent>/skills/<slug>/.skillhub/metadata.json`
2. Groups by `registry + namespace + slug`
3. Backs up old `inventory.json` (if exists)
4. Writes new `inventory.json`
If the same skill has version conflicts across different targets, that skill will be skipped and reported.
## Publishing
```bash
# 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
```
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
```bash
@ -181,6 +282,72 @@ skillhub update --check
skillhub update
```
Update mechanism:
- Installed via npm globally: Auto-executes `npm install -g skillhub@latest`
- Installed via Bun globally: Auto-executes `bun add -g 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
```
### config.json
```json
{
"registry": "https://skill.xfyun.cn",
"defaultAgent": "codex",
"lastUpdateCheckAt": "2026-04-28T06:00:00.000Z"
}
```
### credentials.json
```json
{
"tokens": {
"https://skill.xfyun.cn": "sk_xxx",
"https://skillhub.example.com": "sk_yyy"
}
}
```
### inventory.json
```json
{
"items": [
{
"registry": "https://skill.xfyun.cn",
"namespace": "global",
"slug": "pdf-parser",
"version": "1.0.0",
"targets": [
{
"agent": "codex",
"rootDir": "/path/to/project/.codex/skills",
"installDir": "/path/to/project/.codex/skills/pdf-parser",
"installedAt": "2026-04-28T06:00:00.000Z"
}
]
}
]
}
```
## JSON Output
All commands support the `--json` parameter for machine-readable JSON output:
@ -189,11 +356,244 @@ All commands support the `--json` parameter for machine-readable JSON output:
skillhub search pdf --json
skillhub list --json
skillhub whoami --json
skillhub install pdf-parser --json
skillhub remove pdf-parser --json
skillhub doctor --json
```
Success response format:
```json
{
"ok": true,
...
}
```
Error response format:
```json
{
"ok": false,
"message": "error message",
"exitCode": 2,
"details": {
"registry": "https://skill.xfyun.cn",
"next": "run `skillhub login`"
}
}
```
## Exit Codes
| Exit Code | Description |
|-----------|-------------|
| 0 | Success |
| 1 | General error |
| 2 | Authentication failure |
| 3 | Network error |
| 4 | File system error |
| 5 | Parameter error |
## Command Reference
### help
```bash
skillhub help
skillhub help install
```
Display help information.
### version
```bash
skillhub version
skillhub version --json
```
Display CLI version.
### login
```bash
skillhub login --token <token> [--registry <url>] [--json]
```
Save token and registry configuration.
### logout
```bash
skillhub logout [--registry <url>] [--json]
```
Remove token for specified registry.
### whoami
```bash
skillhub whoami [--registry <url>] [--token <token>] [--json]
```
Validate current token and display user information.
### search
```bash
skillhub search <query> [--registry <url>] [--limit <n>] [--json]
```
Search published skills.
### install
```bash
skillhub install <slug> [options]
```
Options:
- `--namespace <slug>` — Namespace (default: `global`)
- `--version <v>` — Version (default: latest)
- `--agent <profile>` — Agent profile (repeatable)
- `--dir <path>` — Custom installation directory
- `--force` — Overwrite existing installation
- `--registry <url>` — Registry URL
- `--token <token>` — API token
- `--json` — JSON output
### list
```bash
skillhub list [options]
```
Options:
- `--agent <profile>` — Filter by Agent (repeatable)
- `--dir <path>` — Filter by directory
- `--registry <url>` — Registry URL
- `--json` — JSON output
### remove
```bash
skillhub remove <slug> [options]
```
Options:
- `--agent <profile>` — Filter by Agent (repeatable)
- `--all` — Remove all targets
- `--remote` — Remove remote skill
- `--hard` — Skip remote deletion confirmation
- `--namespace <slug>` — Namespace for remote deletion
- `--registry <url>` — Registry URL
- `--token <token>` — API token
- `--json` — JSON output
### doctor
```bash
skillhub doctor [--json]
```
Scan project directory and rebuild local inventory.
### publish
```bash
skillhub publish <path> [options]
```
Options:
- `--namespace <slug>` — Namespace
- `--visibility <v>` — Visibility (`public` | `namespace-only` | `private`)
- `--registry <url>` — Registry URL
- `--token <token>` — API token
- `--json` — JSON output
### update
```bash
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 set to `0600`
- 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
```
### Network Error
```bash
# Check if registry is accessible
curl https://skill.xfyun.cn/api/cli/v1/skills/search?q=test&limit=1
# Use alternative registry
skillhub search test --registry https://skillhub.example.com
```
### 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
```
## Local Development Verification
If you're developing SkillHub locally, you can verify the CLI like this:
```bash
# 1. Build CLI
cd cli
bun install
bun run build
bun link
# 2. Start local backend
cd ..
make dev-all
# 3. Configure CLI to connect to local service
export SKILLHUB_REGISTRY=http://localhost:8080
# 4. Test commands
skillhub search test
skillhub install example-skill --agent codex
skillhub list
```
## Related Links
- [SkillHub Homepage](https://skill.xfyun.cn)
- [GitHub Repository](https://github.com/iflytek/skillhub)
- [Issue Tracker](https://github.com/iflytek/skillhub/issues)

454
docs/skillhub/guide/cli.md
View file

@ -8,7 +8,7 @@ SkillHub CLI 是 SkillHub 的第一方命令行工具，用于搜索、安装、
# 通过 npm 全局安装
npm install -g skillhub
# 或使用 npx 直接运行
# 或使用 npx 直接运行（无需安装）
npx skillhub@latest version
# 或通过 Bun 全局安装
@ -40,7 +40,7 @@ skillhub publish ./my-skill --namespace myspace
1. `--registry <url>` 命令行参数
2. `SKILLHUB_REGISTRY` 环境变量
3. 用户配置中的 `registry`
3. 用户配置文件 `~/.skillhub/config.json` 中的 `registry` 字段
4. 默认值 `https://skill.xfyun.cn`
```bash
@ -53,6 +53,12 @@ export SKILLHUB_REGISTRY=https://skillhub.example.com
## 认证
Token 按以下优先级解析：
1. `--token <token>` 命令行参数
2. `SKILLHUB_TOKEN` 环境变量
3. `~/.skillhub/credentials.json` 中存储的 token（按 registry 区分）
### 登录
```bash
@ -63,37 +69,53 @@ skillhub login --token sk_xxx
skillhub login --token sk_xxx --registry https://skillhub.example.com
```
Token 只存储在用户目录 `~/.skillhub/credentials.json` 中，不会写入任何项目文件。
`login` 会验证 token 有效性，然后将 token 存储到 `~/.skillhub/credentials.json`，同时将 registry 写入 `~/.skillhub/config.json`。
### 查看当前身份
```bash
skillhub whoami
# 指定 registry 查看
skillhub whoami --registry https://skillhub.example.com
# 临时使用其他 token
skillhub whoami --token sk_other
```
### 登出
```bash
skillhub logout
# 登出指定 registry
skillhub logout --registry https://skillhub.example.com
```
登出只删除 token，保留 registry 配置和安装记录。
登出只删除对应 registry 的 token，保留 registry 配置和安装记录。
## 搜索
```bash
# 关键词搜索
skillhub search pdf
skillhub search "" --limit 20
# 列出所有技能（空字符串查询）
skillhub search "" --limit 50
# JSON 输出
skillhub search pdf --json
```
## 安装
输出格式：`namespace/slug version summary`
## 安装技能
```bash
# 安装到自动探测的 Agent 目录
skillhub install pdf-parser
# 指定 namespace
# 指定 namespace（默认 global）
skillhub install pdf-parser --namespace myspace
# 指定版本
@ -112,38 +134,86 @@ skillhub install pdf-parser --dir ~/.claude/skills
skillhub install pdf-parser --force
```
### 支持的 Agent
### 安装目标解析
内建支持以下 Tier 1 Agent：
CLI 按以下逻辑确定安装位置：
- `claude-code` - Claude Code
- `codex` - Codex
- `cursor` - Cursor
- `github-copilot` - GitHub Copilot
- `gemini-cli` - Gemini CLI
- `openhands` - OpenHands
- `windsurf` - Windsurf
- `openclaw` - OpenClaw
- `kiro-cli` - Kiro CLI
- `roo` - Roo
- `trae` - Trae
- `trae-cn` - Trae CN
- `opencode` - OpenCode
- `kilo` - Kilo
1. 指定 `--dir`：安装到该目录，agent 标记为 `custom`
2. 指定 `--agent`：安装到对应 Agent 的 skills 目录
3. 未指定：自动扫描当前目录，探测已存在的 Agent 配置目录
- 探测到 1 个 Agent → 直接安装
- 探测到多个 Agent → 交互式选择（TTY 模式）或报错（非交互模式）
- 未探测到 → 回退到 `<cwd>/.agents/skills/`
> `--dir` 和 `--agent` 不能同时使用。
### 安装路径
每个 Agent 有项目级和用户级两个 skills 目录：
| Agent | 项目级路径 | 用户级路径 |
|-------|-----------|-----------|
| `claude-code` | `<project>/.claude/skills/` | `~/.claude/skills/` |
| `codex` | `<project>/.codex/skills/` | `~/.codex/skills/` |
| `cursor` | `<project>/.cursor/skills/` | `~/.cursor/skills/` |
| `github-copilot` | `<project>/.github-copilot/skills/` | `~/.github-copilot/skills/` |
| `gemini-cli` | `<project>/.gemini-cli/skills/` | `~/.gemini-cli/skills/` |
| `windsurf` | `<project>/.windsurf/skills/` | `~/.windsurf/skills/` |
| `kiro-cli` | `<project>/.kiro-cli/skills/` | `~/.kiro-cli/skills/` |
| `roo` | `<project>/.roo/skills/` | `~/.roo/skills/` |
| `trae` | `<project>/.trae/skills/` | `~/.trae/skills/` |
| `trae-cn` | `<project>/.trae-cn/skills/` | `~/.trae-cn/skills/` |
| `openhands` | `<project>/.openhands/skills/` | `~/.openhands/skills/` |
| `openclaw` | `<project>/.openclaw/skills/` | `~/.openclaw/skills/` |
| `opencode` | `<project>/.opencode/skills/` | `~/.opencode/skills/` |
| `kilo` | `<project>/.kilo/skills/` | `~/.kilo/skills/` |
对于不在列表中的 Agent，使用 `--dir` 指定安装路径。
### 安装后的文件结构
```
.codex/skills/pdf-parser/
├── ... # 技能包解压后的文件
└── .skillhub/
└── metadata.json # 安装元数据
```
`metadata.json` 内容示例：
```json
{
"registry": "https://skill.xfyun.cn",
"namespace": "global",
"slug": "pdf-parser",
"version": "1.0.0",
"agent": "codex",
"installedAt": "2026-04-28T06:00:00.000Z"
}
```
## 本地管理
### 查看已安装技能
```bash
# 列出所有已安装技能
skillhub list
# 按 Agent 过滤
skillhub list --agent codex
# 按多个 Agent 过滤
skillhub list --agent codex --agent claude-code
# 按目录过滤
skillhub list --dir ~/.codex/skills
# JSON 输出
skillhub list --json
```
### 删除本地技能
### 删除技能
```bash
# 删除所有本地安装目标
@ -152,25 +222,56 @@ skillhub remove pdf-parser
# 只删除指定 Agent 的安装
skillhub remove pdf-parser --agent codex
# 删除远程技能
# 删除所有目标（跳过交互确认）
skillhub remove pdf-parser --all
# 删除远程技能（需要认证，会弹出确认提示）
skillhub remove pdf-parser --remote --namespace myspace
# 跳过远程删除确认
skillhub remove pdf-parser --remote --hard --namespace myspace
```
> 参数互斥规则：
> - `--all` 不能与 `--agent` 同时使用
> - `--remote` 不能与 `--agent` 或 `--all` 同时使用
> - 非交互环境下远程删除必须加 `--hard`
### 重建本地清单
```bash
skillhub doctor
```
`doctor` 扫描当前项目下的 `.*/skills/<slug>/.skillhub/metadata.json`，重建 `inventory.json`。
`doctor` 执行以下操作：
1. 扫描 `<cwd>/.<agent>/skills/<slug>/.skillhub/metadata.json`
2. 按 `registry + namespace + slug` 分组
3. 备份旧的 `inventory.json`（如果存在）
4. 写入新的 `inventory.json`
如果同一技能在不同目标中存在版本冲突，该技能会被跳过并报告。
## 发布
```bash
# 发布目录（自动打包为 zip）
skillhub publish ./my-skill --namespace myspace
# 发布已有的 zip 文件
skillhub publish ./my-skill.zip --namespace myspace
# 指定可见性
skillhub publish ./my-skill --namespace myspace --visibility private
```
可见性选项：
- `public`（默认）— 所有人可见
- `namespace-only` — 仅 namespace 成员可见
- `private` — 仅自己可见
发布成功后会输出技能详情页 URL。
## 自更新
```bash
@ -181,6 +282,72 @@ skillhub update --check
skillhub update
```
更新机制：
- 通过 npm 全局安装：自动执行 `npm install -g skillhub@latest`
- 通过 Bun 全局安装：自动执行 `bun add -g skillhub@latest`
- 通过 npx 运行：提示手动更新命令
- 未知安装方式：提示手动更新
## 环境变量
| 变量 | 说明 | 优先级 |
|------|------|--------|
| `SKILLHUB_REGISTRY` | 默认 registry URL | 低于 `--registry` 参数 |
| `SKILLHUB_TOKEN` | API token | 低于 `--token` 参数，高于存储的 token |
## 本地文件结构
```
~/.skillhub/
├── config.json # 用户配置（registry、defaultAgent 等）
├── credentials.json # API tokens（按 registry 存储，权限 0600）
└── inventory.json # 已安装技能清单
```
### config.json
```json
{
"registry": "https://skill.xfyun.cn",
"defaultAgent": "codex",
"lastUpdateCheckAt": "2026-04-28T06:00:00.000Z"
}
```
### credentials.json
```json
{
"tokens": {
"https://skill.xfyun.cn": "sk_xxx",
"https://skillhub.example.com": "sk_yyy"
}
}
```
### inventory.json
```json
{
"items": [
{
"registry": "https://skill.xfyun.cn",
"namespace": "global",
"slug": "pdf-parser",
"version": "1.0.0",
"targets": [
{
"agent": "codex",
"rootDir": "/path/to/project/.codex/skills",
"installDir": "/path/to/project/.codex/skills/pdf-parser",
"installedAt": "2026-04-28T06:00:00.000Z"
}
]
}
]
}
```
## JSON 输出
所有命令都支持 `--json` 参数，输出机器可读的 JSON 格式：
@ -189,11 +356,244 @@ skillhub update
skillhub search pdf --json
skillhub list --json
skillhub whoami --json
skillhub install pdf-parser --json
skillhub remove pdf-parser --json
skillhub doctor --json
```
成功响应格式：
```json
{
"ok": true,
...
}
```
错误响应格式：
```json
{
"ok": false,
"message": "error message",
"exitCode": 2,
"details": {
"registry": "https://skill.xfyun.cn",
"next": "run `skillhub login`"
}
}
```
## 退出码
| 退出码 | 说明 |
|--------|------|
| 0 | 成功 |
| 1 | 通用错误 |
| 2 | 认证失败 |
| 3 | 网络错误 |
| 4 | 文件系统错误 |
| 5 | 参数错误 |
## 命令参考
### help
```bash
skillhub help
skillhub help install
```
显示帮助信息。
### version
```bash
skillhub version
skillhub version --json
```
显示 CLI 版本。
### login
```bash
skillhub login --token <token> [--registry <url>] [--json]
```
保存 token 和 registry 配置。
### logout
```bash
skillhub logout [--registry <url>] [--json]
```
删除指定 registry 的 token。
### whoami
```bash
skillhub whoami [--registry <url>] [--token <token>] [--json]
```
验证当前 token 并显示用户信息。
### search
```bash
skillhub search <query> [--registry <url>] [--limit <n>] [--json]
```
搜索已发布的技能。
### install
```bash
skillhub install <slug> [options]
```
选项：
- `--namespace <slug>` — namespace（默认 `global`）
- `--version <v>` — 版本（默认最新版本）
- `--agent <profile>` — Agent 配置（可重复）
- `--dir <path>` — 自定义安装目录
- `--force` — 覆盖已存在的安装
- `--registry <url>` — Registry URL
- `--token <token>` — API token
- `--json` — JSON 输出
### list
```bash
skillhub list [options]
```
选项：
- `--agent <profile>` — 按 Agent 过滤（可重复）
- `--dir <path>` — 按目录过滤
- `--registry <url>` — Registry URL
- `--json` — JSON 输出
### remove
```bash
skillhub remove <slug> [options]
```
选项：
- `--agent <profile>` — 按 Agent 过滤（可重复）
- `--all` — 删除所有目标
- `--remote` — 删除远程技能
- `--hard` — 跳过远程删除确认
- `--namespace <slug>` — 远程删除的 namespace
- `--registry <url>` — Registry URL
- `--token <token>` — API token
- `--json` — JSON 输出
### doctor
```bash
skillhub doctor [--json]
```
扫描项目目录，重建本地清单。
### publish
```bash
skillhub publish <path> [options]
```
选项：
- `--namespace <slug>` — Namespace
- `--visibility <v>` — 可见性（`public` | `namespace-only` | `private`）
- `--registry <url>` — Registry URL
- `--token <token>` — API token
- `--json` — JSON 输出
### update
```bash
skillhub update [--check] [--json]
```
检查或执行 CLI 自更新。
## 安全说明
- Token 只存储在用户目录 `~/.skillhub/credentials.json`
- 在 Linux/macOS 上，凭据文件权限设置为 `0600`
- 在 Linux/macOS 上，凭据文件权限自动设置为 `0600`
- 不会将 token 写入任何项目本地文件
- 远程删除操作需要显式确认或 `--hard` 参数
- `remove` 命令会验证路径安全性，防止删除非技能目录
## 故障排查
### 认证失败
```bash
# 验证 token 是否有效
skillhub whoami
# 重新登录
skillhub login --token sk_xxx
```
### 网络错误
```bash
# 检查 registry 是否可访问
curl https://skill.xfyun.cn/api/cli/v1/skills/search?q=test&limit=1
# 使用其他 registry
skillhub search test --registry https://skillhub.example.com
```
### 安装目录冲突
```bash
# 使用 --force 覆盖
skillhub install pdf-parser --force
# 或先删除再安装
skillhub remove pdf-parser
skillhub install pdf-parser
```
### 清单损坏
```bash
# 重建清单
skillhub doctor
```
## 本地开发验证
如果你在本地开发 SkillHub，可以这样验证 CLI：
```bash
# 1. 构建 CLI
cd cli
bun install
bun run build
bun link
# 2. 启动本地后端
cd ..
make dev-all
# 3. 配置 CLI 连接本地服务
export SKILLHUB_REGISTRY=http://localhost:8080
# 4. 测试命令
skillhub search test
skillhub install example-skill --agent codex
skillhub list
```
## 相关链接
- [SkillHub 主页](https://skill.xfyun.cn)
- [GitHub 仓库](https://github.com/iflytek/skillhub)
- [问题反馈](https://github.com/iflytek/skillhub/issues)