别再拿 Skills 当提示词:三种最常见的理解误区与纠正

原创2026-10-17 17:37:311,350 阅读
文章标签:AI 技能移动开发原生移动

别再拿 Skills 当提示词:三种最常见的理解误区与纠正

2026 年,以 Android Skills 为代表的"技能(Skills)"概念开始大规模进入开发者的日常工作流。Google 官方的 Android skills 仓库明确将其定义为"面向 AI 优化的模块化指令与资源集合",社区里《千万别误用Android Skills》一文也获得了持续热议——它翻译的原文标题直指要害:"为什么大多数开发者已经在错误地使用它"。与此同时,《Skill 到底是什么?》等深度解读反复强调同一件事:Skill 不是一段更长的提示词。

但现实是,大量开发者依然把 SKILL.md 当作"高级 prompt 模板"来粘贴使用:从对话里复制一段文字,塞给智能体,期待它"变聪明"。这种做法恰恰抹掉了 Skills 体系里最值钱的三个设计维度——可执行结构、可验证标准、可组合边界。本文结合社区情报与本地仓库源码,拆解三种最常见的理解误区,并给出可直接落地的纠正方案。

误区一:当提示词粘贴,忽略了可执行结构

症状:只看到"文字",没看到"文件系统"

很多人拿到一个 Skill 后的第一反应是:把 SKILL.md 的内容复制进对话上下文。这等于把一本操作手册撕成一张纸塞给执行者——目录、索引、分册全部丢失。

打开 README.md 就能看到官方对 Skills 的定义:它们是遵循开放智能体技能标准(open-standard agent skills)的 Markdown 文件,作用是为任务提供技术规格说明,并让 LLM 扎根于特定领域与工作流的信息。关键词是"文件"——Skills 天生是文件系统里的结构化资产,不是对话里的一段话。

再看仓库里任意一个技能目录的物理结构,比如 performance/r8-analyzer/:

r8-analyzer/
├── SKILL.md                              # 主流程:路径选择、步骤、约束
└── references/
    ├── CONFIGURATION.md                  # R8 配置基线
    ├── CONFIGURATION-ANALYZER.md         # 量化分析路径
    ├── KEEP-RULES-IMPACT-HIERARCHY.md    # keep 规则影响层级
    ├── REDUNDANT-RULES.md                # 冗余规则判定
    ├── REFLECTION-GUIDE.md               # 反射场景评估
    └── REPORT_FORMAT.md                  # 报告格式规范

这正是社区解读中反复强调的"渐进式加载"机制:智能体先看到所有 Skill 的 name 与 description,判断任务匹配后才读取 SKILL.md 正文;只有执行到特定场景,才继续按需读取 references/ 或运行脚本。也就是说,description 不是简介,而是路由入口;references 不是装饰,而是防止上下文爆炸的惰性加载层。

纠正:让元数据承担"路由"职责,让目录承担"按需加载"职责

把"提示词"改造成"技能",第一件事是补上 frontmatter。仓库中每个 SKILL.md 都有完整的 YAML 头部,例如 devtools/android-cli/SKILL.md:

---
name: android-cli
description: Provides instructions for installing and using the `android` CLI. The
  `android` command-line tool is a critical tool for Android development and helps
  you create new Android projects, run Android apps on devices, manage and interact
  with Android virtual devices ...
license: Complete terms in LICENSE.txt
metadata:
  author: Google LLC
  last-updated: '2026-09-12'
---

description 决定"什么时候触发",metadata.last-updated 决定"这条经验还新不新鲜",license 决定"能不能复用"。一个优质的 description 应该同时回答三件事:能做什么、什么时候触发、什么事情不做。

第二步是拆分内容。社区指南给出的推荐结构值得直接照搬:

my-skill/
├── SKILL.md          # 核心流程与规则
├── scripts/          # 确定性操作脚本,可选
├── references/       # 按需读取的参考资料,可选
└── assets/           # 模板、图片等静态资源,可选

主文件只保留核心步骤、边界、输出要求和检查清单;详细规范、领域知识、长示例和 API 说明放进 references/,并在主文件中明确写出什么情况下读取哪个相对路径。就像 navigation/navigation-3/SKILL.md 那样——正文是一个清晰的"路由表",每一条都指向具体的 recipe 文件。

误区二:只写"做什么",不写验收标准

症状:目标写得很清楚,怎么算"做完"完全没说

这是把 Skill 当提示词用的最典型后遗症:提示词只需要描述意图,而技能必须定义成功判据。没有验收标准的技能,等于让智能体自己发明"好"的标准——结果就是你反复返工,每次结果都不一样。

Google 官方技能里充斥着这种"验收思维"。看 system/edge-to-edge/SKILL.md,它把约束写成硬性前置条件:

## Prerequisites

- Project **MUST** use Android Jetpack Compose.
- Project **MUST** target SDK 35 or later. If the SDK is lower than 35, increase the SDK to 35.

正文里是 RIGHT/WRONG 成对出现的代码模式——每一种写法都解释了"为什么对/为什么错"。比如 IME 处理:Scaffold(contentWindowInsets = WindowInsets.safeDrawing) 里再叠 imePadding() 会导致双倍内边距,所以标注 WRONG;用 fitInside(WindowInsetsRulers.Ime.current) 则是 RIGHT。这不是"建议",是可判定的规则。

文件末尾的 Checklist 更是把验收标准落到了可勾选的具体条目上:

## Checklist

- [ ] Does every `Activity` call `enableEdgeToEdge()`?
- [ ] Is `adjustResize` set in the `AndroidManifest.xml`?
- [ ] Does the project build? Run `./gradlew build` to be sure.

而 performance/r8-analyzer/SKILL.md 则示范了"输出约束"也是一种验收:报告必须严格遵循 references/REPORT_FORMAT.md 的章节结构,只输出原始 Markdown 报告,"不要输出对话式填充内容(例如'这是你的报告……')",并且"只做调研与建议,不得修改文件"。配合 references/REPORT_FORMAT.md 中"Optimization score: [X]% code is available for R8 optimizations"这类量化输出,验收就变成了可打分、可对比的数字。

纠正:把"判断标准"写进技能,用检查清单终结返工

社区解读里有一句话非常准确:没有验收条件,智能体只知道何时开始,不知道怎样才算完成。给子智能体派任务时,目标 / 约束 / 输入 / 验收 四要素中"验收"最容易被忽略——写技能时同理。

一个直接的纠正范例,是把验收前置到流程开头。看 devtools/android-cli/references/interact.md 如何定义设备交互的"完成标准":

**IMPORTANT** : Always *VISUALLY* examine the PNG image returned from `android
screen` BEFORE doing anything else.

"先看图,再操作"是一条硬性验收规则——它把"智能体必须亲眼确认 UI 状态"这个隐性经验变成了显性步骤。同理,你的技能也应在末尾加一个可勾选的"验收清单":

  • 输入字段的 state 是否包含 "focused" 再输入文本?
  • 滚动前是否检查元素 interactions 是否含 "scrollable"?
  • 最终结果能否追溯到某条命令或某个 diff?

每一行都对应一个可执行的检查动作,而不是模糊的"确保质量良好"。

误区三:不考虑技能之间的组合与冲突

症状:技能越装越多,产出越来越差

"多装几个技能 = 能力更强"是这个误区最迷惑人的地方。社区里那篇《千万别误用Android Skills》给出了一个反直觉的量化结论:每个已安装的技能都会在每次任务的基础上下文中注入 100–200 个 token;一旦被激活,token 数会飙升至数千。一个每天跑 150 个任务、挂着 10 个不必要技能的团队,一年可能浪费 500–600 美元用于模型本已掌握的上下文——并且因为噪声增加,输出质量反而下降。

Google 的官方指导给出的思维模型是:

Android Knowledge Base first → Targeted Skills second → Custom Skills third

知识库(android docs)覆盖广泛知识,技能只针对已确认的故障模式,自定义技能才用来沉淀团队特有经验。仓库 README.md 里也写得很直白:"我们的 Android 技能开发聚焦于评估显示 LLM 表现不佳的用例与工作流;我们不会优先去覆盖 LLM 已经擅长的领域,例如基础的 Jetpack Compose 最佳实践。"——技能的立项标准就是"模型会错",而不是"知识点很多"。

冲突的第二个层面是运行时的互斥。仓库 navigation/navigation-event/SKILL.md 直接给出了一个会崩的冲突案例:同一个 NavigationEventState 被绑定到多个 NavigationBackHandler 会抛出 IllegalArgumentException。

// WRONG
val navigationState = rememberNavigationEventState(currentInfo = NavigationEventInfo.None)
NavigationBackHandler(
    state = navigationState,
    isBackEnabled = hasUnsavedChanges,
    onBackCompleted = { /* Discard changes */ }
)
NavigationBackHandler(
    state = navigationState,
    isBackEnabled = !hasUnsavedChanges,
    onBackCompleted = { /* Navigate up */ }
)
// RIGHT
val navigationState = rememberNavigationEventState(currentInfo = NavigationEventInfo.None)
NavigationBackHandler(
    state = navigationState,
    isBackEnabled = true,
    onBackCompleted = {
        if (hasUnsavedChanges) {
            showDiscardDialog()
        } else {
            onNavigateUp()
        }
    }
)

条件分支必须收敛到单个处理器内部,而不是堆叠多个处理器。同类冲突也出现在布局层级上——system/edge-to-edge/SKILL.md 反复强调"只选一种方法以避免双重 padding",imePadding() 与 contentWindowInsets 叠加就是典型的技能内部规则打架。

纠正:用边界声明与组合策略管理技能生态

三个可落地的纠正动作:

第一,把"排除场景"写进 description,从源头避免误触发。 社区指南给出的公式是:description = 功能定义 + 触发场景/常见说法 + 必要的排除场景。多个技能功能重叠时,路由冲突和误触发几乎是必然的;一句"不用于 X 场景"就能划掉一半歧义。

第二,在技能内部显式建模"路径选择",而不是让智能体自行猜测。 performance/r8-analyzer/SKILL.md 是教科书级示范:

- **If AGP >= 9.3.0** : Proceed to **Path A (Standalone Task)**.
- **If AGP < 9.3.0 and R8 >= 9.3.7-dev** : Proceed to **Path B (Quantitative)**.
- If none of the conditions are met, proceed to **Path C (Heuristic)**.

同样的思路也体现在 device-ai/appfunctions/SKILL.md 的四步工作流中——Discovery → Implementation → KDoc refinement → Testing,并且明确要求"如果用户只请求其中某几步,必须引导其走完整流程"。技能之间、技能内部的关系都应当用显式规则表达。

第三,按"串联 / 并联 / 循环"组织多技能协作,并承认技能是可弃用的。 社区解读把组合方式归纳为三种:串联(A 的输出是 B 的输入)、并联(同一输入探索多个方案)、循环(质检不过带着问题返回上一步)。Google 官方技能的设计哲学则是"为弃用而构建"——随着模型能力提升,曾经成立的技能会被评估通过后"退休"。这意味着你的技能库应该随季度收缩而非扩张:定期用 android skills list --installed 审视,删除模型已不再需要的项,而不是无限堆砌。

把 Skill 当产品迭代,而不是当 prompt 收藏

三个误区的共同根源,是把 Skills 误当成"一次性沟通工具"。实际上,它更接近一个需要持续迭代的软件产品:有结构(文件系统与元数据)、有验收(检查清单与量化指标)、有边界(路由描述与组合规则)。

社区情报中最值得复刻的做法,是 Google 评估技能是否该存在的验收体系——每一个官方技能发布前都要通过真实场景评测,不仅检查项目能否编译,还要用 llm_diff_judge 验证智能体是否用对了 API、是否符合 acceptance_criteria。这不只是大厂流程,也是个人写技能的最小可行方法:准备正例、边界情况和易混淆反例三类测试用例,定义可判断的检查项,对比有无技能时的输出差异,再把失败案例沉淀进测试题库。 一次只改一个问题,改完跑完整回归。

Skill 的价值,从来不是让模型突然变聪明,而是把人的隐性经验变成 AI 可反复执行的显性流程。别再把它当成一段可以随手粘贴的提示词——它是一套可执行、可验证、可组合、可持续升级的工程资产。

登录后查看全文
skills