自定义技能
技能是可通过 Claude Code 自动执行完整工作流的斜杠命令。当你在终端中输入 /implement 时，Claude Code 会读取对应技能中的指令，并执行预定义的步骤：读取任务、编写代码、运行测试，以及将项目移至正确的列。
Almirant 内置了涵盖最常见工作流的技能，但你也可以创建自己的技能，使其适应团队的需求。
内置技能
Almirant 默认包含以下技能：
| 技能 | 说明 |
|---|---|
/implement | 读取分配的工作项，实现所需代码，并将任务移至 Review 列 |
/review-task | 将当前实现与工作项定义及完成定义进行对比，以审查当前实现 |
/validate | 完整验证流水线：代码审查 + 测试执行 + 截图 |
/test-task | 为当前实现生成并运行自动化测试 |
/pr | 根据当前分支创建带有生成说明的 GitHub Pull Request |
/ideate | 启动交互式头脑风暴会话，并根据创意创建工作项 |
/create-tasks | 创建结构完善的工作项，包含标题、说明、验收标准和估算 |
各技能的工作方式
/implement
- 通过 MCP 从 Almirant 读取分配的工作项
- 分析说明、验收标准和完成定义
- 探索现有代码库以了解上下文
- 实现所需变更
- 将工作项移至 Review 列
/review-task
- 从 Almirant 获取工作项及其完成定义
- 读取已实现的代码变更
- 将实现与验收标准进行对比
- 生成包含发现和建议的详细报告
/validate
- 运行
/review-task审查实现 - 运行项目测试
- 如果有 UI，则截取屏幕截图进行视觉验证
- 生成包含每个步骤结果的汇总报告
/test-task
- 读取工作项以了解需要测试的内容
- 分析当前实现
- 生成单元测试和/或集成测试
- 运行测试并报告结果
/pr
- 分析当前分支上的提交和变更
- 为 Pull Request 生成标题和说明
- 使用生成的信息在 GitHub 上创建 PR
/ideate
- 启动交互式对话来探索创意
- 通过提问细化概念
- 将创意转化为 Almirant 中结构化的工作项
/create-tasks
- 接收所需内容的高层描述
- 将工作拆分为细粒度任务
- 在 Almirant 中创建包含所有必要信息的工作项
创建自定义技能
技能定义为项目 .claude/skills/ 目录中的 Markdown 文件。
位置
your-project/
.claude/
skills/
implement.md
review-task.md
my-custom-skill.md # <-- 你的自定义技能
技能结构
每个技能文件包含两个部分：
- 前置元数据：YAML 格式的元数据（名称和说明）
- 指令：Claude Code 应遵循的步骤，以 Markdown 编写
---
name: my-skill
description: 此技能功能的简要说明
---
## 面向代理的指令
1. 第一步：详细说明
2. 第二步：详细说明
3. 第三步：详细说明
示例：部署技能
---
name: deploy-staging
description: 将当前分支部署到 staging 环境
---
## 指令
1. 运行 `git status`，确认没有未提交的变更
2. 使用 `bun run lint` 运行 linter 并修复所有错误
3. 使用 `bun run test` 运行测试并确认全部通过
4. 将当前分支推送到 origin
5. 使用 `bun run deploy:staging` 部署到 staging
6. 检查 staging URL，确认部署成功
7. 将结果及环境 URL 报告给用户
示例：文档技能
---
name: document-feature
description: 为已实现的功能生成技术文档
---
## 指令
1. 使用 MCP 从 Almirant 读取与该功能关联的工作项
2. 识别实现中新建或修改的文件
3. 对于每个新组件或模块：
- 生成包含说明、参数和示例的 JSDoc
- 如果是 hook，则记录返回值
- 如果是 endpoint，则记录 request/response
4. 如果存在，则更新所属领域的 README
5. 在工作项中创建评论，概述已生成的文档
示例：数据库迁移技能
---
name: db-migrate
description: 安全地生成并应用数据库迁移
---
## 指令
1. 读取 schema 文件中的待处理变更（`backend/packages/database/src/schema/`）
2. 使用 `bun run db:generate` 生成迁移
3. 审查 migrations 文件夹中生成的 SQL
4. 如果 SQL 包含破坏性操作（DROP 或会导致数据丢失的 ALTER），
警告用户并等待确认后再继续
5. 使用 `bun run db:migrate` 应用迁移
6. 确认迁移已成功应用
最佳实践
清晰且具体的指令
编写不留歧义的指令。不要只写“审查代码”，而应明确要审查哪些文件或模式。
# 效果较差
1. 审查代码
2. 进行必要的变更
# 效果更好
1. 阅读 `src/domains/[feature]/` 中的所有文件，以了解结构
2. 确认展示组件不包含 useState 或 useEffect
3. 如果在 .tsx 组件中发现逻辑，请将其提取到 `application/hooks/` 中的自定义 hook
在指令中使用 MCP 工具
引用 Almirant 的 MCP 工具，使技能能够与你的看板交互。
1. 使用 `get_work_item` 工具读取已分配的任务
2. 根据说明实现变更
3. 使用 `update_work_item` 将任务移至 "Review" 列
包含条件和验证
定义在出现失败或特殊条件时技能应执行的操作。
3. 使用 `bun run test` 运行测试
- 如果测试失败，分析错误并尝试修复
- 如果尝试 2 次后仍无法修复，请向用户报告失败情况
4. 如果工作项具有 "needs-review" 标签，请勿自动将其移至 Done
保持技能聚焦
每个技能应专注做好一件事。如果需要复杂工作流，请将其拆分为多个技能并手动组合。
提示
先复制一个内置技能，再根据你的用例修改它。调整现有内容比从头创建更容易。
重要
技能是提供给 AI 的指令，而不是可执行脚本。Claude Code 会解释这些指令并决定如何执行每一步。请像为首次阅读这些指令的开发者编写一样来撰写它们。
与团队共享技能
技能位于 .claude/skills/ 中，因此会与项目的其余部分一起由 Git 进行版本控制。克隆仓库的任何团队成员都可访问相同的技能。
为保持一致性：
- 在前置元数据中为每个技能提供清晰说明
- 使用一致的命名约定（kebab-case）
- 使用前缀将相关技能分组：
deploy-staging.md、deploy-production.md - 像审查其他项目文件一样在代码审查中审查技能