运行第一个 Skill 并验证输出
High Contrast
Dark Mode
Light Mode
Sepia
Forest
5 min read1,009 words

运行第一个 Skill 并验证输出

你已经写好了第一个 Skill 文件，现在让它真正运行起来。这一节演示完整的从零到运行的过程，包括如何判断 Skill 是否按预期工作、如何处理第一次遇到的问题。

完整演练：git-standup Skill

我们从头构建一个真实有用的 Skill：生成适合站会使用的 Git 工作摘要。

步骤 1：创建 Skill 文件

mkdir -p .claude/skills

创建文件 .claude/skills/standup.md：

---
description: 生成今日或最近工作的 Git 提交摘要，适合站会使用
allowed-tools: Bash
---
# 站会工作摘要
## 目标
从 Git 历史中提取最近的工作内容，生成简洁的站会摘要。
关注点：做了什么、完成了哪些功能、遇到了哪些问题。
## 执行步骤
1. 运行以下命令获取最近的提交历史：
```
git log --oneline --since="yesterday" --format="%h %s (%an, %ar)"
```
如果今天没有提交，改为查询最近 3 天：
```
git log --oneline --since="3 days ago" --format="%h %s (%an, %ar)"
```
2. 运行以下命令获取修改文件的统计：
```
git diff --stat HEAD~3 HEAD 2>/dev/null || git diff --stat HEAD~1 HEAD
```
3. 根据提交信息，将工作内容归类为：
- 已完成的功能（feat: 开头的提交）
- 已修复的问题（fix: 开头的提交）
- 进行中的工作（WIP / 其他提交）
4. 用自然语言（而非仅列出 commit hash）总结工作内容
## 输出格式

📋 站会摘要

昨天/最近完成： - [用一句话描述完成的工作] - [另一项完成的工作]

今天计划： （根据进行中的工作推断，如无法判断则留空，提示用户手动填写）

阻碍/问题： （如果有未完成或 WIP 的工作，提示可能的阻碍）

基于最近提交：[提交数量] 次

步骤 2：在 Claude Code 中运行

打开终端，进入项目目录，启动 Claude Code：

cd /your/project
claude

在 Claude Code 的交互界面中：

> /standup

Claude Code 会： 1. 找到 .claude/skills/standup.md 2. 读取文件内容 3. 调用 Bash 工具执行 git log 命令 4. 根据结果生成摘要

步骤 3：预期输出示例

📋 站会摘要
**昨天/最近完成：**
- 完成了用户认证模块的 JWT 刷新逻辑（feat: add token refresh）
- 修复了登录页面在 Safari 上的样式问题（fix: Safari login button）
**今天计划：**
（根据进行中的工作，可能继续：API 限流中间件开发）
**阻碍/问题：**
- 有 1 个 WIP 提交，可能还有未完成的工作
---
*基于最近提交：4 次（过去 2 天）*

验证 Skill 的三个维度

运行 Skill 后，通过以下三个维度判断它是否工作正常：

维度 1：工具调用是否符合预期

Claude Code 会显示它调用了哪些工具。检查： - 是否调用了 allowed-tools 中声明的工具？ - 工具的参数是否合理（例如 Bash 命令是否正确）？ - 有没有调用你不期望的工具（如 Write 写了你不想要的文件）？

维度 2：输出格式是否匹配

对照 Skill 中定义的输出格式，检查： - 结构是否正确（有没有缺失的部分）？ - 格式是否符合预期（Markdown 表格、代码块等）？ - 内容是否准确（工具输出有没有被正确解析）？

维度 3：行为是否稳定

连续运行 Skill 两到三次，检查： - 在相同输入下，输出结构是否一致？ - 如果仓库没有变化，结论是否稳定（不会随机波动）？

常见的第一次运行问题

问题 1：/standup 命令没有被识别

> /standup
未知命令：/standup

检查： - .claude/skills/standup.md 文件路径是否正确？ - 当前工作目录是否在包含 .claude/ 目录的项目根目录？ - 文件名是否有拼写错误（如 stand-up.md vs standup.md）？

# 验证文件存在
ls .claude/skills/
# 验证 Claude Code 在正确目录
pwd

问题 2：Bash 工具执行失败

Bash 工具：git log --oneline --since="yesterday" ...
错误：fatal: not a git repository

原因：项目目录不是 Git 仓库，或者当前目录不在 Git 仓库根目录。

解决：在 Skill 中添加前置检查：

## 执行步骤
0. 首先运行 `git rev-parse --is-inside-work-tree` 验证当前目录是 Git 仓库。
如果失败，告知用户"当前目录不是 Git 仓库，请在项目根目录运行此 Skill"并停止。

问题 3：输出格式不符合预期

Claude 生成了正确的内容，但格式和你期望的不一样。

解决：在输出格式区域更明确地使用示例而不是描述：

## 输出格式
严格按照以下格式输出，不要修改标题，不要添加额外段落：
[格式示例放这里，越具体越好]

Skill 迭代工作流

第一次运行很少能得到完美的结果。建议按以下迭代循环改进：

graph LR A["写 Skill 文件"] --> B["运行 /skill-name"] B --> C{结果符合预期？} C -->|是| D["✅ 完成"] C -->|否| E["分析差距"] E --> F["修改 Skill 文件"] F --> B style D fill:#e8f5e9,stroke:#2e7d32 style E fill:#fff3e0,stroke:#ef6c00

通常需要 2–4 次迭代才能得到稳定、高质量的输出。不要期望第一次就完美。

本节记录清单

下一章：Skill 参数设计与输入处理——你的第一个 Skill 能运行了。现在让它更灵活：如何让用户在调用时传入参数，让同一个 Skill 适应不同场景？