agent-skills 接入 Command Code：用 cmd skills 原生安装、管理与发现 25 个工程技能

本文讲解如何在 Command Code 中通过其内置的 cmd skills 命令原生安装、管理和使用 agent-skills 技能包：从项目级/用户级两种安装作用域、单技能挑选与分支指定，到 TUI 斜杠菜单中的自动发现机制，以及技能存放路径的完整解析规则。读完本文，你可以在任意项目中一键接入这套 25 个生产级工程技能，并理解 Command Code 是如何递归发现 SKILL.md 文件并完成技能装载的。

Command Code 原生技能系统的工作原理

Command Code 自带一套原生技能（skills）系统，核心是内置的 cmd skills 命令。它的工作流程是：

1. 克隆你指定的 GitHub 仓库；
2. 递归发现仓库中的每一个 SKILL.md 文件；
3. 交互式地让你勾选要安装的技能，并写入对应的技能目录。

Command Code 的可执行文件名为 cmd，在 Windows 上的别名为 cmdc，另有 command-code 别名。下文示例统一使用 cmd。

这套机制能直接对接 agent-skills 仓库，正是因为仓库的每个技能都遵循「一个目录 + 一份 SKILL.md」的标准结构。仓库的 skills/ 目录当前共有 25 个技能目录，例如 skills/spec-driven-development/SKILL.md、skills/interview-me/SKILL.md、skills/using-agent-skills/SKILL.md 等。递归扫描 SKILL.md 恰好能完整覆盖这些技能，而每个目录下的可选支撑文件（如 skills/idea-refine/frameworks.md、skills/idea-refine/scripts/idea-refine.sh）也随目录整体安装。

SKILL.md 本身以 YAML frontmatter 开头，这是 Command Code 识别与展示技能的关键：

---
name: spec-driven-development
description: Creates specs before coding. Use when starting a new project,
  feature, or significant change and no specification exists yet. …
---

frontmatter 中 name 必须与技能目录名一致（小写连字符命名），description 需要同时说明技能「做什么」和「何时触发」（"Use when…"）。这一点在仓库的格式规范 docs/skill-anatomy.md 中有明确定义：Agent 靠 description 决定何时激活某个技能，而 TUI 斜杠菜单里显示的提示文本也正是来自这里。仓库还通过 scripts/validate-skills.js 对每个技能做 lint 校验（规则集中在 scripts/lib/skill-lint.js），保证技能包在安装到任意 Agent 之前结构合法——这保证了 cmd skills 递归发现到的每一份 SKILL.md 都是可被正确解析的。

安装技能

项目级安装（默认作用域）

在项目根目录执行：

cmd skills add addyosmani/agent-skills

技能会安装到当前 git 仓库根目录下的 .commandcode/skills/。在交互式终端中，命令会弹出一个多选界面，让你从发现的 25 个技能中勾选要安装的子集；如果通过管道或以非交互方式调用，则安装所有被发现的技能。

安装指定技能

只想要某一个技能时，用 -s 参数指定技能名：

cmd skills add addyosmani/agent-skills -s spec-driven-development

例如 spec-driven-development 对应的技能定义了 SPECIFY → PLAN → TASKS → IMPLEMENT 四阶段门控工作流，每个阶段都要人工评审后才进入下一阶段；interview-me 则是「一次只问一个问题」的需求澄清流程。技能名即 skills/ 下的目录名，也是 frontmatter 里的 name 值。

用户级安装（全局作用域）

加 --global 把技能安装到 ~/.commandcode/skills/，在所有项目中可用：

cmd skills add addyosmani/agent-skills --global

其他支持的参数形式

cmd skills add addyosmani/agent-skills@main            # 指定分支
cmd skills add addyosmani/agent-skills/skills/interview-me   # 指定仓库内的具体路径
cmd skills add addyosmani/agent-skills --force         # 已安装时覆盖/更新

• @main 后缀固定从 main 分支拉取，适合需要在特定分支版本上锁定技能的场景；
• 直接给到仓库内路径（如 .../skills/interview-me）时，Command Code 只从该路径出发发现 SKILL.md，等价于安装单个技能；
• --force 会重新拉取并覆盖已存在的技能，这也是把技能更新到最新版本的方式。

管理已安装的技能

cmd skills list                       # 列出已安装技能（project + user + bundled）
cmd skills remove spec-driven-development           # 移除项目级技能
cmd skills remove spec-driven-development --global  # 移除用户级技能

list 会聚合三个来源：项目级（.commandcode/skills/）、用户级（~/.commandcode/skills/）以及 Command Code 自带的 bundled 技能；remove 默认只作用于项目级，需要 --global 才作用于用户级。更新技能没有单独的 update 子命令，统一用 add ... --force 重拉覆盖。

在 TUI 中使用技能

安装完成后无需任何额外配置——技能被自动发现，并出现在 TUI 的斜杠菜单中，带有 [skill] 标签：

/spec-driven-development   [skill] Write a spec before writing code…

• 输入 / 浏览全部命令与技能，继续输入技能名前缀即可过滤；
• 使用 /skills 可以启用/禁用单个技能，无需重新安装。

斜杠菜单里的提示语（如 "Write a spec before writing code…"）来自各 SKILL.md 的 description 字段，这也是为什么 agent-skills 对每条 description 都要求写清「做什么 + 何时用」：它同时服务于 Agent 的按需激活判断和人类在菜单里的快速识别。

技能发现路径：四个作用位置一览

Command Code 会从以下位置发现技能（项目级条目相对于最近的 git 根目录解析）：

Scope	Path
Project	.commandcode/skills/<name>/SKILL.md
Project (agents-compat)	.agents/skills/<name>/SKILL.md
User	~/.commandcode/skills/<name>/SKILL.md
User (agents-compat)	~/.agents/skills/<name>/SKILL.md

cmd skills add 的写入目标是 .commandcode/skills/（项目级）或 ~/.commandcode/skills/（--global）。

其中两组 agents-compat 路径值得注意：从源码结构看，agent-skills 面向多个 Agent 工具（Claude Code、Gemini CLI、OpenCode、Copilot 等），而这些工具普遍遵循 .agents/skills/<name>/SKILL.md 这一跨工具约定。例如 docs/gemini-cli-setup.md 说明 Gemini CLI 会同时自动发现 .gemini/skills/ 或 .agents/skills/，docs/opencode-setup.md 也列出 .agents/skills/ 作为通用兼容路径。这意味着如果你把技能手动放入 .agents/skills/（或 ~/.agents/skills/），Command Code、Gemini CLI、OpenCode 等工具都能发现同一份技能文件，实现跨工具共享同一套技能安装，而不必为每个工具维护一份拷贝。

为什么这套技能能被"递归发现"：SKILL.md 的目录契约

Command Code 的发现逻辑是"递归找 SKILL.md"，它对技能目录内部结构没有额外要求，只要求入口文件存在。agent-skills 的技能目录则遵循更完整的契约（见 docs/skill-anatomy.md）：

skills/
  skill-name/
    SKILL.md           # 必需：技能定义（frontmatter + 工作流正文）
    scripts/           # 可选：技能工作流使用的可执行辅助脚本
    references/        # 可选：技能专属参考文档

• 每个技能是一个自包含目录，SKILL.md 是唯一必需文件，例如最精简的 skills/ci-cd-and-automation/ 只有一个 SKILL.md，而 skills/idea-refine/ 则额外携带 examples.md、frameworks.md、refinement-criteria.md 和 scripts/；
• 技能正文按统一的章节骨架组织：Overview（是什么）、When to Use（何时用/何时不用）、核心流程（分步工作流）、Common Rationalizations（借口-反驳对照表）、Red Flags（违规信号）、Verification（带证据要求的退出条件）。这种"流程而非散文"的写法保证了 Agent 装载技能后拿到的是可执行步骤，而不是需要自行发挥的参考文档；
• 渐进式披露（progressive disclosure）机制下，启动时只有技能名与 description 进入上下文，完整 SKILL.md 在被判定相关后才加载——这与 Command Code「斜杠菜单里只展示一行描述」的呈现方式正好对应。

此外，技能包还包含位于仓库根目录的 references/ 共享清单（如 references/security-checklist.md、references/testing-patterns.md）。从源码结构看，整仓安装（cmd skills add addyosmani/agent-skills 不带路径参数、勾选全部技能时技能目录整体拷贝）会保留技能对这些清单的引用；但如果只安装单个技能目录（-s 参数或指定仓库内路径），这些技能正文中指向仓库级 references/ 的链接可能解析不到——这一点与 README.md 中提到的单技能安装可移植性限制（issue #361）一致，属于已知边界，使用时按需把所需清单复制进对应技能的 references/ 目录即可。

安装后的验证清单

完成安装后，可以按以下步骤确认技能真正生效：

1. cmd skills list 能看到目标技能，并确认其作用域（project 或 user）符合预期；
2. 在 TUI 中输入 / + 技能名前缀，确认它出现在斜杠菜单且带 [skill] 标签；
3. 实际触发一次（例如输入 /spec-driven-development），观察 Agent 是否开始执行该技能定义的步骤（如 SPECIFY 阶段输出规格文档）；
4. 若技能不生效，检查项目级技能是否放在 git 根目录下的 .commandcode/skills/<name>/SKILL.md（Command Code 以最近的 git 根为基准解析项目级路径）；
5. 需要更新时执行 cmd skills add addyosmani/agent-skills --force 重新拉取覆盖；需要卸载时用 cmd skills remove <name>（用户级加 --global）。

适用前提与限制

• 上述所有行为基于 Command Code 当前版本的 cmd skills 子命令，以及 agent-skills 仓库 skills/ 目录下现有的 25 个技能（24 个生命周期技能 + using-agent-skills 元技能）；
• cmd skills add 依赖联网克隆 GitHub 仓库，因此需要可访问该仓库的网络环境；
• 项目级安装要求当前处于一个 git 仓库内（技能写入当前 git 根目录下的 .commandcode/skills/），在用户主目录等无 git 根的位置应改用 --global；
• 技能只是"工作流指令"，最终执行仍由 Command Code 的 Agent 完成；技能中的验证门（如测试必须通过、变更需附证据）要求 Agent 具备实际运行测试和命令的权限。

如果你想了解同一套技能在其他 Agent 工具（Claude Code、Codex、Gemini CLI、Cursor 等）中的接入方式，可参考 README.md 的 Quick Start 一节及 docs/ 下各工具的专属安装指南。