统一技能仓库：数据团队如何向AI编码代理传递代码规范

一个技能仓库，服务所有 AI 代理：我们的数据团队如何将约定传递给 Claude Code、GitLab Duo、OpenCode 和 Snowflake CoCo

我的数据团队有五名工程师。一个用 Claude Code，一个偏好 OpenCode，一个用 GitLab Duo 的 CLI，一个用 Snowflake CoCo，而最新入职的同事可能会带来第六个还没人听说过的工具。

这些代理中的每一个都能快速编写 Python。而且它们每一个，开箱即用，写出的 Python 都无法通过我们的 CI。

不是因为代码质量差。而是因为代理不知道我们的 CI 运行着较旧的 pylint，它会以神秘的 E0012 bad-option-value 错误拒绝 disable-next 注释。它不知道我们的测试文件与源代码放在一起，而不是放在共享的测试目录中。它不知道我们流水线中的两个格式化任务是关键阶段，因此一个失败会导致所有下游任务都被清除。

这些知识以前存在于三个地方：一个没有代理会阅读的手册页面、高级工程师的头脑，以及合并请求审查线程中，在那里同样的评论会被写下第一百次。

我们把它移到了第四个地方，而另外三个就不再重要了：一个中央的 Agent Skills git 仓库，团队中的每个 AI 工具都使用它。

问题：你的约定在你的手册和你的代理之间的鸿沟中消亡

AI 编码代理是在整个互联网的 Python 上训练的。你的团队不编写整个互联网的 Python。你编写的是带有特定 pylint 禁用列表、特定测试布局、特定 make 目标的 Python，这些目标精确地镜像了 CI。

标准的解决方案一直是个人提示文件。每个工程师管理自己的指令，各自独立地学习每个陷阱，并将其编码在只有自己能看到的配置中。团队的知识分散在五个主目录中。当 CI 镜像升级或约定发生变化时，五个私有提示会悄然失效。

解决方案：Agent Skills，像代码一样管理

Agent Skill 是一种故意简单化的技术。它是一个包含 SKILL.md 文件的文件夹：带有少量 YAML frontmatter 的 Markdown 指令。名称和描述字段是必需的，而描述承担了重任，因为代理是根据它来决定何时加载技能。

---
name: python-ci-gates
description: Pre-push checklist of the CI gates that block Python
  merges in data-team repos. Lists the local commands that mirror
  each CI job, the critical-stage cascade, and the pylint version
  trap. Use before staging, committing, or pushing any .py change.
---

## What I do
Catalog the CI jobs that gate Python merges, the make targets
that mirror them locally, and the pylint version trap that
catches every new contributor...

其机制是渐进式披露。在会话开始时，代理只将每个可用技能的名称和描述加载到上下文中。当你的任务与描述匹配时，代理就会拉入完整的正文。空闲时成本低，相关时内容丰富。

这是改变我们团队工作方式的部分：这种格式正在成为跨供应商的标准。同一个 SKILL.md 文件可以被 GitLab Duo Agent Platform、Claude Code、OpenCode 和 Snowflake CoCo（Snowflake 为数据生命周期构建的 AI 原生编码和开发代理）理解。GitLab 的文档也列出了 Codex 和 Gemini CLI 作为兼容工具。

多个工具可以读取的 Markdown 文件。管理它只有一种正确的方式：一个带有合并请求审查的 git 仓库。

运作方式：一个仓库，两条规则，扁平名称

我们的中央仓库有一个简单的契约。如果一个技能用于多个仓库的开发，或者它不属于任何一个特定仓库但有助于更广泛的团队，那么它就属于这里。

data-team-agentic-skills/
├── README.md
├── shared-dev-workflows/
│   ├── conventions/
│   │   ├── python-style/SKILL.md
│   │   ├── python-ci-gates/SKILL.md
│   │   └── python-testing/SKILL.md
│   ├── gitlab-workflow/
│   │   ├── ci/trigger-ci-pipeline/SKILL.md
│   │   └── mr/update-mr-with-testing-results/SKILL.md
│   └── snowflake-infrastructure/
│       └── snowflake-oauth-integration/SKILL.md
└── non-dev-workflows/

技能是小的且可组合的，而不是庞大单一的。我们的 Python 指南最初是一个巨大的技能，审查反馈将其拆分为三个：python-style（约定和惯用法）、python-ci-gates（精确镜像 CI 的命令以及版本陷阱）和 python-testing（测试布局、命名以及破坏 pytest 收集的 __init__.py 冲突）。每个都相互引用，因此代理只加载任务所需的内容。

我们在审查中学到的一条硬性规则：叶目录名称在整个仓库中必须唯一。每个工具都通过该名称识别技能，因此重复的名称会静默地遮蔽另一个技能。

接入你选择的工具

这是收获部分。一次克隆，然后每个工具都用自己的方言指向它。下面每条命令都在真实机器上验证过，而不是从文档中转录的。

OpenCode会递归发现技能，因此整个仓库的一个符号链接就可以工作：

git clone [email protected]:your-group/your-skills-repo.git ~/repos/skills
mkdir -p ~/.config/opencode/skills
ln -s ~/repos/skills ~/.config/opencode/skills/team-skills

当前的 OpenCode 构建也会读取兼容 Claude 的 ~/.claude/skills/ 和跨工具的 ~/.agents/skills/ 位置，这一点稍后会很重要。

Claude Code从 ~/.claude/skills/ 加载，并且期望每个技能一个目录。它不会搜索嵌套的子目录，因此要构建一个扁平的符号链接农场：

mkdir -p ~/.claude/skills
find ~/repos/skills -not -path '*/.git/*' -name SKILL.md | while read -r skill_file; do
  skill_dir=$(dirname "$skill_file")
  ln -sfn "$skill_dir" ~/.claude/skills/"$(basename "$skill_dir")"
done

当新的技能加入时，重新运行该循环。使用 -sfn 标志使其幂等。

GitLab Duo CLI从 ~/.gitlab/duo/skills/（以及跨工具的 ~/.agents/skills/）读取用户级技能，但需要实验性标志，该标志随 GitLab 19.0 和 Duo CLI 8.83.0 引入。相同的循环，不同的目标：

mkdir -p ~/.gitlab/duo/skills
find ~/repos/skills -not -path '*/.git/*' -name SKILL.md | while read -r skill_file; do
  skill_dir=$(dirname "$skill_file")
  ln -sfn "$skill_dir" ~/.gitlab/duo/skills/"$(basename "$skill_dir")"
done
glab duo cli --enable-global-skills

或者在 shell 配置文件中一次性导出 GITLAB_ENABLE_GLOBAL_SKILLS=true。在会话内，/skills 会列出它找到的所有内容。对于 GitLab UI 中的 Duo Agent Platform 流程，技能则来自正在操作的仓库中的项目级 skills/ 目录。

Snowflake CoCo拥有一流的技能管理，而优雅之处在于：你不需要第三份副本。CLI 二进制文件仍然是 cortex，所以将它指向你已经为 Claude Code 构建的扁平符号链接农场：

cortex skill add ~/.claude/skills
cortex skill list

CoCo 会持久化该目录，并通过它发现每个符号链接的技能。一个符号链接农场现在为两个工具提供支持，当你拉取仓库时，两者都会拾取更改。CoCo 甚至可以将技能发布到 Snowflake stage，以便在你的数据平台内部分发。

每个代理在哪里查找技能以及如何连接：OpenCode 从单个符号链接递归读取 ~/.config/opencode/skills/，Claude Code 希望通过符号链接循环在 ~/.claude/skills/ 中每个技能一个平面目录，GitLab Duo CLI 读取 ~/.gitlab/duo/skills/ 或 ~/.agents/skills/ 使用符号链接循环加上实验性标志，而 Snowflake CoCo 扫描您使用 cortex skill add 注册的任何目录的直接子目录。

对于喜欢文本形式的读者：

• OpenCode：查找 ~/.config/opencode/skills/，递归发现，因此整个仓库的一个符号链接就足够了。
• Claude Code：查找 ~/.claude/skills/，希望每个技能一个平面目录，因此使用符号链接循环。
• GitLab Duo CLI：查找 ~/.gitlab/duo/skills/ 或 ~/.agents/skills/，每个技能一个目录，符号链接循环加上实验性标志。
• Snowflake CoCo：查找您注册的任何目录，扫描其直接子目录，因此使用 cortex skill add 注册您现有的农场。

治理循环：由人类和 AI 审查的技能

因为技能是代码，它们需要经过合并请求。这听起来像是流程开销。实际上，这是价值复合增长的地方，因为技能 MR 在某人阐述知识的确切时刻捕获了知识。

审阅者评论“我们的 CI pylint 较旧，这个禁用注释会破坏流水线。”这个见解不会在已解决的线程中蒸发，而是成为 python-ci-gates 中的三行，从那天起，团队中的每个代理都知道它。

我们也亲自试用审查本身。GitLab Duo 与人类审阅者一起审查我们的技能 MR，它赢得了自己的位置。在记录这个设置的 MR 上，Duo 的审查发现了我们符号链接循环中的一个真实边缘情况（两个共享叶目录名的技能会静默覆盖彼此），建议从 find 命令中修剪 .git/，并质疑了一个 CLI 标志，然后我们针对工具自身的帮助输出验证了该标志。每一个发现都在人类合并之前使最终版本更好。

采用路径：从您最常听到的三条审查评论开始

您不需要平台倡议。以下是对我们有效的分阶段路径。

1. 创建一个仓库。两个顶层文件夹：共享的开发工作流，其他所有内容。
2. 选择您的团队最常写的三条审查评论。将每条转化为技能。我们的是风格约定、CI 门禁和测试布局。
3. 将描述写成路由器规则，而不是营销文案。“在推送任何 .py 更改之前使用”可靠触发。“有用的 Python 提示”从不触发。
4. 将符号链接说明添加到仓库 README 中，以便任何工具设置都是两分钟的复制粘贴。
5. 将所有技能更改都通过 MR 审查，并让您的 AI 审阅者也参与其中。
6. 当约定改变时，更改技能。每个工程师的每个代理将在下一次 git pull 时更新。

诚实地说说局限性

标准很年轻，这很明显。发现语义因工具而异：OpenCode 递归，Claude Code 希望平面目录，CoCo 仅扫描直接子目录，这正是符号链接农场存在的原因。Duo CLI 的全局技能标志明确是实验性的，GitLab UI 中的技能目前适用于 Agent Platform 流程而非 Duo Chat。当新技能落地时，必须重新运行符号链接循环，因此它适合作为 shell 别名或 dotfiles 钩子。

技能的好坏取决于其描述。模糊的描述要么永不触发，要么不断触发，两种失败模式都是无声的。为那个字段预留真正的审查注意力。

更大的图景

看看谁在收敛于这个文件格式：Anthropic 创造了它，GitLab 在 Duo Agent Platform 中采用了它，并在自己的 CLI 中捆绑了技能，Snowflake 在 CoCo 中构建了技能管理、技能目录和基于阶段的发布。SKILL.md 文件正在成为 README.md 几十年前的样子：一个如此有用的约定，不支持它看起来像个 bug。

这意味着团队知识正在悄然成为版本化、可审查、可分发的工件。现在这样对待它的团队将更快地入职，减少重复审查，并在不丢失一行累积判断的情况下切换 AI 工具。不这样做的团队将继续向每个新代理重复教授同样的 pylint 陷阱，永远如此。

快速参考

# One-time
git clone [email protected]:your-group/your-skills-repo.git ~/repos/skills

# OpenCode: whole-repo symlink
ln -s ~/repos/skills ~/.config/opencode/skills/team-skills
# Claude Code + Duo CLI: flat symlink farm (repeat per target dir)
find ~/repos/skills -not -path '*/.git/*' -name SKILL.md | while read -r f; do
  ln -sfn "$(dirname "$f")" ~/.claude/skills/"$(basename "$(dirname "$f")")"
done
# Duo CLI: enable user-level skills
export GITLAB_ENABLE_GLOBAL_SKILLS=true   # then: /skills to verify
# Snowflake CoCo: reuse the same farm
cortex skill add ~/.claude/skills && cortex skill list
# Update everything, every tool, every engineer
git -C ~/repos/skills pull

本周将您团队最常重复的审查评论变成共享仓库中的 SKILL.md，让您的队友使用的每个代理免费强制执行它。

一个技能仓库，每个 AI 代理：我们的数据团队如何将其约定传递给 Claude Code、GitLab… 最初发表于 Snowflake Builders Blog: Data Engineers, App Developers, AI, & Data Science 在 Medium 上，人们通过强调和回应这个故事来继续对话。