用 Hello World Skill 跑通完整生命周期

时间锚点：从此刻起，大约 25 分钟，你将完成一个最简 Skill 的声明、本地测试、团队共享的闭环。
场景还原：上一章你搭好了开发环境，就像有了厨房和灶台；本章要做的是“煎一颗蛋”，让它完成从材料准备、下锅、翻面到装盘的全流程——跑通 Hello World Skill，你会对 Skills 开发的整个生命周期形成肌肉记忆。

Skill 的本质是一个“可被 Claude 按需激活的专用能力包”：一个包含 SKILL.md 指令文件、可选脚本、配置和静态资源的目录。当 Claude 判断当前任务与某个 Skill 相关时，就会自动加载执行——你不需要在每次对话里反复写同样的长提示。Hello World Skill 将把这个“目录 → 激活 → 执行 → 卸载”的完整路径实际跑一遍，同时让你看清参数定义、调试输出和团队协作的真实模样。

你需要什么

• 环境：已按上一章完成的 Claude Code 开发环境（已配置 MCP、可执行 Shell 的工具集）。
• 账号：拥有组织工作区的读写权限（用于发布步骤）。
• 材料：一个文本编辑器、终端。
• 预计耗时：25–30 分钟（含首次试错）。

最终成果

你将得到一个名为 date-diff 的 Skill，它能根据用户输入的两个日期，准确计算相隔天数。在流程中，你会实际经历：

1. 手写一个符合规范的 SKILL.md 与配套 Shell 脚本。
2. 使用 Claude Code 的调试功能观察技能加载、参数注入、输出格式。
3. 将技能目录共享至团队工作区，验证其他成员可直接调用且结果一致。

为什么要做这个？
全局流程感远胜于单独学习某个命令。完成这个闭环后，往后任何复杂 Skill 的开发，你都会下意识地知道“现在该做什么事、该去哪里检查”——这就是可迁移的开发直觉。

步骤说明

1. 手写第一个 SKILL.md 与脚本

动作：在你的项目根目录下创建 skills/date-diff/ 文件夹，并在其中新建两个文件：

skills/
└─ date-diff/
   ├─ SKILL.md
   └─ date_diff.sh

先写好 SKILL.md，再写脚本，最后一并验证。 这个顺序能避免脚本尚未完成时就被 Claude 误加载，产生难以排查的“半成品错误”。

SKILL.md 的内容：

# Date Difference Calculator

计算两个日期之间的相隔天数。接收 `--start` 和 `--end` 参数，返回整数天数差。

## 调用方式
当任务涉及日期差计算时，Claude 会激活本技能并在 Shell 环境中执行 `date_diff.sh`。

## 参数
- `--start`：开始日期，格式 YYYY-MM-DD
- `--end`：结束日期，格式 YYYY-MM-DD

## 返回值
纯数字，表示日期差（`end - start`），可能为正、负或零。

## 约束
- 若任一参数缺失或格式不符合 `YYYY-MM-DD`，返回字符串 `ERROR: invalid date`
- 仅使用 GNU date，不依赖网络

date_diff.sh 脚本（Shell 脚本，用于确定性计算）：

#!/bin/bash
# 计算两个日期的天数差

set -euo pipefail

START="$1"
END="$2"

# 参数校验
if [[ -z "$START" || -z "$END" ]]; then
  echo "ERROR: invalid date"
  exit 1
fi

if ! date -d "$START" &>/dev/null || ! date -d "$END" &>/dev/null; then
  echo "ERROR: invalid date"
  exit 1
fi

# 转换为秒级时间戳并计算差值
SEC_START=$(date -d "$START" +%s)
SEC_END=$(date -d "$END" +%s)
DIFF_DAYS=$(( (SEC_END - SEC_START) / 86400 ))

echo "$DIFF_DAYS"

给脚本添加可执行权限：

chmod +x skills/date-diff/date_diff.sh

预期结果：两个文件内容完整，脚本可直接在终端执行验证：

./skills/date-diff/date_diff.sh 2026-01-01 2026-01-10
# 应输出：9

⚠️ 注意：即使 Shell 脚本已经能独立运行，也不要急于让 Claude 调用。先完成下一步本地测试，因为 Skill 激活时还会有隐式的环境变量与工作路径差异，直接在 Claude 中调试效率更高。

2. 本地测试与调试输出

现在你要在 Claude Code 的上下文中触发这个技能，并观察它被识别、加载、执行、卸载的全过程。这和单纯跑脚本的本质区别在于：你会看到 Claude 如何把自然语言请求翻译成技能调度，以及技能返回值的后续使用。

动作：

1. 确保当前工作目录是项目根（skills/ 文件夹位于此处）。
2. 在 Claude Code 对话中输入一条需要日期计算的任务，例如：

   “帮我算一下 2026-06-01 到 2026-06-15 相差多少天。”

此时 Claude 会进入思考链，自动判别 date-diff Skill 的相关性并加载它。在此过程中，你可以打开调试面板（通常为侧边栏或命令面板中的 Developer Tools > Skill Activity）来查看以下关键信息：

• Skill 匹配日志：Claude 如何从 skills/ 目录扫描 SKILL.md，并匹配到当前请求。
• 参数注入：--start 和 --end 被正确填充为 2026-06-01 和 2026-06-15。
• 进程执行输出：调试面板中会显示类似 RUN: /path/to/date_diff.sh 2026-06-01 2026-06-15 的命令行。
• 返回结果解析：14（或你的预期值）被 Claude 接收，并最终生成包含该数值的自然语言回复。

如果出现错误，最常见的三类问题及解法如下：

踩坑标记：即使你在 SKILL.md 中声明了参数格式，Claude 偶尔仍会以 --start=2026-01-01 的形式传递，而非空格分隔。要彻底规避，可在脚本头部统一做一次参数清洗，例如：

CLEAN_START=$(echo "$1" | sed 's/^--start=//')
CLEAN_END=$(echo "$2" | sed 's/^--end=//')

然后在主逻辑中使用清洗后的变量。这个 bug 在社区中反复被提及，目前尚未在官方文档中统一修正，务必在调试阶段就处理掉。

预期结果：Claude 给出准确的日期差（譬如 14 天），并且调试面板完整记录了 skill load → run → output → unload 四个环节的时间戳。你已经完成了一次本地闭环。

3. 发布到团队工作区

开发本地的 Skill 只有你自己能用。要让同事也能复用同一个 date-diff 能力，需要将其上传至组织级别的 Skills 市场（或共享目录），并配置可见性与权限。

动作：

1. 将 skills/date-diff/ 整个文件夹复制（或符号链接）到团队共享的 Skill 仓库中，通常路径为：

   /org-shared/skills/date-diff/

2. 确认该目录下仍包含 SKILL.md 和 date_diff.sh，脚本权限保留。
3. 在组织的管理后台（如果使用企业级 Skills 平台）将 date-diff 状态的可见性设为 “团队可见” 或更高，确保同事在请求日期计算时，Claude 能扫描到该 Skill。
4. 邀请一名团队成员进行一次协同验证：让对方在独立的 Claude Code 会话中输入相同的日期计算请求，确认：
   • Skill 能被自动激活（无需手动安装或导入）。
   • 计算结果与你的完全一致。
   • 对方无权修改 Skill 源文件（只读校验）。

为什么这样设计？
经验表明，共享 Skill 时最大的痛点不是“找不到文件”，而是信任链：同事不确定这个技能是否被其他人改动过、是否符合最新的业务规则。通过“共享源目录 + 只读权限”可将这种信任建立在文件系统上，而非口头约定。

预期结果：至少一名团队成员成功调用你的 date-diff Skill，且客户端调试面板显示相同的执行日志，源文件不可被其修改。从这一刻起，你的 Skill 正式进入生产级生命周期——后续的更新、版本控制、废弃都有章可循。

回顾

你用了不到半小时，让一个极简 Skill 走完了“编写声明 → 本地调试 → 团队发布”的全流程。具体而言：

1. 创建了符合规范的 skills/date-diff/ 目录及其内容。
2. 通过 Claude Code 的调试面板验证了 Skill 的加载、参数注入、执行与解析。
3. 将技能发布至团队工作区并完成一次跨用户调用验证。

这个闭环的价值并不在于计算日期的功能本身，而在于：从此你拥有了一个可复制的开发流程模板。将来面对任何复杂 Skill，你都会本能地按照“写声明-测闭环-共共享”的顺序推进，避免陷入“功能做了一大半却不知道如何验证”的困境。

行动清单

1. 在你的项目中创建 skills/hello-world/ 骨架，亲手填写 SKILL.md 和至少一个可执行脚本。
2. 打开调试面板，通过 Claude Code 对话触发该 Skill，完整观察四次日志事件。
3. 修复可能出现的“参数格式不兼容”问题，并记录下你采取的后置清洗方案。
4. 将技能目录推送到团队共享区，并找一位同事进行一次端到端联调。
5. 在个人笔记中记下本次闭环中消耗的实际时间与出现的错误类型，以便后续章节对比优化效果。

完成 Hello World Skill 的闭环后，你可能会好奇：为什么有些 Skill 能被自动发现，而有些则默默无闻？答案就藏在那些定义加载行为的文件里。下一章 《文件与配置文件决定了 Skills 的加载行为》 将系统拆解 SKILL.md、.claudeignore 以及其他元数据文件的约束关系，让你能精准控制技能在何时、以何种优先级被激活。