create-command

用途

create-command 用于为 code-forge（forgecode）应用创建新的自定义命令。命令是模块化的工作流，可被调用以执行特定任务，例如代码检查、测试、提交前验证、文档更新、清理、构建部署等。

文件位置

所有命令文件必须创建在 <cwd>/.forge/commands 目录中，其中 <cwd> 是 code-forge 项目的当前工作目录。这是 forge 发现和加载自定义命令的唯一位置，放在其他位置将无法被识别。

• 目录：<cwd>/.forge/commands
• 文件格式：{command-name}.md
• 示例：若项目位于 /home/user/my-project，命令应放在 /home/user/my-project/.forge/commands/

命令文件结构

每个命令文件必须包含两部分：

1. YAML Frontmatter（必需）：

   • name：命令标识符，多词名称使用连字符
   • description：命令的功能说明

2. 命令正文（必需）：

   • 要执行的步骤列表
   • 用于自动化工作流的特殊标签
   • 每个步骤的清晰说明

特殊命令标签

命令正文中可使用三种标签嵌入自动化命令，标签应放在步骤描述之后的独立行：

• <lint>：用于 linting/格式化命令，例如 <lint>cargo +nightly fmt --all; cargo +nightly clippy --fix --allow-staged --allow-dirty --workspace</lint>
• <test>：用于测试命令，例如 <test>cargo insta test --accept --unreferenced=delete</test>
• <shell>：用于一般 shell 命令（非 linting 或测试），例如 <shell>rm -rf target/debug</shell>

命令类型

• 简单命令：单步骤或仅含说明的命令
• 多步骤命令：包含多个顺序步骤的命令
• 自动化工作流命令：包含自动化检查的命令

使用方式

创建命令的步骤：

1. 确定命令目的：明确任务、涉及步骤、是否需要自动化检查或测试、用户应如何处理结果。
2. 选择命令名称：使用基于动词的名称，多词用连字符。推荐如 check、fixme、pr-description、run-tests；避免 checker、fixing、PRdescription。
3. 编写命令文件：在 <cwd>/.forge/commands 目录中创建 {command-name}.md 文件，包含 frontmatter 和命令正文。

命令正文使用 markdown 列表编写步骤，每个步骤应以明确的动作动词开头，具体可执行，并包含上下文。

最佳实践

命名：

• 仅使用小写字母
• 多词名称用连字符分隔
• 使用基于动词的名称（祈使形式）
• 名称简短但具描述性

描述：

• 清晰简洁
• 描述命令做什么，而非如何做
• 包含主要目的和关键结果
• 避免实现细节

命令步骤：

• 顺序步骤使用编号列表
• 每个步骤以动作动词开头
• 具体说明要做什么
• 复杂步骤包含上下文
• 使用现在时

特殊标签：

• 标签放在步骤之后的独立行
• 仅使用 <lint>、<test>、<shell> 标签
• 包含可执行的完整命令
• 为工作流使用适当的标志

验证清单

文件结构：

• 文件位于 <cwd>/.forge/commands 目录（关键）
• 文件名与命令名称匹配（如 check.md 对应 name: check）
• 文件扩展名为 .md
• YAML frontmatter 使用 --- 分隔符

Frontmatter：

• 存在 name 字段
• name 使用小写字母
• name 多词时使用连字符
• name 基于动词（祈使形式）
• 存在 description 字段
• description 清晰简洁
• description 描述做什么而非如何做

命令正文：

• 至少定义一个步骤
• 步骤使用项目符号（-）
• 每个步骤以动作动词开头
• 步骤具体可执行
• 复杂步骤包含上下文
• 步骤顺序合理

特殊标签：

• 标签在步骤描述之后的独立行
• 仅使用有效标签（<lint>、<test>、<shell>）
• 标签命令完整可执行
• 标签命令使用适当标志
• 标签命令格式正确

测试命令

创建命令后，可通过以下方式测试：

1. 语法检查：验证 YAML 是否有效，如使用 yamllint path/to/your-command.md
2. 人工审查：检查每个步骤是否合理、顺序是否逻辑、命令是否完整
3. 执行测试：运行命令，检查每个步骤是否成功执行、输出是否符合预期、是否有错误
4. Forge 识别测试：验证命令被 forge 识别
   • forge list command（列出所有命令，自定义命令标记为 type: custom）
   • forge list cmd（仅列出自定义命令）
   • forge list command --custom（较新版本，仅列出自定义命令）
5. 边界情况：考虑步骤失败、环境不同、文件缺失等场景

常见错误

Frontmatter 错误：

• 分隔符错误：缺少闭合 ---
• 缺少必需字段：缺少 description

命名错误：

• 使用 CamelCase 名称
• 使用名词而非动词

步骤错误：

• 没有动作动词
• 步骤含糊不清

标签错误：

• 标签与步骤在同一行
• 使用无效标签（如 <check>）
• 命令不完整（如缺少 --all 标志）

适用场景

该技能适用于需要为 code-forge 项目定义可复用工作流的开发者，典型场景包括：Git 工作流命令（提交检查）、文档命令（更新文档）、清理命令（清理临时文件）、构建部署命令（构建并部署到 staging）等。

限制

命令必须放在 <cwd>/.forge/commands 目录，否则无法被 forge 发现。仅支持 <lint>、<test>、<shell> 三种特殊标签。命令名称必须与文件名（不含 .md）匹配。若命令未出现在列表中，需检查文件位置、文件名与 frontmatter 中 name 字段是否匹配、YAML frontmatter 格式是否正确、name 和 description 字段是否都存在。