docs: improve agent and CLI help docs

README.md

@@ -74,7 +74,7 @@ Options:
 | Option | Description |
 |------|------|
 | `-g, --global` | Install globally and symlink to detected agent clients |
-| `-a, --agent <name>` | Link to a specific agent client instead of relying on auto-detection |
+| `-a, --agent <name>` | Link to a specific agent client instead of relying on auto-detection. See Supported Agent Clients for valid values. |
 | `-y, --yes` | Skip confirmation and automatically back up then overwrite existing files |
 
 ### `agent-specs update`
@@ -150,18 +150,18 @@ agent-specs remove -g -y
 
 ## Supported Agent Clients
 
-| Agent | Detection Directory | Symlink Target | Filename |
-|-------|---------|-------------|--------|
-| Claude Code | `~/.claude/` | `~/.claude/CLAUDE.md` | `CLAUDE.md` |
-| Gemini CLI | `~/.gemini/` | `~/.gemini/GEMINI.md` | `GEMINI.md` |
-| Codex (OpenAI) | `~/.codex/` | `~/.codex/AGENTS.md` | `AGENTS.md` |
-| Amp | `~/.config/amp/` | `~/.config/amp/AGENTS.md` | `AGENTS.md` |
-| OpenCode | `~/.config/opencode/` | `~/.config/opencode/AGENTS.md` | `AGENTS.md` |
-| Qwen Code | `~/.qwen/` | `~/.qwen/QWEN.md` | `QWEN.md` |
-| Roo Code | `~/.roo/` | `~/.roo/rules/AGENTS.md` | `AGENTS.md` |
-| Continue | `~/.continue/` | `~/.continue/rules/AGENTS.md` | `AGENTS.md` |
-| Augment | `~/.augment/` | `~/.augment/rules/AGENTS.md` | `AGENTS.md` |
-| Kiro | `~/.kiro/` | `~/.kiro/steering/AGENTS.md` | `AGENTS.md` |
+| Agent | `--agent` | Detection Directory | Symlink Target | Filename |
+|-------|-----------|---------------------|----------------|----------|
+| Claude Code | `claude-code` | `~/.claude/` | `~/.claude/CLAUDE.md` | `CLAUDE.md` |
+| Gemini CLI | `gemini-cli` | `~/.gemini/` | `~/.gemini/GEMINI.md` | `GEMINI.md` |
+| Codex (OpenAI) | `codex` | `~/.codex/` | `~/.codex/AGENTS.md` | `AGENTS.md` |
+| Amp | `amp` | `~/.config/amp/` | `~/.config/amp/AGENTS.md` | `AGENTS.md` |
+| OpenCode | `opencode` | `~/.config/opencode/` | `~/.config/opencode/AGENTS.md` | `AGENTS.md` |
+| Qwen Code | `qwen-code` | `~/.qwen/` | `~/.qwen/QWEN.md` | `QWEN.md` |
+| Roo Code | `roo-code` | `~/.roo/` | `~/.roo/rules/AGENTS.md` | `AGENTS.md` |
+| Continue | `continue` | `~/.continue/` | `~/.continue/rules/AGENTS.md` | `AGENTS.md` |
+| Augment | `augment` | `~/.augment/` | `~/.augment/rules/AGENTS.md` | `AGENTS.md` |
+| Kiro | `kiro` | `~/.kiro/` | `~/.kiro/steering/AGENTS.md` | `AGENTS.md` |
 
 The CLI only creates symlinks for agent clients that are actually detected on the machine.
 When `-a, --agent <name>` is provided, the CLI links the selected agent directly.

docs/README.zh-CN.md

@@ -74,7 +74,7 @@ agent-specs add https://github.com/vercel-labs/agent-skills/blob/main/AGENTS.md
 | 选项 | 说明 |
 |------|------|
 | `-g, --global` | 全局安装，并 symlink 到各 agent 客户端 |
-| `-a, --agent <name>` | 定向安装到指定 agent，而不是依赖自动检测 |
+| `-a, --agent <name>` | 定向安装到指定 agent，而不是依赖自动检测。可用值见“支持的 Agent 客户端” |
 | `-y, --yes` | 跳过确认，自动备份并覆盖已有文件 |
 
 ### `agent-specs update`
@@ -150,18 +150,18 @@ agent-specs remove -g -y
 
 ## 支持的 Agent 客户端
 
-| Agent | 检测目录 | Symlink 目标 | 文件名 |
-|-------|---------|-------------|--------|
-| Claude Code | `~/.claude/` | `~/.claude/CLAUDE.md` | `CLAUDE.md` |
-| Gemini CLI | `~/.gemini/` | `~/.gemini/GEMINI.md` | `GEMINI.md` |
-| Codex (OpenAI) | `~/.codex/` | `~/.codex/AGENTS.md` | `AGENTS.md` |
-| Amp | `~/.config/amp/` | `~/.config/amp/AGENTS.md` | `AGENTS.md` |
-| OpenCode | `~/.config/opencode/` | `~/.config/opencode/AGENTS.md` | `AGENTS.md` |
-| Qwen Code | `~/.qwen/` | `~/.qwen/QWEN.md` | `QWEN.md` |
-| Roo Code | `~/.roo/` | `~/.roo/rules/AGENTS.md` | `AGENTS.md` |
-| Continue | `~/.continue/` | `~/.continue/rules/AGENTS.md` | `AGENTS.md` |
-| Augment | `~/.augment/` | `~/.augment/rules/AGENTS.md` | `AGENTS.md` |
-| Kiro | `~/.kiro/` | `~/.kiro/steering/AGENTS.md` | `AGENTS.md` |
+| Agent | `--agent` | 检测目录 | Symlink 目标 | 文件名 |
+|-------|-----------|----------|-------------|--------|
+| Claude Code | `claude-code` | `~/.claude/` | `~/.claude/CLAUDE.md` | `CLAUDE.md` |
+| Gemini CLI | `gemini-cli` | `~/.gemini/` | `~/.gemini/GEMINI.md` | `GEMINI.md` |
+| Codex (OpenAI) | `codex` | `~/.codex/` | `~/.codex/AGENTS.md` | `AGENTS.md` |
+| Amp | `amp` | `~/.config/amp/` | `~/.config/amp/AGENTS.md` | `AGENTS.md` |
+| OpenCode | `opencode` | `~/.config/opencode/` | `~/.config/opencode/AGENTS.md` | `AGENTS.md` |
+| Qwen Code | `qwen-code` | `~/.qwen/` | `~/.qwen/QWEN.md` | `QWEN.md` |
+| Roo Code | `roo-code` | `~/.roo/` | `~/.roo/rules/AGENTS.md` | `AGENTS.md` |
+| Continue | `continue` | `~/.continue/` | `~/.continue/rules/AGENTS.md` | `AGENTS.md` |
+| Augment | `augment` | `~/.augment/` | `~/.augment/rules/AGENTS.md` | `AGENTS.md` |
+| Kiro | `kiro` | `~/.kiro/` | `~/.kiro/steering/AGENTS.md` | `AGENTS.md` |
 
 CLI 只会为检测到已安装的 agent 创建 symlink。
 如果显式传入 `-a, --agent <name>`，CLI 会直接为该 agent 建立链接。

src/cli.ts

@@ -1,5 +1,6 @@
 import { createRequire } from 'node:module'
 import { Command } from 'commander'
+import { SUPPORTED_AGENTS } from './agents.ts'
 import { addCommand } from './commands/add.ts'
 import { removeCommand } from './commands/remove.ts'
 import { updateCommand } from './commands/update.ts'
@@ -8,13 +9,31 @@ import { linkCommand } from './commands/link.ts'
 
 const require = createRequire(import.meta.url)
 const pkg = require('../package.json')
+const supportedAgentNames = SUPPORTED_AGENTS.map((agent) => agent.name).join(', ')
 
 const program = new Command()
 
 program
   .name('agent-specs')
   .description('CLI for managing AGENTS.md files')
   .version(pkg.version)
+  .showHelpAfterError()
+  .addHelpText(
+    'after',
+    `
+Install modes:
+  Project mode (default): writes ./AGENTS.md in the current directory
+  Global mode (-g): writes ~/.agents/AGENTS.md and links detected agent clients
+
+Examples:
+  $ agent-specs add https://github.com/vercel-labs/agent-skills/blob/main/AGENTS.md
+  $ agent-specs add ./AGENTS.md -a claude-code
+  $ agent-specs add ./AGENTS.md -g -a codex
+  $ agent-specs list -g
+
+Run "agent-specs <command> --help" for command-specific help.
+`,
+  )
 
 program
   .command('add')
@@ -23,6 +42,27 @@ program
   .option('-g, --global', 'Install globally (~/.agents/) and symlink to detected agent clients')
   .option('-a, --agent <name>', 'Link to a specific agent client')
   .option('-y, --yes', 'Skip confirmation and overwrite existing files')
+  .addHelpText(
+    'after',
+    `
+Notes:
+  Project mode: writes ./AGENTS.md and optionally links one project agent path with -a
+  Global mode: writes ~/.agents/AGENTS.md and links detected agent clients
+  Use -a to bypass auto-detection and target one agent directly
+
+Supported source formats:
+  GitHub blob URL, short GitHub URL, raw URL, any URL, local path, file:// URL
+
+Examples:
+  $ agent-specs add ./AGENTS.md
+  $ agent-specs add ./AGENTS.md -a claude-code
+  $ agent-specs add https://example.com/AGENTS.md -g
+  $ agent-specs add ./AGENTS.md -g -a codex
+
+Supported --agent values:
+  ${supportedAgentNames}
+`,
+  )
   .action(addCommand)
 
 program
@@ -31,25 +71,78 @@ program
   .description('Remove installed AGENTS.md files and related symlinks')
   .option('-g, --global', 'Remove the global installation')
   .option('-y, --yes', 'Skip confirmation prompts')
+  .addHelpText(
+    'after',
+    `
+Notes:
+  Project mode: removes ./AGENTS.md and any project agent symlinks created by this CLI
+  Global mode (-g): removes ~/.agents/AGENTS.md and related global symlinks
+  If the install reused an existing AGENTS.md as the source of truth, that file is preserved
+
+Examples:
+  $ agent-specs remove
+  $ agent-specs remove -g
+  $ agent-specs rm -g -y
+`,
+  )
   .action(removeCommand)
 
 program
   .command('update')
   .description('Re-fetch and update AGENTS.md from its original source')
   .option('-g, --global', 'Update the global installation')
+  .addHelpText(
+    'after',
+    `
+Notes:
+  Re-fetches content from the original source recorded during install
+  Project mode updates ./AGENTS.md
+  Global mode (-g) updates ~/.agents/AGENTS.md without recreating symlinks
+
+Examples:
+  $ agent-specs update
+  $ agent-specs update -g
+`,
+  )
   .action(updateCommand)
 
 program
   .command('list')
   .alias('ls')
   .description('Show installation and symlink status')
   .option('-g, --global', 'Show global installation status')
+  .addHelpText(
+    'after',
+    `
+Notes:
+  Project mode shows ./AGENTS.md plus project agent symlink status
+  Global mode (-g) shows ~/.agents/AGENTS.md plus detected or configured global agent links
+
+Examples:
+  $ agent-specs list
+  $ agent-specs list -g
+  $ agent-specs ls -g
+`,
+  )
   .action(listCommand)
 
 program
   .command('link')
   .description('Detect agent clients and recreate symlinks (requires a global install)')
   .option('-y, --yes', 'Automatically handle conflicting files')
+  .addHelpText(
+    'after',
+    `
+Notes:
+  Requires an existing global install in ~/.agents/AGENTS.md
+  Re-runs agent detection and recreates missing global symlinks
+  Useful after installing a new agent client
+
+Examples:
+  $ agent-specs link
+  $ agent-specs link -y
+`,
+  )
   .action(linkCommand)
 
 program.parse()