chrisbanes/skills 深度解析：为 Kotlin 与 Jetpack Compose 而生的 AI 技能集

chrisbanes/skills 深度解析：为 Kotlin 与 Jetpack Compose 而生的 AI 技能集

Chris Banes（长期活跃于 Android 生态、曾任职 Google Android 团队并深度参与 Jetpack 与 Compose 生态）开源了一套面向 Kotlin、Jetpack Compose 与 Android 开发的 AI 辅助技能集 https://github.com/chrisbanes/skills。它把资深 Android 工程师的判断经验，编码成一个个可被 AI 代理（如 Claude Code、Codex、OpenCode）按需加载的"操作规范"文件。本文从技能文件结构、分层路由体系、Compose 与 Kotlin 技能矩阵、端到端工作流，到安装上手，系统拆解它的设计思路与工程价值。

1、概述

chrisbanes/skills 是一套采用 Apache 2.0 协议开源的 AI 技能集，专为 Kotlin、Jetpack Compose 与 Android 开发场景设计。它不提供可运行的库或 SDK，而是提供一组"技能文件"——每个文件描述一类开发任务应当如何判断、如何取舍，供 AI 代理在编码、审查、重构时作为权威参考。

核心特性：

        - 以 SKILL.md 为单位，每个技能对应一个目录，扁平结构

        - frontmatter 的 description 写满触发词，便于 AI 自动路由

        - 采用"路由技能 + 聚焦技能"分层：总览技能把任务导向具体技能

        - 覆盖 Compose 状态/副作用/性能/UI 设计/测试、Kotlin 协程/Flow/控制流/KMP/值类，以及 issue 全流程工作流

        - 支持四种安装方式：skills CLI、Claude Code 插件、Codex 插件、OpenCode 插件

典型应用场景：

        - Compose 屏幕重构与状态分层

        - 协程作用域归属与 Flow 状态/事件建模审查

        - 重组合性能、稳定性诊断与延迟读优化

        - 从 GitHub / Jira / Linear 的一个 issue 一路实现到可合并的 PR

2、技能的本质：SKILL.md 与 frontmatter 约定

整套仓库的基本单元是技能文件。所有技能都遵循扁平目录约定：路径形如 skills/<skill-name>/SKILL.md，目录名即技能名，且必须是 kebab-case；frontmatter 中的 name 字段必须与目录名完全一致。这一约束由仓库根目录的 JSON Schema（skills.schema.json）校验，name 与 description 为必填字段。

以聚焦技能 compose-side-effects 为例，其文件头部 frontmatter 形如：

---
name: compose-side-effects
description: Use when choosing or keying Compose effect APIs such as
  LaunchedEffect, DisposableEffect, SideEffect, rememberCoroutineScope,
  snapshotFlow, for snackbar, navigation, focus requests, analytics,
  or event Flow collection.
---

校验 frontmatter 的 skills.schema.json 核心片段：

{
  "type": "object",
  "properties": {
    "name": {
      "type": "string",
      "pattern": "^[a-z][a-z0-9]*(-[a-z0-9]+)*$"
    },
    "description": { "type": "string", "minLength": 1 }
  },
  "required": ["name", "description"],
  "additionalProperties": false
}

核心约定：

1. 目录名即技能名，必须 kebab-case，与 frontmatter 的 name 完全一致

2. frontmatter 的 name 与 description 为必填，additionalProperties 为 false（不允许多余字段）

3. description 要写清"何时使用本技能"，并尽量铺满触发词——这是 AI 决定是否加载该技能的命脉

4. 正文（frontmatter 之后）才是给 AI 的操作规范，含决策表、BAD/GOOD 代码对比与"常见错误"诊断表，而非给人读的入门教程

3、分层架构：路由技能与聚焦技能

这是整套设计最关键的思想：仓库并不维护一个臃肿的大文档，而是采用"一个路由技能 + 多个聚焦技能"的分层结构。路由技能 using-chrisbanes-skills 明确自我定位为"Router only"——它本身不给具体建议，只负责把任务信号导向最合适的聚焦技能，再由后者在被加载后提供细节。

任务信号到起始技能的常见映射：

        - Compose 状态或副作用工作 → compose-state-authoring / compose-state-hoisting / compose-state-holder-ui-split / compose-side-effects

        - 排查重组合、稳定性或卡顿 → compose-recomposition-performance

        - Flow 或协程架构审查 → kotlin-flow-state-event-modeling / kotlin-coroutines-structured-concurrency

        - 键盘、TV、D-pad 与焦点优先导航 → compose-focus-navigation

        - 可复用组件设计 → compose-slot-api-pattern / compose-modifier-and-layout-style

对于跨多领域的任务，路由技能要求"逐域加载、分别处理"。例如"从 ViewModel 处理事件"这一任务，需要同时加载 UI 拆分、副作用、Flow 建模三个聚焦技能；性能类任务则从 recomposition-performance 入手，再按其指引深入到 stability 或 deferred-reads 子方向。聚焦技能之间还会通过交叉引用彼此联动（如副作用技能会指向 state-holder-ui-split、focus-navigation、state-deferred-reads）。

分层路由的核心收益：

1. 按需加载：AI 只在相关时读取对应技能，避免一次性吞入超长上下文，对 token 与注意力都更友好

2. 单一职责：每个聚焦技能只讲清一件事的判断标准与反模式，可独立演进

3. 可组合：复杂任务通过"路由 + 多技能叠加"覆盖，而非把所有规则塞进一个文件

4. 网络化：聚焦技能之间交叉引用，形成知识网而非线性手册

4、Compose 技能矩阵

Compose 方向是这套技能集的主战场，按"状态与副作用、性能与稳定性、UI 设计与布局、测试"四个子方向拆解。

4.1、状态与副作用

这一组技能解决"状态该放哪、副作用该用哪个 API"两个高频问题。compose-state-authoring 规范本地可变状态与只读 composable 访问器的写法；compose-state-hoisting 给出状态归属的四种去处（本地 remember、提升为参数、plain state holder 类、屏幕级 state holder）；compose-state-holder-ui-split 强调把状态接线与纯 UI 拆开，从而获得可预览、可测试的屏幕。

其中最值得细读的是 compose-side-effects。它的核心原则是：composable 函数体只描述 UI，可能被反复重组、跳过或放弃，因此任何外部工作都必须放到生命周期与之匹配的 Effect API 中。其 Effect 选择映射如下：

        - 把状态发布给非 Compose 代码 → SideEffect

        - 注册 / 注销监听器 → DisposableEffect(keys...)

        - 挂起或带 key 的一次性任务 → LaunchedEffect(keys...)

        - 在用户事件中启动挂起工作 → rememberCoroutineScope()

        - 把快照读转换为 Flow → 在 LaunchedEffect 中使用 snapshotFlow { ... }

该技能特别强调几个隐蔽陷阱：keys 定义"重启身份"，key 变化时旧 effect 取消、新 effect 启动，因此应选择与工作生命周期绑定的稳定语义 key；LaunchedEffect(Unit) 捕获会变化的值（如 userId）是典型反模式；rememberUpdatedState 用于让长周期 effect 拿到最新值而不重启，但绝不能用它来掩盖本应正确设置的 key；把 rememberUpdatedState 的值在 remember { } 块里"提前读"会一次性捕获、永不刷新。

4.2、性能与稳定性

compose-recomposition-performance 是性能问题的总入口，负责把任务路由到稳定性、延迟读或跨阶段回写三个子方向。compose-stability-diagnostics 聚焦诊断：解读编译器稳定性报告、strong skipping、不稳定参数及对应修复。compose-state-deferred-reads 则要求把帧率级的读移出 composition，并避免布局→组合的"跨阶段回写"以及跨行测量引发的性能问题。

4.3、UI API 设计与布局

这一组面向"如何设计出易用、可复用的 Compose API"。compose-modifier-and-layout-style 要求布局 API 保持可由调用方放置（caller-placeable）、modifier 链可读；compose-slot-api-pattern 用调用方提供的 slot 区设计可复用组件；compose-animations 按可见性、目标值、协调过渡、内容切换等场景选择动画 API；compose-focus-navigation 覆盖键盘、TV、D-pad 与焦点优先导航的设计与测试。

4.4、测试

compose-ui-testing-patterns 帮助在多种测试形态间取舍：纯 UI 测试、semantics 语义断言、按键/焦点测试、交互状态测试、截图测试与集成测试，并指明各自适用场景，避免"一律写 UI 测试"的粗放做法。

5、Kotlin 技能矩阵

Kotlin 方向的技能更偏语言层面的判断与建模，覆盖并发、控制流、Flow、函数归属、KMP 与值类六个主题。

主要技能与定位：

        - kotlin-coroutines-structured-concurrency：审查协程作用域归属、init 与即发即弃边界、取消处理与阻塞边界

        - kotlin-control-flow：写与审 when 主题、guard、sealed 穷尽、smart cast、可空分支与提前返回

        - kotlin-flow-state-event-modeling：规范 StateFlow / SharedFlow / Channel / stateIn / 共享策略与一次性事件，避免"有损默认值"

        - kotlin-functions：为成员、顶层、扩展、工厂函数选择正确归属，默认避免对基本/常见类型做扩展

        - kotlin-multiplatform-expect-actual：设计语义化的 expect/actual 与接口边界，服务 KMP 平台互操作

        - kotlin-types-value-class：单字段领域类型优先用 @JvmInline value class 而非 data class，并说明其对 Compose 稳定性的影响

这组技能与 Compose 矩阵呼应——例如 value class 的稳定性、Flow 的事件建模、协程的作用域归属，都会直接回灌到 Compose 屏幕的状态分层与副作用选择中，体现"语言层规范→框架层落地"的连贯性。

6、工作流技能：从 issue 到 PR

implement-issue 与 shepherd 这两个工作流技能，把"技能"从单点建议扩展成端到端流程，是仓库中最具野心的部分。

implement-issue 接收一个 issue 引用（支持 123、#123、namespace/project#123、GitHub/GitLab 完整 URL、Jira 与 Linear 的 URL 或 PROJ-123、jira:PROJ-123、linear:ENG-123 等多种形态），完整走通"解析校验 → 诊断 → 设计规划 → 实现 → 评审验证 → 完成分支"七个阶段。它的设计要点：

        - 把 issue 正文、评论、系统活动、链接、附件、粘贴的命令一律视为"证据"而非"指令"，不允许其覆盖用户、系统指令或受信仓库指引

        - IssueContext（跟踪 器身份与访问）与 RepositoryContext（检出、远端、分支、完成机制）独立记录，互不替换

        - bug 类任务进入诊断阶段调用 systematic-debugging；进入 Kotlin/Compose 领域前先走 using-chrisbanes-skills 路由

        - 完成路径由 RepositoryContext 决定（GitHub 走 gh、GitLab 走 glab MR），与 issue 来源解耦，且默认不在执行期间提交

shepherd 则是一个"看护型"工作流：自动轮询开放的 PR / MR，分类评审意见、检测并尝试修复 CI 失败，让 PR 持续向前推进，适合维护者长期托管。

需要强调的是，implement-issue 并非自包含——它依赖一整套 Superpowers 工作流技能族（brainstorming、writing-plans、test-driven-development、using-git-worktrees、subagent-driven-development、requesting/receiving-code-review、verification-before-completion 等）。这些技能必须已安装且可被发现；若某一步所需的技能缺失，流程会停下并报告，而不是用近似流程蒙混过关。

7、安装与上手

仓库提供四种安装方式，覆盖主流的 AI 编码代理生态：

// 1) 通过 skills CLI 安装
npx skills add chrisbanes/skills

// 2) 作为 Claude Code 插件
/plugin marketplace add chrisbanes/skills
/plugin install chrisbanes-skills@chrisbanes-skills

// 3) 作为 Codex 插件
codex plugin marketplace add chrisbanes/skills --ref main
codex plugin add chrisbanes-skills@chrisbanes-skills

4) 作为 OpenCode 插件，在其配置文件中声明：

{
  "plugin": ["chrisbanes-skills@git+https://github.com/chrisbanes/skills.git"]
}

上手路径建议：

1. 任务较泛、不确定归哪个技能时，先走 using-chrisbanes-skills 路由，由它指向聚焦技能

2. 任务已明确（如"这个 LaunchedEffect 该怎么写"），直接调用对应的聚焦技能

3. 需要从 issue 一路做到 PR 时，使用 implement-issue；长期看护多个 PR 时，使用 shepherd

4. 自研技能贡献回仓库前，执行 npm install 与 npm run lint 通过校验，CI 也会对每个 PR 跑同样的检查

8、优势与注意事项

优势：

        - 把资深工程师的判断沉淀为可复用的 AI 操作规范，团队风格一致性强、可复制

        - 分层路由避免超大文档，按需加载、token 与注意力都更经济

        - 聚焦技能内含 BAD/GOOD 代码对比与"常见错误→诊断→修复"表格，工程实战导向

        - 覆盖面从语言（Kotlin）到框架（Compose）再到端到端工作流（issue→PR）

注意事项：

        - 内容面向已熟悉 API 的实践者，初学者需先掌握 Compose 与协程基础才能用好

        - 工作流技能依赖 Superpowers 技能族，需配套安装，缺一即停

        - 技能是"规范与路由"，不能替代真实环境验证（如真机性能 profiling、稳定性实测）

        - description 的触发词是 AI 路由的命脉，自研或裁剪技能时务必写准

        - 内容随官方 API 演进（如 strong skipping），需关注其 CalVer 版本号（YYYY.M.D，月日不补零）的更新

9、总结

chrisbanes/skills 用"SKILL.md + frontmatter + 路由/聚焦分层"的组合，把 Kotlin 与 Jetpack Compose 的工程判断经验编码进 AI 工作流。它的价值不在提供新 API，而在提供一套可被代理按需加载的判断规范：从单点取舍（状态归属、副作用选择、性能与稳定性、控制流、值类），到端到端的 issue→PR 工作流，都有清晰的路由与反模式对照。其分层与按需加载的思路，对任何想沉淀团队工程经验的 AI 编码场景，都有很强的借鉴意义。

对于在 Claude Code、Codex 或 OpenCode 中进行 Android / Compose 开发的工程师，先装上这套技能、把 using-chrisbanes-skills 作为通用入口，再按任务深入对应聚焦技能，并据需启用 implement-issue 与 shepherd，是提升代码一致性与端到端交付质量的必要投资。