From 64894e750306b90389e9f137c2057e3813d84331 Mon Sep 17 00:00:00 2001 From: zzgosh <30567623+zzgosh@users.noreply.github.com> Date: Thu, 19 Mar 2026 23:52:37 +0800 Subject: [PATCH] docs: improve agent and CLI help docs --- README.md | 26 ++++++------- docs/README.zh-CN.md | 26 ++++++------- src/cli.ts | 93 ++++++++++++++++++++++++++++++++++++++++++++ 3 files changed, 119 insertions(+), 26 deletions(-) diff --git a/README.md b/README.md index 9b2ba87..51b8345 100644 --- a/README.md +++ b/README.md @@ -74,7 +74,7 @@ Options: | Option | Description | |------|------| | `-g, --global` | Install globally and symlink to detected agent clients | -| `-a, --agent ` | Link to a specific agent client instead of relying on auto-detection | +| `-a, --agent ` | 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 ` is provided, the CLI links the selected agent directly. diff --git a/docs/README.zh-CN.md b/docs/README.zh-CN.md index 9b76f5c..5a88e13 100644 --- a/docs/README.zh-CN.md +++ b/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 ` | 定向安装到指定 agent，而不是依赖自动检测 | +| `-a, --agent ` | 定向安装到指定 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 `，CLI 会直接为该 agent 建立链接。 diff --git a/src/cli.ts b/src/cli.ts index 7853b7d..38a28ba 100644 --- a/src/cli.ts +++ b/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,6 +9,7 @@ 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() @@ -15,6 +17,23 @@ 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 --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 ', '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,12 +71,39 @@ 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 @@ -44,12 +111,38 @@ program .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()