Codewhale Skills 管理器解析SKILL.md 指令包的四层架构、所有权模型与操作实践【免费下载链接】CodewhaleOpen-source coding agent for your terminal, built in Rust and on a journey of continuous community improvement. Issues and PRs welcome.项目地址: https://gitcode.com/GitHub_Trending/de/Codewhale本指南以 Codewhale 仓库中的 Skills Manager 说明文档 为核心骨架系统讲解其可复用SKILL.md指令包从磁盘发现、审计、变更到模型调用的完整生命周期。你将掌握 Codewhale 中哪些技能目录可写、哪些只读兼容、/skills与/skill命令的准确语义、Skills Manager 的全部按键操作、随附技能目录的分层规则以及invocation/aliases-for等 frontmatter 字段如何影响模型的上下文路由。文中所有结论均可在 crates/tui/src/skills/ 及其随附资产中找到源码与测试佐证。Codewhale 官方简体中文版见 zh_hans/SKILLS.md关于 Claude Code 插件边界、skills_dir与[skills]配置键请分别参阅 CLAUDE_PLUGIN_COMPAT.md 与 CONFIGURATION.md。Skills 的本质可复用的 SKILL.md 指令包在 Codewhale 中Skill 是可复用的SKILL.md指令包——每个技能是一个目录内含带 frontmatter 的SKILL.md正文。Codewhale 从多个根root发现这些指令包但只有 Codewhale 自有的目录是可写的统一的/skills管理器是审计与变更的交互入口而斜杠别名slash alias与它共享同一条写路径。docs/skills/目录下的gh-*系列与codew-release-qa-sweep属于仓库维护与发布运维辅助技能不在最终用户入门技能包内、不会被自动安装详见后文仓库运维技能边界一节。四层架构职责分离的设计基石Skills 子系统在逻辑上被严格切分为四层每层职责单一、权限边界清晰层Layer职责RoleRoot catalog根目录目录优先级与所有权唯一权威SkillRootCatalog。Audit审计只读、不合并的磁盘盘点状态、digest、可执行动作。Mutation controller变更控制器install / import / update / remove / trust 的唯一写入者。Skills manager view管理器视图TUI 层只发射事件自身绝不写文件。源码中根目录枚举与所有权逻辑集中在 roots.rsSkillRootCatalog::build一次性构建自有 兼容 可选配置目录 逻辑源的完整目录并用递增的precedence表达低值高优、先到先得的运行期合并顺序见 roots.rs 中SkillRootDescriptor.precedence字段的注释SkillRootAccess枚举把每个根标记为WritableOwned/ReadOnlyExternal/Immutable/CacheOnly从类型层面杜绝把只读外部根当成写目标的实现漂移注释明确指出Discovery directories are not write targets: only explicitly owned CodeWhale roots are writable即运行期发现目录并不是写目标。一个关键设计取舍体现在文档中运行期发现SkillRegistry会把各根合并后交给模型而Audit 刻意不合并——它展示磁盘上的每一份拷贝让冲突与遮蔽shadowing保持可见。审计是未合并盘点这是排查同名技能问题时最直接的入口。所有权与根哪些目录可写、可发现、可审计Codewhale 将技能根分成三类访问语义每类的处置策略都不同。可写Codewhale 自有范围路径项目Projectworkspace/.codewhale/skills/全局Global~/.codewhale/skills/源码实现与文档一致在 roots.rs 中项目自有根为workspace.join(.codewhale).join(skills)全局自有根为home.join(.codewhale).join(skills)二者均以SkillRootAccess::WritableOwned、include_even_if_missing true注册——因为自有目标可能尚未创建但将来要写入。owned_writable_roots()方法专门返回这两类可写根。只读兼容仅作发现 / 导入来源绝不就地变更常见外部布局示例包括workspace/.agents/skills、./skills、.claude/skills、.cursor/skills、.opencode/skills、~/.agents/skills、~/.claude/skills及其他同类 harness 布局。源码层面 roots.rs 的CompatibleHarness枚举明确登记了这些外部 harnessAgents、Claude、Cursor、OpenCode、Codex、DeepSeekLegacy~/.deepseek/skills以及扁平的workspace/skillsFlatProjectSkills。这些根统一以ReadOnlyExternal注册能出现在发现与审计中但不允许被变异——如果同一技能只存在于兼容外部根下写入会被拒绝正确做法是走/skills导入到自有根而不是手工编辑 harness 目录。仅审计不参与运行期发现.codex/skills会出现在compatible审计扫描中供运维人员查看但不进入运行期发现集合。在 roots.rs 中Codex 项目与全局根均以active_for_runtime false, active_for_audit true注册代码注释注明audit-compatible only; never active for runtime。读者若用过 Codex可借此一眼看出两种工具对.codex/skills的语义差异。配置目录skills_dir的特殊性若配置的skills_dir并非自有根路径则该目录保持只读发现与管理器可以列出它但所有变更仍只指向自有的项目 / 全局根。classify_configured_skills_dir见 roots.rs 导出的工具函数正是用于判断配置目录归属的辅助逻辑。斜杠命令/skills 与 /skill 全解文档列出了完整的命令面。这里是完整的继承表并附带语义说明命令行为/skills打开 Skills Manager自有目录扫描无网络。/skills prefix按名称前缀过滤的文本列表。/skills inspect文本式发现模式展示搜索过的目录与来源路径。/skills --remote显式列出注册表网络。/skills suggest task针对任务为最多三个远程技能排序给出匹配证据与一条显式安装命令网络不安装。/skills sync显式注册表 → 本地缓存同步网络。/skill name为下一轮激活某个技能。/skill install [--project\|--global] spec通过变更控制器安装。/skill update [--project\|--global] name依据注册表出处registry provenance更新受管技能。/skill uninstall [--project\|--global] name移除受管技能。/skill trust [--project\|--global] name写入绑定 digest 的咨询性信任标记。补充语义原文档明确强调实操极易踩坑不存在/skills audit子命令。需要审计信息时使用管理器并按c切换是否包含兼容根或用/skills inspect查看发现细节。裸/skill install spec不带作用域标志默认安装到 Codewhale全局自有根。/skills suggest只通过既有网络策略读取精选注册表它从不下载、信任、启用或激活任何技能每条结果都会给出一条独立的/skill install name命令供用户自行决定。若同一名称同时存在于项目与全局自有根update / uninstall / trust 都必须显式加--project或--global。若某名称只存在于兼容外部根下写入会被拒绝——应通过/skills导入而不是直接编辑 harness 目录。Skills ManagerTUI按键与事件驱动模型默认打开方式输入/skills并确认。界面在打开时为零网络状态仅做自有目录审计。按键映射如下按键动作↑/↓或j/k移动选择Enter触发当前可用主动作 / 确认待处理提示i导入外部 → 自有u更新受管 注册表出处r移除受管先确认t信任受管绑定 digests切换导入目标project ↔ globalc切换扫描范围自有目录 ↔ 兼容目录仍只访问本地磁盘Esc取消确认或关闭管理器事件驱动模型是这套 UI 的安全保证视图层从不调用安装辅助函数、不触碰文件系统。它只发出一个变更请求宿主进程运行变更控制器、展示回执receipt再重建审计清单。这与四层架构表中Mutation controller 是唯一写入者互为印证——TUI 只是一个指令发射器。随附技能目录双层级打包策略Codewhale 把随产品发布的技能压缩成两个紧凑层级避免代理工作流被文档与集成辅助技能淹没Core agentic核心智能体工作流——规划、实现、调试、评审、验证、委派、Fleet、发布以及best-of-n对比工作流。Format tooling格式与工具链——文档格式、数据可视化、前端与 Web 测试以及 skill / plugin / MCP 编写辅助。工作区、用户与兼容 harness 的技能始终标记为customCodewhale 不会凭名称猜测它们的用途。源码层面 system.rs 给出了打包的实现证据BUNDLED_SKILL_VERSION 10并在注释中记录了从 generation 1 到 10 的演进generation 7 加入 explicit-only 的help路由、generation 8 加入contributor-onboarding、generation 9 加入handoff、generation 10 加入mcp-discovery每个技能正文通过include_str!(../../assets/skills/name/SKILL.md)在编译期嵌入二进制BUNDLED_SKILLS表逐一声明名称、正文与引入世代实际技能内容存放于 crates/tui/assets/skills/共 40 个目录例如plan、implement、debug、test、review、verify、research、delegate、fleet-manager、best-of-n、handoff、document、dataviz、docx、pdf、pptx、xlsx、skill-creator、plugin-creator、mcp-builder、help等另有documents/presentations/spreadsheets这类纯别名包。还有一个值得注意的克制原则随附包不会宣称运行时不具备的能力。例如 Codewhale 具备图片理解能力但图片生成技能不会被捆绑——直到真正存在图片生成工具为止。详见下文 starter-pack 对等决策。仓库运维技能边界仓库维护与发布运维类辅助技能gh-*系列技能以及docs/skills/下的codew-release-qa-sweep不属于最终用户的入门技能包永远不会被自动安装catalog-matrix 测试固化pin了这一边界。把它们作为可选 bundle 发布属于插件交付工作在仓库中单独跟踪对应 issue #4836。调用与别名元数据frontmatter 中的路由字段随附技能与用户技能可在 frontmatter 中声明两个运行期路由字段字段含义invocation: modeluser默认值技能出现在模型的紧凑目录中可被模型或用户加载。invocation: explicit-only技能仍可按显式名称加载但从模型目录中省略避免选择加入的指令变成环境上下文。aliases-for: name, other-name为同一个规范技能提供额外查找名别名不是独立目录条目不会复制 prompt 内容。路由规则的确定性行为均有源码/测试约束缺失或未知的 invocation 值沿用历史默认modeluser发生冲突时规范名优先于别名加载技能时报告其规范 invocation 与别名保证回执可核查。随附的help技能正是invocation: explicit-only的实例——它的 SKILL.md frontmatter 第 4 行即为invocation: explicit-only。Starter-pack 对等决策哪些参考技能被收录、映射或排除v0.9.2 对等审计对应 issue #4698将五个参考技能与实际 Codewhale 技能包逐一对照。文档强调这是一张决策矩阵而非照抄参考文本或宣传不支持的工具的请求参考技能Codewhale 决策运行期锚点check-work规范别名/兼容映射为verifyverify是随附的证据收集工作流。code-review规范别名/兼容映射为reviewreview是随附的只读正确性工作流。create-skill规范别名/兼容映射为skill-creatorskill-creator是随附的技能编写工作流。help有界的invocation: explicit-only路由器而非环境手册路由到/help、/skills、/config、doctor与已安装的docs/树正文不嵌入任何手册文本。imagine有意排除在范围外Codewhale 没有图片生成/编辑工具入门包不得宣传其一。两个非别名决策的额外细节help作为随附技能generation 7发布但为explicit-only因此永远不出现在模型目录中环境 prompt 成本为零。它的正文是一张路由卡——哪个界面拥有哪类事实——并且显式禁止把命令清单或设置表粘贴进上下文。一项被测试固定checked的不变量使其保持在 80 行以内并要求其点名/help、/skills、/config与doctor四个界面。imagine坚决不收。随附运行时只暴露图片理解而非生成/编辑所以任何随附技能都不得宣传该能力catalog-matrix 断言imagine、image、image-gen三个名字不在技能包中且解析不到任何东西。此兼容切片没有复制任何参考技能正文。显式别名与 invocation 元数据是有界路由事实完整的技能正文仍然只通过load_skill进入上下文。Catalog fixture matrix免 Provider 的契约测试文档与源码共同说明了一类无模型、无 Provider的确定性测试。期望表位于 crates/tui/assets/skills-catalog-matrix.json它是人工编写的期望表覆盖每个随附技能规范名、层级、invocation、别名、是否渲染为环境目录条目以及哪些别名被其他规范名遮蔽。catelog_matrix.rs 测试 断言该 fixture 与BUNDLED_SKILLS之间存在双射——随附技能包的任何变化都必须同步更新 fixture否则测试失败。测试把随附技能包安装进临时目录并按真实用户方式发现见installed_registry()辅助函数全程无网络、无 Provider、无环境主目录且断言随附包必须无警告解析。这些测试能与不能声称什么文档划分得非常清楚它们验证确定性的注册表 / 目录 / 解析器行为安装、解析、资格判定、显式加载、非激活、别名解析、explicit-only 排除、冲突优先级与 prompt 预算。它们不验证任何有关语义 LLM 路由的内容模型拿到一段堆栈是否选择debug是线上 Provider 才有的问题见 LIVE_SMOKE.md。当前被断言的关键不变量不变量含义规范名胜出Canonical wins规范随附名永远胜过另一技能的别名docx→docx绝不会命中documents。单别名校主Single alias owner任何两个随附技能不得声明同一别名。无重复条目No duplicate entries每个规范名最多渲染一行目录别名渲染零行。预算余量Budget headroom仅随附技能包渲染即低于MAX_AVAILABLE_SKILLS_CHARS2 400 字符不会出现additional skills omitted提示行——用户技能绝不会被静默挤掉。无上下文投毒No context poisoning描述保持单行并在进入 prompt 前被截断至MAX_SKILL_DESCRIPTION_CHARS280以内。从 mod.rs 可以读到 prompt 预算的底层计算环境技能索引最多占用路由上下文窗口的 5%SKILL_BUDGET_CONTEXT_PERCENT按 4 字符/token 估算并夹在 2 400 字符下限MIN_AVAILABLE_SKILLS_CHARS与 40 000 字符上限MAX_AVAILABLE_SKILLS_CHARS_CEILING之间当窗口缺失时默认按 128k token 计算。也就是说环境技能索引是路由元数据而非工作本身其预算会随模型上下文窗口伸缩窗口越大的路由可获得越多的技能列表空间。本地化路由元数据15 种语言的确定性回退frontmatter 支持description_tag字段解析顺序为精确 tag → 主次 sub-tag → 规范描述其中繁体中文不参与简体zh的回退。当前没有任何随附技能附带本地化路由描述也不会凭空捏造——因此随附包的契约是一个显式、可测试的回退对技能包中的每个技能 × localization.rsLocale::shipped()中的每个区域共 15 个en、ja、zh-Hans、zh-Hant、pt-BR、es-419、vi、ko、ca、de、fr、id、hi、ru、uk见 localization.rsdescription_for_locale一律返回规范英文描述渲染出的目录块在所有随附区域之间逐字节一致精确 tag 匹配、主次 sub-tag 回退如pt-BR→description_pt与英文回退均用一份合成的作者化 fixture 覆盖因此即使在技能包纯英文的当下解析路径也始终处于测试之中。若未来某个随附技能真的带上了本地化路由元数据对等测试会立即失败直到为其补上源码级覆盖——回退契约不能静默吞掉一种翻译。审计状态机Active / Shadowed / Duplicate / Conflict审计的每一行都会携带优先级与关系标志状态含义Active活跃扫描中该规范名优先级最高的那份拷贝。Shadowed被遮蔽同名存在于更高优先级根下。Duplicate重复规范名与包 digest 均与另一份拷贝相同。Conflict冲突规范名相同、包 digest 不同。对没有自有副本且 digest 有效的外部技能它们成为import 候选。与自有副本冲突或完全重复的外部技能仍可提供 Import——重复时提示已存在冲突时则在所选导入范围内确认是否替换。出处与标记文件.installed-from 与 .trusted受管安装会在技能目录下写入 schemav2元数据。.installed-fromv2——在 install/import 成功时最后写入{ schema_version: 2, spec: github:owner/repo, url: https://…, source_checksum: …, content_digest: …, installed_name: my-skill, registry_version: null }content_digest是整个包树的有界哈希并非仅对 SKILL.md 求哈希URL 展示时会剥离 userinfo、query 与 fragment导入使用本地的import:…出处无法从注册表更新——要么重新导入要么移除它旧版 v1 标记会被识别为受管其完整性标记为LegacyMetadataUnknown直到刷新为止。.trustedv2——咨询性、绑定 digest{ schema_version: 2, content_digest: … }信任记录的是已评审这一意图。它不会对技能做沙箱隔离也不会自动批准工具调用。内容更新会清除信任——过期标记不能比字节活得还久。手工技能位于自有根、但没有受管标记可见但不可通过受管动作执行 update / remove / trust。包 digest 与安全边界Audit 与 mutation 共享同一个有界包 digest安全设计要点仅含常规文件逃逸技能根的符号链接或成环链接 → 关闭失败fail closed对总大小、文件数与深度设有上限变更在写入前重新校验期望 digestTOCTOU 防护import / 替换操作先保留.bak直到 digest 与标记全部落盘成功任一步失败都会恢复先前的自有包。Readiness为未来缓存预留的钩子审计模型带有一个 readiness 字段并为未来的 readiness 缓存预留了可选的 Provider 钩子对应 issue #4407。当前未接线任何缓存时readiness 恒为Unknown。管理器不会运行 readiness 探测也不会因 readiness 而阻塞任何变更。配置项skills_dir 与 [skills]# 可选覆盖发现偏好除非恰为 Codewhale 项目/全局自有路径 # 否则不会自动成为写目标。 skills_dir /path/to/skills [skills] # 为 true 时运行期发现跳过跨工具根.claude、.agents、…。 # Codewhale 自有根与显式 skills_dir 覆盖仍然生效。 scan_codewhale_only false # --remote、sync 与 install 使用的可选注册表/安装大小覆盖。 # registry_url https://… # max_install_size_bytes 5242880对应常量可在 crates/tui/src/skills/install.rs 找到DEFAULT_MAX_SIZE_BYTES与DEFAULT_REGISTRY_URL等默认值经 skills/mod.rs 统一导出给下游消费。scan_codewhale_only的实现锚点是 roots.rs 的runtime_directories(workspace, mode)当模式为CodeWhaleOnly时只保留CodeWhaleProject、CodeWhaleGlobal与Configured三类根项目自有根还会额外做工作区包含性检查防止符号链接逃逸。完整配置面请参见 CONFIGURATION.md。运维检查清单把以上所有机制落到日常操作上文档给出五条建议日常管理优先使用/skills把--remote/sync保持为显式操作。永远不要手工编辑.claude/.agents/.cursor目录来为 Codewhale 安装——请导入到.codewhale/skills。把.trusted当作已评审的咨询性文档而不是安全边界。注册表内容更新后若仍希望保留该咨询标记请重新 trust。同名技能同时存在于项目与全局根时CLI 变更必须显式携带作用域标志。结语Codewhale 的 Skills 子系统用Root catalog 唯一权威、Audit 只读不合并、Mutation controller 唯一写入、TUI 只发事件的四层约束把技能的管理安全性与模型侧的路由效率分开治理explicit-onlyinvocation、digest 绑定信任、包树哈希与无 Provider 的 catalog-matrix 契约测试则分别回答了何时进入模型上下文如何证明内容来源怎么防止目录与技能包漂移三类问题。想继续深入可在仓库中直接研读 docs/SKILLS.md 的配套文档、crates/tui/src/skills/ 的完整实现roots、audit、mutation、install、recommend、system 等模块、crates/tui/assets/skills/ 的真实技能包以及用 crates/tui/assets/skills-catalog-matrix.json 对照理解契约测试的断言边界。【免费下载链接】CodewhaleOpen-source coding agent for your terminal, built in Rust and on a journey of continuous community improvement. Issues and PRs welcome.项目地址: https://gitcode.com/GitHub_Trending/de/Codewhale创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
