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 <url>` 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 <url>]` - Authenticate with a SkillHub registry
-- `skillhub logout [--registry <url>]` - Remove stored credentials
+1. `--token <token>` command-line argument
+2. `SKILLHUB_TOKEN` environment variable
+3. Token stored in `~/.skillhub/credentials.json` (per registry)
 
-### 🎯 Skill Management
-
-- `skillhub search <query>` - Search for skills in the registry
-- `skillhub install <skill-name>` - Install a skill to ~/.claude/skills/
-- `skillhub uninstall <skill-name>` - Remove an installed skill
-- `skillhub list` - List all installed skills
-- `skillhub info <skill-name>` - 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 `<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
 ```
 
-### 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 `<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`
 
-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 <token> [--registry <url>] [--json]` | Save token and registry configuration |
+| `skillhub logout [--registry <url>] [--json]` | Remove token for specified registry |
+| `skillhub whoami [--registry <url>] [--token <token>] [--json]` | Validate current token and display user information |
+| `skillhub search <query> [--registry <url>] [--limit <n>] [--json]` | Search published skills |
+| `skillhub install <slug> [--namespace <slug>] [--version <v>] [--agent <profile>] [--dir <path>] [--force] [--registry <url>] [--token <token>] [--json]` | Install a skill |
+| `skillhub list [--agent <profile>] [--dir <path>] [--registry <url>] [--json]` | List installed skills |
+| `skillhub remove <slug> [--agent <profile>] [--all] [--remote] [--hard] [--namespace <slug>] [--registry <url>] [--token <token>] [--json]` | Remove a skill |
+| `skillhub doctor [--json]` | Scan project directory and rebuild local inventory |
+| `skillhub publish <path> [--namespace <slug>] [--visibility <v>] [--registry <url>] [--token <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 <url>` 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.