Trellis CLI Bundled Skills 机制全解：多文件内置技能如何自动分发到各平台 Skill 根目录

桌面应用开发工具【免费下载链接】EcoPaste跨平台的剪贴板管理工具 | Cross-platform clipboard management tool项目地址https://gitcode.com/gh_mirrors/ec/EcoPaste点击查看免费下载bundled-skills.md是 Trellis CLI 本地架构文档中专门讲解「捆绑技能Bundled Skills」分发机制的一篇位于 .cursor/skills/trellis-meta/references/local-architecture/bundled-skills.md。它回答了三个核心问题什么是捆绑技能、trellis init/trellis update如何把它们原样写入每个 AI 平台的技能根目录以及在不改动上游源码的前提下如何新增、覆盖和移除它们。读完本文你将掌握 Trellis v0.6 的技能分发链路listDirectories→resolveBundledSkills→writeSkills→ 模板哈希回写并能安全地在本地定制这些自动分发的技能。本文以该文档为主体骨架并结合本仓库中已部署好的.cursor/skills/实际落盘结果进行印证。什么是 Bundled Skills「捆绑技能」是随 Trellis CLI npm 包一起发布的多文件内置技能。它与市场技能marketplace skills用户自行安装到.claude/skills/或其他平台技能根目录的关键区别在于由trellis init自动写入每个受支持平台的技能根目录并由trellis update保持同步它是 Trellis 自身的一部分而不是第三方内容每个捆绑技能是packages/cli/src/templates/common/bundled-skills/skill/下的一个目录目录内自带带 YAML frontmatter 的SKILL.md以及可选的references/、assets 或其他支撑文件Trellis 将整个目录树原样复制到各平台技能根目录因此references/保持按需懒加载而不会被压平成一份超大的SKILL.md。在本仓库中可以看到这种「多文件 references/」的落盘形态。例如 .cursor/skills/trellis-meta/ 目录下除了SKILL.md还有references/local-architecture/、references/customize-local/、references/platform-files/三组参考文档.cursor/skills/trellis-channel/ 同样带有references/目录。这正是文档所述「references 保持懒加载、按需读取」的部署结果。什么算 Bundled与相邻概念的边界文档用一张表划清了四个层级的分发边界这是理解 Trellis 技能体系的关键源路径类型如何分发templates/common/bundled-skills/name/Bundled skill多文件整个目录复制到每个平台技能根目录templates/common/skills/name.md单文件工作流技能包上 frontmatter写入为root/name/SKILL.mdtemplates/common/commands/name.md斜杠命令 / prompt写入各平台命令目录.claude/commands/trellis/、.cursor/commands/trellis-*.md、.gemini/commands/trellis/*.toml等templates/platform/skills/平台特定技能只写入该平台目录如.codex/skills/用户放在.claude/skills/my-skill/等处的技能Marketplace 或用户自建Trellis 完全不管理Trellis CLI 从不触碰任何不是由它自己的模板加载器产生的文件。用户手工放入平台技能根目录的任何内容都会被原样保留。在本仓库中可以清晰看到这种边界.cursor/skills/下的trellis-meta、trellis-channel、trellis-session-insight、trellis-spec-bootstrap是多文件捆绑技能带references/而trellis-before-dev、trellis-brainstorm、trellis-break-loop、trellis-check是只含SKILL.md的单文件工作流技能符合「单文件技能写入为name/SKILL.md」的描述。.cursor/commands/下的 trellis-continue.md、trellis-finish-work.md 则对应「斜杠命令写入.cursor/commands/trellis-*.md」的分发规则。当前捆绑技能一览v0.6.0技能集合在运行时通过枚举templates/common/bundled-skills/下的目录发现因此增加新目录是注册新技能的唯一必要步骤。v0.6.0 包含四个捆绑技能技能用途trellis-meta本文档所属技能。向在用户项目内工作的 AI 解释本地 Trellis 架构与定制入口点trellis-session-insight封装trellis memCLI让 AI 知道何时以及如何检索过去的 Claude Code / Codex / Pi Agent 对话日志trellis-spec-bootstrap平台无关的工作流从真实代码库创建或刷新.trellis/spec/可选集成 GitNexus / ABCodertrellis-channel能力型技能教 AI 何时使用trellis channel进行多 Agent 协作、论坛/线程持久化看板以及 dispatcher-wait 模式从本仓库的部署结果看这四个技能全部存在于 .cursor/skills/ 中此外还多出一个trellis-update-spec目录说明该项目的 Trellis 版本或后续 release 在此基础上扩展了技能集——这正好印证了文档「列表在运行时发现新增目录即自动注册」的机制上游只要在bundled-skills/下多放一个目录所有已初始化项目就能在下次trellis update时拿到新技能。每个技能的SKILL.mdfrontmatter 用namedescription描述触发时机例如 trellis-session-insight/SKILL.md 的 description 列举了 how did we solve X last time、上次怎么解的、之前讨论过吗 等触发短语这正是平台自动触发机制要匹配的内容。各平台落盘位置每个平台配置器在trellis init期间调用writeSkills(root, workflowSkills, resolveBundledSkills(ctx))。其中resolveBundledSkills读取templates/common/bundled-skills/下每个目录、解析占位符并返回扁平的{relativePath, content}条目列表writeSkills再把它们镜像到该平台的技能根目录下。各平台落盘位置如下平台Bundled skill 根目录备注Claude Code.claude/skills/skill/configureClaudeCursor.cursor/skills/skill/configureCursorCodex.agents/skills/skill/configureCodex写入共享的.agents/skills/根目录Gemini CLI 0.40 也读取该目录Gemini CLI.agents/skills/skill/与 Codex 共享同一根目录两个配置器必须产生字节级一致的输出Kiro.kiro/skills/skill/configureKiro纯技能平台无命令Qoder.qoder/skills/skill/configureQoderCodebuddy.codebuddy/skills/skill/configureCodebuddyCopilot.github/skills/skill/configureCopilotDroid.factory/skills/skill/configureDroidAntigravity.agent/skills/skill/configureAntigravityDevin.devin/skills/skill/configureDevinKilo.kilocode/skills/skill/configureKiloOpenCode由collectOpenCodeTemplates处理使用同一份resolveBundledSkills(ctx)输出Pi、Reasonix各自的 collector同一份resolveBundledSkills(ctx)输出值得注意的两条路径共享同一份数据configureX(cwd)在trellis init期间写入文件collectPlatformTemplates(platformId)位于configurators/index.ts返回MapfilePath, content供trellis update检测漂移并写入.trellis/.template-hashes.json。两条路径必须产生字节级一致的输出因此它们都调用resolveBundledSkills(ctx)和collectSkillTemplates(root, …, resolveBundledSkills(ctx))。本仓库的.cursor/skills/部署正是「Cursor 平台落盘」的实际样例configureCursor将各捆绑技能完整写入.cursor/skills/skill/配合 .cursor/hooks.json、.cursor/agents/、.cursor/commands/共同构成 Cursor 侧的集成文件。分发接线代码路径自动把捆绑技能分发到各平台技能根目录的机制分布在两个文件中1.packages/cli/src/templates/common/index.tslistDirectories(bundled-skills)枚举磁盘上的技能listBundledSkillFiles(skillDir)递归遍历每个技能目录返回每个文件的{relativePath, content}getBundledSkillTemplates()返回缓存的CommonBundledSkill[]。2.packages/cli/src/configurators/shared.tsresolveBundledSkills(ctx)把上述列表拍平成ResolvedSkillFile[]路径形如skill/relativePath并解析占位符writeSkills(skillsRoot, workflowSkills, bundledSkills)在工作流技能之外把捆绑技能文件写入skillsRootcollectSkillTemplates(skillsRoot, workflowSkills, bundledSkills)以MapfilePath, content的形式返回同样的内容供 update / 哈希管线使用。每个支持技能的平台配置器都导入这两个辅助函数见claude.ts、cursor.ts、codex.ts、gemini.ts、kiro.ts、qoder.ts、codebuddy.ts、copilot.ts、droid.ts、antigravity.ts、devin.ts、kilo.ts。index.ts中的PLATFORM_FUNCTIONS注册表也会在每个collectTemplates闭包内调用resolveBundledSkills(ctx)从而保证trellis update的追踪保持一致。新增一个 Bundled Skill分发形状和接线逻辑已经是通用的因此新增技能只需要文件改动加上发布前验证。完整步骤如下1. 创建目录树。packages/cli/src/templates/common/bundled-skills/my-skill/ SKILL.md # YAML frontmatter 正文 references/ # 可选 topic.md assets/ # 可选任何可读为 utf-8 的内容2. 编写合法的SKILL.md头部。frontmatter 至少包含--- name: my-skill description: When the AI should reach for this skill. Triggering phrases go here. ---description是各平台自动触发机制匹配的对象因此应当描述用户意图触发词而不是技能的内部实现细节。3. 适当使用占位符。捆绑技能内容会经过resolvePlaceholders(file.content, ctx)。所有被resolvePlaceholders支持的 token如{{platform_name}}、{{python_cmd}}等都会按平台替换。4. 无需任何分发接线。listDirectories(bundled-skills)会自动发现新目录因此下次trellis init或trellis update时所有平台都会收到它。5. 发布前验证分发路径。历史教训是跳过这些步骤会导致「文档宣称已捆绑但发布的 npm tarball 里根本没有文件」。至少验证被标记的 branch 上源文件确实存在pnpm --filter mindfoldhq/trellis build把资产复制进dist/templates/common/bundled-skills/skill/npm pack --dry-run --json包含预期的dist/**路径在一个全新的临时项目中trellis init写入.claude/skills/skill/SKILL.md、.agents/skills/skill/SKILL.md等.trellis/.template-hashes.json列出了生成的这些文件在该临时项目中执行trellis update --dry-run报告 Already up to date!。6. 如该 release 会被其他项目升级则添加迁移 manifest 条目。没有显式 manifest 条目时文件也会通过trellis update的标准「missing file」分支落盘但 manifest 能让变更在 changelog 中可见。本地覆盖 Bundled SkillTrellis没有「项目级技能」机制例如.trellis/skills/。捆绑技能是平台根目录级的因此任何覆盖也只能是平台根目录级的。官方支持的覆盖模式依赖trellis update已有的模板哈希 diff直接编辑本地文件例如.claude/skills/trellis-meta/SKILL.md该文件的哈希与.trellis/.template-hashes.json中的条目产生差异下次trellis update检测到用户修改后保持文件不变Trellis 不会在未显式加--force时覆盖用户修改过的文件。覆盖时需要注意的坑覆盖只对你编辑过的那个平台生效。例如要同时在 Claude Code 和 Codex 覆盖同一个技能必须分别编辑.claude/skills/name/与.agents/skills/name/未来的trellis update --force会覆盖本地编辑。请把覆盖内容纳入版本控制以便必要时重新应用以不同文件夹名装在同一平台技能根目录下的市场技能如.claude/skills/my-custom-meta/不受 Trellis 影响当目标是增加行为而非改动捆绑技能时这才是更干净的做法团队私有约定应放在.trellis/spec/或单独的本地市场式技能中而不是修改trellis-meta本身参见 customize-local/add-project-local-conventions.md。相关文档 change-skills-or-commands.md 进一步给出了决策表想让 AI 自动知道某项能力就改/加技能想让用户手动触发就改命令/prompt/workflow团队项目约定优先放.trellis/spec/或项目本地技能要改捆绑技能本身应新增一个不同名字的项目本地技能来补充或取代它。一个常见约定是用项目名做前缀如acme-trellis-deploy、acme-trellis-onboarding——因为如果与trellis-meta、trellis-spec-bootstrap、trellis-session-insight、trellis-channel重名getBundledSkillTemplates()会在下次 update 时覆盖项目本地副本。从项目中移除 Bundled Skill捆绑技能没有逐项目的 opt-out 开关。有两种可行方案删除各平台技能根目录中的对应目录。trellis update会发现文件缺失与.template-hashes.json对比后将其视为与其他用户修改一样的处理——除非传入--force否则不会悄悄重建目录。固定一个未携带该技能的 Trellis 版本。捆绑技能集合在构建时确定因此安装较旧版本的 CLI 是唯一能永久排除当前版本所携带技能的办法。第三种方案——全局禁用所有捆绑技能——不受支持。分发在每个配置器中都是无条件的。若真要增加这样一个开关需要修改configurators/index.ts中的PLATFORM_FUNCTIONS以及每一个configureX函数。操作规则把templates/common/bundled-skills/视为「存在哪些捆绑技能」的唯一事实来源不要手工维护各平台的技能清单不要在捆绑SKILL.md内添加平台特定逻辑。行为若与平台相关应放到templates/platform/skills/不要在没有把依赖写进技能 description 与 references 的情况下把捆绑技能耦合到特定 CLI 二进制如trellis mem——旧版本用户可能没有该命令不要往捆绑技能里存放项目私有内容。捆绑技能是公开的、会分发给每个用户的项目规则应放入.trellis/spec/或本地技能。小结Bundled Skills 是 Trellis 让「一份技能、处处可用」得以成立的基础设施上游在packages/cli/src/templates/common/bundled-skills/维护多文件技能目录trellis init借助resolveBundledSkillswriteSkills把它们原样复制到十几个平台的技能根目录trellis update再借助.template-hashes.json检测漂移并尊重用户修改。本仓库的 .cursor/skills/ 正是这套机制在 Cursor 平台上的实际产物多文件捆绑技能携带references/按需加载单文件工作流技能与斜杠命令各归其位。理解这套分发与覆盖规则后无论是往上游贡献新技能还是在本地用「不同名字的兄弟技能」做定制都能在不动 Trellis 源码的前提下安全完成。赞分享桌面应用开发工具【免费下载链接】EcoPaste跨平台的剪贴板管理工具 | Cross-platform clipboard management tool项目地址https://gitcode.com/gh_mirrors/ec/EcoPaste点击查看免费下载相关推荐EcoPaste 中的 Trellis Bundled Skills 机制内置多文件技能如何自动分发到全部 AI 平台EcoPaste 中的 Trellis Bundled Skills 机制内置多文件技能如何自动分发到全部 AI 平台 本文以 EcoPaste 仓库中由 T桌面应用开发工具Trellis Bundled Skills 分发架构全解内置技能如何自动同步到 15 个 AI 平台Trellis Bundled Skills 分发架构全解内置技能如何自动同步到 15 个 AI 平台 本文深入解析 Trellis CLI 的 Bundle桌面应用Trellis Bundled Skills 机制解析内置技能如何在所有 AI 平台自动分发、覆盖与扩展Trellis Bundled Skills 机制解析内置技能如何在所有 AI 平台自动分发、覆盖与扩展 本篇技术指南聚焦 Trellis CLI 中的 Bu桌面应用上一篇ChatLab 本地优先的 AI 聊天记录分析方案从整份丢给大模型到脱敏后按需取数下一篇LinkSwift 网盘直链下载5分钟跑通多网盘直链获取创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考