Claude Code 工作流中的命令實現(xiàn)與自定義指南

本文基于 claude-code-rev 源碼分析 Claude Code 工作流中的命令系統(tǒng)：命令從哪里加載、如何被識別、如何執(zhí)行、能否自定義、如何編寫自定義命令/技能，以及這些命令與模型、工具權限、插件、工作流和 hooks 的關系。

結論先行：Claude Code 的命令可以自定義。最推薦的方式是寫 Markdown 形式的命令或技能；更深度的交互式命令需要插件或源碼級 local / local-jsx 實現(xiàn)；工作流命令和 MCP skill 也能進入命令系統(tǒng)，但它們依賴對應特性或外部服務。

0. 整體流程圖

命令工作流可以拆成四層：

0. 命令來源：內(nèi)置命令、.claude/skills、舊版 .claude/commands、插件、工作流；MCP skills 走獨立的 MCP 命令集合。
1. 加載過濾：loadAllCommands(cwd) 合并本地/插件/工作流來源，getCommands(cwd) 按可用性、開關和動態(tài)技能過濾。
2. 用戶輸入解析：用戶輸入 /command args 后，processSlashCommand(...) 解析命令名和參數(shù)，并從當前命令表中查找命令。
3. 執(zhí)行分支：根據(jù) Command.type 進入 prompt、local、local-jsx，其中 prompt 命令還可以通過 context: fork 進入子代理執(zhí)行；MCP skills 主要通過單獨篩選后進入模型可調用技能集合。

1. 命令的核心類型

源碼中的命令統(tǒng)一抽象為 Command，定義在 src/types/command.ts。它由公共字段 CommandBase 加上三種執(zhí)行形態(tài)之一組成。

關鍵字段：

2. 命令從哪里來

src/commands.ts 是命令聚合入口。內(nèi)置命令由 COMMANDS() 返回，技能、插件和工作流再由 loadAllCommands(cwd) 合并。

2.1 來源總表

2.2 合并順序

loadAllCommands(cwd) 的合并順序是：

return [
 ?...bundledSkills,
 ?...builtinPluginSkills,
 ?...skillDirCommands,
 ?...workflowCommands,
 ?...pluginCommands,
 ?...pluginSkills,
 ?...COMMANDS(),
]

這意味著命令列表中，技能和插件命令會出現(xiàn)在內(nèi)置命令之前。運行時查找由 findCommand(...) 按數(shù)組順序返回第一個匹配項，因此同名命令可能受到加載順序影響。實踐中建議自定義命令避免與內(nèi)置命令重名。

2.3 過濾邏輯

getCommands(cwd) 會在合并后做兩類過濾：

3. Markdown 命令和技能如何加載

自定義命令最重要的入口在 src/skills/loadSkillsDir.ts 和 src/utils/markdownConfigLoader.ts。

3.1 推薦目錄：.claude/skills

技能目錄只支持這一種結構：

.claude/
  skills/
 ?  my-skill/
 ? ?  SKILL.md

my-skill 會成為命令名，用戶可以輸入：

/my-skill 參數(shù)

如果放在用戶目錄，則是：

~/.claude/
  skills/
 ?  my-skill/
 ? ?  SKILL.md

3.2 舊版目錄：.claude/commands

舊版命令目錄仍被支持：

.claude/
  commands/
 ?  review.md
 ?  git/
 ? ?  pr.md
 ?  deploy/
 ? ?  SKILL.md

命名規(guī)則：

源碼中 buildNamespace(...) 會把子目錄轉換成冒號命名空間。

3.3 加載范圍和優(yōu)先級

loadMarkdownFilesForSubdir(...) 會加載三類位置：

Markdown 文件加載組合順序是 managed > user > project。文件層面會按真實文件 identity 去重，技能層面也會按 realpath 去重，順序靠前者保留。

項目目錄向上查找會在 git root 停止，避免父目錄的 .claude/commands 或 .claude/skills 意外泄露進無關倉庫。worktree 場景下，如果 worktree 缺少 .claude/<subdir>，會回退到主倉庫對應目錄。

4. Frontmatter 字段參考

Markdown 命令/技能通過 YAML frontmatter 定義元數(shù)據(jù)。字段解析主要在 src/utils/frontmatterParser.ts 和 src/skills/loadSkillsDir.ts。

4.1 常用字段

4.2 最小自定義技能示例

---
description: 生成當前改動的代碼審查清單
argument-hint: "[重點區(qū)域]"
when_to_use: 用戶希望快速審查當前分支或工作區(qū)改動時
---
?
請審查當前倉庫的改動，重點關注：$ARGUMENTS。
?
輸出：
1. 高風險問題
2. 可維護性問題
3. 建議補充的測試
4. 可以直接合并的理由或阻塞項

放到：

.claude/skills/review-changes/SKILL.md

調用：

/review-changes auth 模塊

4.3 帶命名參數(shù)的示例

---
description: 根據(jù) issue 編號生成修復計劃
argument-hint: "<issue> <scope>"
arguments:
  - issue
  - scope
---

請為 issue $issue 生成修復計劃。

范圍：$scope

要求：
- 先定位相關文件
- 說明風險
- 給出測試計劃

命令內(nèi)容最終會通過 substituteArguments(...) 替換參數(shù)。

4.4 只能由 Claude 調用的技能

---
description: 安全審計技能
when_to_use: 當任務涉及認證、權限、外部輸入、密鑰或命令執(zhí)行時使用
user-invocable: false
---
對當前任務做安全審計，重點檢查注入、權限繞過、敏感信息泄露和不安全默認值。

用戶直接輸入 /security-audit 時會收到提示：該技能只能由 Claude 調用。用戶可以說“請使用 security-audit 技能”。

4.5 fork 子代理技能

---
description: 在獨立上下文中做大型代碼審查
when_to_use: 當改動跨多個模塊，需要獨立上下文審查時使用
context: fork
agent: code-reviewer
effort: high
---
請審查當前分支的代碼改動，輸出關鍵問題和建議。

執(zhí)行時不會把技能正文簡單塞進當前對話，而是走 executeForkedSlashCommand(...)，調用 runAgent(...) 在子代理中執(zhí)行。

4.6 帶 hooks 的技能

---
description: 編輯 TypeScript 后自動檢查
hooks:
  PostToolUse:
    - matcher: "Write|Edit|MultiEdit"
      hooks:
        - type: command
          command: "npm run typecheck"
          timeout: 60
---
請實現(xiàn)用戶請求，并在修改 TypeScript 文件后自動觸發(fā)類型檢查。

源碼中 getMessagesForPromptSlashCommand(...) 會在命令帶有 hooks 時調用 registerSkillHooks(...)，這些 hook 以會話級方式注冊。

5. 用戶輸入/command后發(fā)生什么

src/utils/processUserInput/processSlashCommand.tsx 負責 slash command 的運行時處理。

5.1 解析與查找

流程如下：

findCommand(...) 的匹配邏輯是：

_.name === commandName ||
getCommandName(_) === commandName ||
_.aliases?.includes(commandName)

5.2 prompt命令執(zhí)行

普通 prompt 命令會：

0. 調用 command.getPromptForCommand(args, context) 生成內(nèi)容塊。
1. 注冊技能 hooks（如果 frontmatter 中定義了 hooks）。
2. 解析 allowedTools，把額外工具權限傳給后續(xù)模型處理。
3. 創(chuàng)建用戶消息，通常設置 shouldQuery: true，讓 Claude 接著處理。

Markdown 技能的 getPromptForCommand(...) 還會做這些替換/處理：

5.3 context: fork的執(zhí)行

當 PromptCommand.context === 'fork' 時，流程進入 executeForkedSlashCommand(...)：

在 KAIROS/assistant 模式下，fork 命令還可能以后臺方式運行，完成后把結果重新放回消息隊列。

5.4 local命令執(zhí)行

local 命令是源碼或插件中的 JS/TS 模塊。執(zhí)行邏輯：

先構造用戶輸入消息。

await command.load() 懶加載模塊。

調用 mod.call(args, context)。

根據(jù)返回結果處理：

• { type: 'skip' }：不寫消息，不繼續(xù)查詢。
• { type: 'text', value }：輸出 <local-command-stdout>。
• { type: 'compact', compactionResult }：進入上下文壓縮后的消息構造流程。

5.5 local-jsx命令執(zhí)行

local-jsx 命令適合交互 UI，例如選擇器、設置面板。執(zhí)行邏輯：

command.load() 懶加載 JSX 模塊。

調用 mod.call(onDone, context, args)。

返回 React 節(jié)點后通過 setToolJSX(...) 渲染。

UI 完成后調用 onDone(result, options)。

options 可控制：

• display: 'skip' | 'system' | 'user'
• shouldQuery
• metaMessages
• nextInput
• submitNextInput

6. 命令是否可以自定義

可以，但不同層級能力不同。

7. 自定義命令實戰(zhàn)模板

7.1 項目級命令：生成 PR 描述

文件：.claude/skills/pr-description/SKILL.md

---
description: 根據(jù)當前分支生成 PR 描述
argument-hint: "[目標分支]"
when_to_use: 用戶準備創(chuàng)建 pull request 或需要總結當前分支改動時
allowed-tools:
  - Bash(git status:*)
  - Bash(git diff:*)
  - Bash(git log:*)
---
請基于當前分支相對 $ARGUMENTS 的改動生成 PR 描述。
要求：
- 標題不超過 70 字符
- Summary 使用 1-3 個 bullet
- Test plan 使用 checklist
- 明確指出未驗證項

調用：

/pr-description main

7.2 只能模型調用的領域技能

文件：.claude/skills/db-review/SKILL.md

---
description: 數(shù)據(jù)庫變更審查
when_to_use: 當任務涉及 SQL、migration、索引、事務或數(shù)據(jù)庫性能時使用
disable-model-invocation: false
user-invocable: false
---

請審查數(shù)據(jù)庫相關改動，重點檢查：
- migration 是否可回滾
- 大表 DDL 是否會長時間鎖表
- 查詢是否有合適索引
- 是否存在 SQL 注入風險

用戶不能直接 /db-review，但可以要求 Claude 使用該技能。

7.3 按路徑激活的條件技能

---
description: React 組件審查
when_to_use: 當修改 React/TSX 文件時檢查組件結構和狀態(tài)管理
paths:
  - "src/**/*.tsx"
  - "app/**/*.tsx"
---

當用戶修改 React 組件時，檢查 props 類型、狀態(tài)管理、副作用和可訪問性。

帶 paths 的技能會先進入 conditional skill 存儲，只有匹配路徑被觸達后才激活。

8. 命令和 SkillTool 的關系

Claude Code 把很多 prompt 型命令也暴露給模型作為 SkillTool 可調用能力。

影響模型是否可調用的關鍵字段：

8.1 Skill 變成命令的完整流程

從 Markdown skill 文件到可執(zhí)行命令，經(jīng)歷以下階段：

8.1.1 加載階段：Markdown → PromptCommand

.claude/skills/example.md
    ↓ loadSkillsDir.ts 讀取文件
    ↓ parseMarkdown() 解析 frontmatter + body
    ↓ 構建 PromptCommand 對象
{
  type: 'prompt',
  path: '/path/to/example.md',
  prompt: 'body 內(nèi)容',
  allowedTools: frontmatter.allowed-tools,
  ...
}

源碼位置：src/skills/loadSkillsDir.ts 的 getPromptForCommand() (344-405行)

8.1.2 用戶輸入/skill-name執(zhí)行路徑

用戶輸入: /example arg1 arg2
    ↓ processSlashCommand.tsx 檢測 "/" 開頭
    ↓ findMatchingCommand() 查找匹配的命令
    ↓ getMessagesForPromptSlashCommand() 生成消息
    ↓ getPromptForCommand() 處理 prompt 內(nèi)容
    ↓ 返回 { messages, allowedTools, hooks }

關鍵函數(shù)：src/utils/processUserInput/processSlashCommand.tsx 第827行

8.1.3 getPromptForCommand() 詳細處理步驟

8.1.4 SkillTool 調用路徑

模型通過 SkillTool 調用 skill 時：

模型輸出: Skill({ skill: "example", args: "arg1" })
    ↓ SkillTool.ts call() 函數(shù) (580-841行)
    ↓ 判斷 context: inline 還是 fork
    ↓ inline: 直接返回 prompt 消息
    ↓ fork: 啟動子 Agent 執(zhí)行

8.1.5 Inline vs Fork 執(zhí)行流程對比

8.1.6 關鍵源碼位置表

9. 命令和權限的關系

命令系統(tǒng)本身不等同于工具權限系統(tǒng)，但它會影響后續(xù)模型或內(nèi)聯(lián) shell 的權限邊界。

9.1allowed-tools

Markdown 命令 frontmatter 的 allowed-tools 會被解析為工具列表。對于 prompt 命令：

• 會傳到 slash command 結果的 allowedTools。
• 在 Markdown 內(nèi)聯(lián) shell 執(zhí)行時，會被寫入 alwaysAllowRules.command，讓該命令內(nèi)部的 shell 片段按命令級 allowlist 執(zhí)行。

9.2 MCP 技能的限制

MCP skills 被視為遠端/不可信來源，源碼中明確禁止執(zhí)行其 Markdown 正文里的內(nèi)聯(lián) shell 片段。也就是說：

9.3 Remote / Bridge 模式限制

src/commands.ts 中還有遠程模式限制：

10. 與 hooks 的關系

命令和 hooks 是兩套機制，但可以互相連接：

建議：

11. 源碼級原理說明

11.1 加載原理

getCommands(cwd) 是命令表入口。它先調用 memoized 的 loadAllCommands(cwd)，再做可用性過濾和動態(tài)技能插入。

核心鏈路：

getCommands(cwd)
  └─ loadAllCommands(cwd)
      ├─ getSkills(cwd)
      │   ├─ getSkillDirCommands(cwd)
      │   ├─ getPluginSkills()
      │   ├─ getBundledSkills()
      │   └─ getBuiltinPluginSkillCommands()
      ├─ getPluginCommands()
      ├─ getWorkflowCommands(cwd)
      └─ COMMANDS()

getSkillDirCommands(cwd) 又會加載：

managed .claude/skills
user ~/.claude/skills
project .claude/skills
additional --add-dir .claude/skills
legacy .claude/commands

11.2 Markdown 轉 Command 的原理

SKILL.md 或舊版 .md 文件會經(jīng)歷：

讀取 Markdown
  → parseFrontmatter(...)
  → parseSkillFrontmatterFields(...)
  → createSkillCommand(...)
  → 返回 type: 'prompt' 的 Command

createSkillCommand(...) 生成的命令固定是 type: 'prompt'。因此 Markdown 自定義命令不是直接執(zhí)行 JS 函數(shù)，而是生成一段 prompt 內(nèi)容，讓 Claude Code 把它作為用戶消息或子代理任務處理。

11.3 執(zhí)行原理

用戶輸入 /name args 后：

processSlashCommand(...)
  → parseSlashCommand(...)
  → hasCommand(...)
  → getMessagesForSlashCommand(...)
  → getCommand(...)
  → switch command.type
      ├─ local-jsx: load().call(onDone, context, args)
      ├─ local: load().call(args, context)
      └─ prompt:
          ├─ context === 'fork' → executeForkedSlashCommand(...)
          └─ inline → getMessagesForPromptSlashCommand(...)

11.4 為什么 Markdown 命令不能直接做任意 UI

Markdown 命令最終被轉成 PromptCommand。它只有 getPromptForCommand(...)，不能直接返回 React 節(jié)點，也不能直接實現(xiàn) onDone 交互流程。需要交互 UI 的命令必須是 local-jsx，也就是源碼或插件代碼提供的命令。

11.5 為什么自定義命令推薦寫成 skills

skills 目錄是當前更完整的能力模型：

• 支持 SKILL.md 目錄結構和技能資源文件。
• 支持 ${CLAUDE_SKILL_DIR} 引用技能目錄。
• 支持 paths 條件激活。
• 支持 when_to_use 給模型選擇技能。
• 支持 context: fork 啟動子代理。
• 支持技能級 hooks。

舊版 .claude/commands 仍能用，但源碼中標記為 commands_DEPRECATED，適合兼容，不建議作為新設計的首選。

12. 使用建議與最佳實踐

13. 常見問題

13.1/commands和/skills有什么區(qū)別

.claude/commands 是舊版 Markdown 命令目錄；.claude/skills 是更完整的技能目錄。兩者最終都會被轉成 type: 'prompt' 的 Command，但 skills 支持更明確的目錄結構、資源引用、條件激活和模型技能語義。

13.2 自定義命令能覆蓋內(nèi)置命令嗎

命令合并時自定義技能在內(nèi)置命令之前，查找時返回第一個匹配項，因此同名有可能影響解析結果。但不建議依賴覆蓋行為，最好避免與內(nèi)置命令重名。

13.3 Markdown 命令能直接執(zhí)行 shell 嗎

可以使用 Markdown 內(nèi)聯(lián) shell 片段，但要受權限和 allowed-tools 影響。MCP skills 不會執(zhí)行內(nèi)聯(lián) shell。涉及危險操作時，建議用 hooks 做強制約束。

13.4user-invocable: false是什么效果

用戶不能直接輸入 /skill-name 調用；如果模型可調用未禁用，Claude 仍可通過 SkillTool 使用它。

13.5context: fork和普通命令區(qū)別是什么

普通 prompt 命令會把內(nèi)容加入當前對話；context: fork 會啟動子代理在獨立上下文中執(zhí)行，最終把結果返回給主流程。

13.6 命令會自動出現(xiàn)在模型可用技能里嗎

不一定。模型可調用技能通常要求是 prompt 類型、不是 builtin、沒有 disableModelInvocation，并且有合適的 description 或 when_to_use。插件/MCP 類技能對顯式描述要求更高。

14. 關鍵源碼位置

15. 快速決策表

以上就是Claude Code工作流中的命令實現(xiàn)與自定義指南的詳細內(nèi)容，更多關于Claude Code工作流命令的資料請關注腳本之家其它相關文章！

最新評論