Lesson 5: Integrating Skill with a Real Repository's CI / Team-Shared Directory
本课目标:你会把个人目录里打磨过的 Skill,接到真实仓库的 CIrespond in singing团队共享目录约定里——谁能改、合并前验什么、只读门禁怎么挡私货。不是再写一篇「协作很重要」的感想,而是今晚就能提的校验脚本与目录规范。上一课你已经会用失败用例迭代 description;本课把它变成可合并的工件。

Introduction
请先完成第 4 课《用真实失败用例迭代 description》:https://school.myshirtai.com/archives/3661。你手头至少要有:一个可加载 Skill、一份带前后计数的 failures.md、一个 description 的 git tag。若还缺第 1–3 课基础,请回补:第 1 课 https://school.myshirtai.com/archives/3378;第 2 课 reference 与计划文件 https://school.myshirtai.com/archives/3462;第 3 课带脚本与安全审计 https://school.myshirtai.com/archives/3521The
材料清单:仓库写权限或能提 PR;CI 能跑 Python/Shell 任选其一;团队同意一个共享路径(示例 .claude/skills/ 或 docs/skills/);第 4 课的 failures 摘要。没有失败计数,就不要进共享目录——那是把未验证触发器广播给全组。

概念:共享的是约定,不是你的家目录副本
个人 ~/.claude/skills 里怎么乱都可以;一进团队仓库,Skill 就变成产品的一部分。我用三句话压概念:
- 单一入口:全组只认一个目录树,禁止每人一份「最终版」私货路径。
- 合并前门禁:CI 校验
SKILL.mdfrontmatter、禁止空 description、脚本目录要有来源说明。 - 只读默认:流水线里对 skills 的检查是只读的;发布/安装到运行环境另走受控步骤,避免 CI 机器人写回生产 Skill。
官方 Agent Skills 文档强调 description 负责触发、细节渐进披露;第 3 课强调脚本安全。本课把这两层钉进仓库:触发器没有计数不给合;脚本没有可信来源标记不给合。约定写进 CONTRIBUTING-skills.md 一页就够,别写成无人读的章程。
动手前先做一个判断:这个 Skill 是否被至少两个人用过、有没有前后计数、有没有人愿意在 CODEOWNERS 里当它的负责人?三条有一条答不上,就先留在个人目录,下周再提。进共享的门槛定高一点,比事后清理二十个没人维护的触发器便宜得多。
分步实操:CI 校验、共享目录、只读门禁

- 定目录:在仓库根选一个入口,例如
.claude/skills/<skill-name>/SKILL.md。每个 Skill 一目录;可选reference/,scripts/。不要用「桌面压缩包」当分发渠道。 - 写校验脚本
scripts/validate_skill.py::遍历 skills 下每个目录,断言存在SKILL.md;解析 frontmatter,要求name,description非空且 description 长度在你们约定的上下限内;若存在scripts/,要求同目录有SOURCE.md(说明来源与许可)或等价字段。 - 挂 CI:在 GitHub Actions / 你们现有 CI 加一步:仅在
skills/**或约定路径变更时跑校验;失败则阻断 merge。CI 对 skills 目录只读——不要在 job 里「自动美化并 push」。 - PR 模板加三问:是否附 failures 摘要与前后触发计数?是否新增脚本及来源?是否与现有 Skill 名称/触发域冲突?三问空着不允许求合并。
- 发版约定:合并 main 后,由值班人按清单把 Skill 同步到运行环境(或由受控 CD 拉取)。禁止开发者从个人笔记本直接 scp 到共享盘覆盖。
# validate_skill.py 思路示意(非完整生产代码)
from pathlib import Path
import sys, re
root = Path("skills") # 或 .claude/skills
errs = []
for d in sorted(p for p in root.iterdir() if p.is_dir()):
skill = d / "SKILL.md"
if not skill.exists():
errs.append(f"{d.name}: missing SKILL.md"); continue
text = skill.read_text(encoding="utf-8")
if not re.search(r"^description:\s*\S", text, re.M):
errs.append(f"{d.name}: empty description")
if (d / "scripts").is_dir() and not (d / "SOURCE.md").exists():
errs.append(f"{d.name}: scripts/ without SOURCE.md")
if errs:
print("\n".join(errs)); sys.exit(1)
print("SKILL_CI_OK")
校验通过的关键字我建议固定为 SKILL_CI_OK。缺 description、缺 SOURCE、或同名冲突,都应非零退出。冲突检测可以简单:所有 name: 必须唯一。更细的触发域重叠,留给人工三问,别幻想第一周就上 NLP 查重。
PR 模板直接抄这段,放进 .github/pull_request_template.md,三问就有了固定格式:
## Skill 变更三问(空着不允许求合并) 1. 失败用例摘要:误触发 __ → __,漏触发 __ → __;第 4 课 tag:________ 2. 是否新增或修改 scripts/?来源与许可已写进 SOURCE.md:是 / 否 3. 与现有 Skill 名称或触发域是否冲突?查过的相近 Skill:________ ## 禁用方式(一行) ________
同一时间把 CONTRIBUTING-skills.md 的三行也写掉,评审时有据可依:
入口:只认 .claude/skills/<name>/,其他路径的 Skill 不加载、不评审。 禁止:密钥、个人笔记、整机配置、与 Skill 无关的大文件;CI 不得写回 main。 同步:合并 main 后由当周值班人按清单同步到运行环境,禁止个人直接覆盖共享盘。
配置要点:评审、来源、回滚与本地对齐
脚本挂上只是第一步;下面几条决定共享目录三个月后还能不能用,每条都是今天能改的配置。
- CODEOWNERS 两人评审:给 skills 路径设 CODEOWNERS,必须两人评审。一人合并自己的 description,是事故温床。评审只看三件事:description 正反例像不像触发器;failures 数字有没有下降;scripts 能不能审计。评审人不必最懂模型,但必须敢按红灯。
- SOURCE.md 至少四行:来源 URL 或作者、许可、最后审计日期、已知风险,缺一行 CI 就红。写「内部自研」可以,但要留审计人名字与日期——匿名脚本进共享,等于匿名责任。
- 每个 Skill 写一行禁用方式:exist
CONTRIBUTING-skills.md里写清误触发暴涨时怎么下线(改名下线、移出加载路径或 feature flag)。没有回滚的共享,等于给全组发不可撤回的插件。 - 本地与 CI 跑同一条命令:文档给出复制即用的
python3 scripts/validate_skill.py,推 PR 前本地先跑。本地绿、CI 红,先查路径与工作目录,再怀疑脚本;路径约定写进脚本顶部注释,别靠隐式当前目录。 - 命名一致、改名两步走:目录名、frontmatter
name、文档标题保持一致,减少「加载了 A 以为是 B」。重命名算破坏性变更:先禁用旧名再加新名,别直接改名让旧对话全漏触发。 - 跨仓库只建一个源仓:多个产品仓要同一 Skill 时别复制四份——description 会漂移,failures 计数也无法共用。抽一个 skills 源仓,用 submodule、包发布或只读同步 bot 拉取;源仓同样走本课 CI,bot 不在产品仓里「智能改写」。
- CI 资源按 lint 申请:和平台组沟通时,把它说成「和 lint 同类的便宜门禁」:秒级、无外部网络、失败信息可读。拉模型跑评测是第 6 课的事。没有 GitHub Actions 就挂进 Jenkins / 自建 runner,规则不变:skills 路径变更就跑,失败阻断合并。
- 合并后 24 小时抽检:值班人抽三条真实对话,看触发是否与 failures 预期同向。误触发暴涨时先禁用再开 issue,别「再改改 description 顶上」——共享环境里先止血。
字段名以你安装版本的 Claude Code skills 官方文档为准;本文示例若有出入,按文档校正。文档会变,「合并前要红过一次」这条不怎么变。
Errors and Setbacks (At Least Three)

- CI 只校验 Markdown 语法,不校验 frontmatter:结果空 description 也能合。处理:显式解析 frontmatter 字段,空值即失败。
- 共享目录变成「第二份家目录」:有人把整机配置、API 密钥、个人笔记塞进 skills。处理:CI 扫密钥形态;PR 拒收与 Skill 无关的大文件;密钥只走密钥柜。
- 自动 push 回写:有「好心」job 在 CI 里格式化并提交,把未审 description 写进 main。处理:skills 流水线只读;写回必须人工或单独受控 workflow 且要审批。
- 同名 Skill 覆盖:两个人都叫
weekly-report,后合并的静默赢。处理:name 唯一门禁 + 目录名与 name 一致。 - 路径过滤写错,job 永远不触发:目录放在
.claude/skills/,CI 的 paths 却写成skills/**,改了也不跑,大家还以为一直绿。处理:paths 与真实入口逐字对齐,并用一次故意的红灯 PR 证明它真的会触发。 - 只在 main 上跑:触发条件只写了 push 到 main,PR 阶段没有校验,合并后才红。处理:触发条件加上 pull_request,并在分支保护里把这一步设为必过检查。
- 跳过 failures 计数:「先合进去再测」。处理:PR 模板硬拦;没有前后数字的 description 变更,评审直接请求修改。
课堂里还有一个隐蔽翻车:有人把第 3 课的脚本权限在进共享时一并放宽,「反正 CI 过了」。CI 过的是结构,不是运行时权限。运行时仍要沿用第 3 课的安全审计与第 4 课的触发边界——两层都不能因为「进仓库了」就放松。动作:把第 3 课的审计清单链接写进共享目录 README 顶部。
Exercises
选你在第 4 课打磨过的一个 Skill,完成:
- 按本课目录约定放进示例仓库分支;
- 加上
validate_skill.py(或同能力 shell)并在 CI 跑通一次失败用例(故意清空 description,看红灯)再跑通一次绿灯; - PR 描述粘贴 failures 置顶计数与 git tag 名;
- 写三行
CONTRIBUTING-skills.md:入口路径、禁止事项、值班同步方式。
交作业最低标准:有红灯截图或日志、有绿灯日志、SKILL_CI_OK、PR 三问都有答。缺红灯证明的「我写了脚本」,不算完——没见过红灯的门禁,多半是没挂上。
课堂验收再加一条:能当场说出这个 Skill 的禁用方式。口才好但没有红灯日志的,重做。
互评:两人交换,故意给对方提交空 description,看对方 CI 是否真红。发现「脚本在但 job 没挂」的,当场补挂——互评比自测更能抓到「我以为挂了」。
时间盒九十分钟:三十分钟搬目录与写校验,三十分钟挂 CI 并制造红灯,三十分钟写 PR 三问与禁用方式。时间更紧就只做「清空 description → CI 红」这一条,绿了再补 SOURCE.md 与唯一名检查。
Preview of the Next Lesson
第 6 课预告:Skill 评测集与回归清单——把第 4 课的 failures 与本课的 CI 门禁,收成可重复跑的评测集:固定对话片段、固定模型与 Skill 集合、发布前必跑。共享目录解决「放哪」,评测集解决「变好还是变坏」。下一课会要求你带上本课的 SKILL_CI_OK 日志与 failures 摘要。
Table of Contents for This Series
- Lesson 1: Write Your First Claude Agent Skill That Triggers Automatically in 30 Minutes — https://school.myshirtai.com/archives/3378
- Lesson 2: Adding a Reference to Skill / Validation Loop for “Write the Plan First, Then Execute” — https://school.myshirtai.com/archives/3462
- Lesson 3: Scripted Skills and Security Audits — https://school.myshirtai.com/archives/3521
- Lesson 4: Iterating Using Real-World Failure Cases description — https://school.myshirtai.com/archives/3661
- 第 5 课:把 Skill 接到真实仓库 CI / 团队共享目录(本文)
系列名:Claude Agent Skill 实战。
收尾动作:今晚定目录、挂一条会红的校验、用第 4 课的 Skill 走一次 PR 三问。个人目录里的漂亮 description,进不了共享与 CI,就还是自嗨。能在团队仓库里亮起 SKILL_CI_OK,你才算把 Skill 当成工程工件,而不是聊天附件。


Comment List (0):
Load More Comments Loading...