diff --git a/docs/skillhub/en/guide/cli.md b/docs/skillhub/en/guide/cli.md
index f6fe2b49..9e1345da 100644
--- a/docs/skillhub/en/guide/cli.md
+++ b/docs/skillhub/en/guide/cli.md
@@ -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)
diff --git a/docs/skillhub/guide/cli.md b/docs/skillhub/guide/cli.md
index 098e8c06..244995b1 100644
--- a/docs/skillhub/guide/cli.md
+++ b/docs/skillhub/guide/cli.md
@@ -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)