develop-ai-functions-example

develop-ai-functions-example skill 概览

develop-ai-functions-example 适合用来做什么

develop-ai-functions-example 是一份聚焦型构建指南，专门用于在 vercel/ai 仓库的 examples/ai-functions/src/ 中创建或修改可运行示例。它的职责不是通用 Prompt 编写，而是帮助你产出符合仓库约定的示例：包括 AI SDK 函数演示、provider 能力验证，以及偏测试夹具（fixture）性质的样例文件。

谁适合使用这个 skill

如果你正在做以下事情，就适合用 develop-ai-functions-example skill：

• 为某个 AI SDK 函数新增示例
• 把现有示例适配到另一个 provider
• 验证某个 provider 是否支持某项能力
• 在现有示例树下创建最小复现或 fixture
• 希望遵循仓库现有结构，而不是自己另起一套模式

如果你只是想泛泛地问一个 LLM：generateText() 原理上怎么工作，那这个 skill 可能比你需要的更窄、更偏仓库实现。

它真正解决的任务是什么

大多数用户要的不是说明文字，而是一个能跑、放在正确目录、结构正确、调用正确 SDK 函数、并尽量少犯仓库特有错误的示例。更准确地说，develop-ai-functions-example 最适合被看作 AI Functions 示例区域里的“仓库感知型实现助手”。

它和通用 coding prompt 有什么不同

普通 prompt 也能起草示例代码，但通常会忽略本地分类方式和文件落位逻辑。这个 skill 补上的是更实用的上下文，比如：

• examples/ai-functions/src/ 下已经存在哪些示例分类
• 功能类型与目标目录之间的预期映射
• 仓库为什么要保留这些示例：用于验证、演示和 fixture
• 优先生成最小、可运行的示例，而不是写成大而全教程

最适合的范围

develop-ai-functions-example for Skill Examples 最擅长处理的是以下目录类别中的工作：

• generate-text/
• stream-text/
• generate-object/
• stream-object/
• agent/
• embed/
• embed-many/
• generate-image/
• generate-speech/
• transcribe/
• rerank/
• middleware/

这个边界很重要。该 skill 是为当前仓库布局下的示例开发而优化的，不是用来设计应用、SDK API surface，或生产级架构方案的。

如何使用 develop-ai-functions-example skill

安装上下文与适用场景

当你在 vercel/ai 仓库中工作，或者希望复用它的示例组织方式时，可以使用 develop-ai-functions-example install 相关指引。一个常见安装方式是：

npx skills add vercel/ai --skill develop-ai-functions-example

随后，当你的任务明确是创建、编辑或验证 examples/ai-functions/src/ 下的示例文件时，再调用这个 skill。

先选对示例分类，再让它写代码

在要代码之前，先确定目标函数家族。这通常是影响最大的决策，因为它同时决定了目标文件夹和示例应有的结构。

例如：

• 普通的一次性文本输出 → generate-text/
• token 或 chunk 流式输出 → stream-text/
• 带 schema 约束的结构化输出 → generate-object/
• 流式结构化输出 → stream-object/
• 单条输入的 embedding → embed/
• 批量输入的 embedding → embed-many/
• 带工具调用的多步骤流程 → agent/

如果跳过这一步，生成出来的示例很可能连 API 都选错。

这个 skill 需要你提供哪些输入

develop-ai-functions-example usage 的效果，很大程度取决于你的需求说得有多具体。建议至少提供：

• 目标函数，例如 generateObject() 或 streamText()
• provider 和 model（如果已知）
• 这个示例是用于验证、文档式演示，还是测试 fixture
• 预期输入和输出
• 是否需要 streaming、tools、schema validation 或 middleware
• 对依赖、文件命名、环境变量是否有约束

一个较弱的输入是：

• “Make an AI example.”

一个更有效的输入是：

• “Create a minimal generateObject() example under examples/ai-functions/src/generate-object/ that tests structured extraction from product review text using a Zod schema and a provider supported in this repo.”

把模糊目标改写成更适合这个 skill 的 prompt

一个好的 develop-ai-functions-example guide prompt，通常会明确结果、目标目录、所用函数，以及验证意图。

实用模板可以包含：

• 你想生成什么
• 它应该放在哪里
• 它应该使用哪个 AI SDK 函数
• 允许采用哪些 provider 假设
• 它应该尽量保持最小化，还是更接近生产形态
• 你怎么判断它算成功

示例 prompt：

“Use develop-ai-functions-example to create a minimal example in examples/ai-functions/src/stream-text/ showing streamText() with a provider already used in the repo. Keep it short, runnable, and clearly focused on streaming output rather than app integration. Include any required env vars and explain why this belongs in stream-text/ instead of generate-text/.”

先读 SKILL.md，再看相邻示例

这个 skill 当前只有一个可见支持文件：SKILL.md。先读它，因为里面总结了分类映射和该仓库特有的使用意图。读完之后，再去看你准备修改的目标目录中的相邻示例。相比泛读整个仓库文档，这样更快抓到本地命名方式和代码模式。

推荐阅读顺序：

1. skills/develop-ai-functions-example/SKILL.md
2. examples/ai-functions/src/ 下的目标文件夹
3. 与你目标功能最接近的一到两个同级示例
4. 附近文件里使用的 provider-specific imports 或 env 写法

让示例和它的用途匹配

这个仓库里的 examples 不只是为了文档展示。你在 prompt 里最好明确，你优化的是哪一种目的：

• provider 支持验证
• 功能演示
• 可复现 fixture
• 迭代实验

为什么这点重要：

• 验证型示例应该尽量最小且表达明确
• 演示型示例应该突出核心 API 行为
• fixture 应尽量避免无关变化
• 实验型示例可以稍微粗糙一些，但目录归类仍要正确

输出尽量精简，但必须可运行

最好的 develop-ai-functions-example skill 输出，往往不是做得更多，而是做得更少。你可以明确要求它：

• 只包含一次清晰的函数调用
• 只保留必要 imports
• 输入清楚直白
• 输出处理尽量简短
• 明确列出 env variables
• 除非目标目录本来就需要，否则不要加 framework scaffolding

这样能减少一种常见误差：模型把应用层代码一并加进去，反而掩盖了你真正想展示的 SDK 行为。

建议在请求里直接写明的仓库路径

如果你希望输出严格贴合仓库结构，就在请求中直接写路径。常用路径包括：

• examples/ai-functions/src/generate-text/
• examples/ai-functions/src/stream-text/
• examples/ai-functions/src/generate-object/
• examples/ai-functions/src/stream-object/
• examples/ai-functions/src/agent/
• examples/ai-functions/src/embed/
• examples/ai-functions/src/embed-many/

直接写路径，能帮助这个 skill 选中正确模式，而不是凭空生成一个“中性示例”。

新建示例时的实用工作流

一个更稳妥的流程通常是：

1. 先确定目标函数家族
2. 查看该目录下的同级示例
3. 在 prompt 中明确目录、函数、provider 和用途
4. 生成初版示例
5. 删掉所有对验证或演示不必要的部分
6. 用目标 provider 跑一遍
7. 调整命名、输入和 env 处理方式，使其与附近文件保持一致

通常这比“盲要一个完整示例，再强行改造成仓库风格”要快得多。

什么时候该用它，而不是普通 prompt

当主要风险是“与仓库不匹配”时，用 develop-ai-functions-example usage 更合适：比如目录放错、AI SDK 函数用错、复杂度过高，或生成出的 demo 根本不适合放进现有 examples tree。
如果你需要的是 examples/ai-functions/src/ 之外、更宽泛的架构建议，那普通 prompt 更适合。

develop-ai-functions-example skill 常见问题

develop-ai-functions-example 只适用于 vercel/ai 仓库吗

它在这里最有价值，因为这个 skill 就是围绕 examples/ai-functions/src/ 的示例分类体系设计的。你当然也可以把它当作自己 examples 仓库的参考模式，但如果你并不在意是否匹配这套结构，它的价值会明显下降。

这个 skill 对新手友好吗

算友好，前提是你已经知道自己想演示什么能力。它能把你的目标收敛到合适的示例分类里。
但如果你还在犹豫是做文本生成、结构化生成、embeddings、agents 还是 middleware，那么它对新手就没那么友好了，因为它不会替你做高层概念选择。

它相比普通 coding request 强在哪里

最大的优势是更贴合仓库。develop-ai-functions-example 能帮你避免这类常见错误：把结构化输出示例塞进普通文本目录、用非流式 API 去做流式演示，或者给一个 fixture 堆进大量无关的 app 代码。

什么时候不该使用 develop-ai-functions-example

如果你需要的是以下内容，就不适合用它：

• 生产级应用架构
• UI 集成指导
• 通用 AI SDK 教程
• 跨仓库重构建议
• 超出示例创建范围的评测或 benchmark 策略

它本来就是刻意收窄范围的。

一开始就必须知道具体 provider 吗

不一定，但如果你能指定 provider，输出通常会更好。如果你暂时不确定，可以要求它选择“附近示例里已经在用的 provider”，这样生成的文件更容易对照现有仓库模式做验证。

它能帮我改现有示例，而不只是新建吗

可以。它同样适合用来修改、收紧已有示例，尤其是在你想切换 SDK 函数、更换 provider、把 repro 简化，或者把某个文件重新对齐到正确分类时。

如何改进 develop-ai-functions-example skill 的使用效果

给这个 skill 一个明确的仓库目标

最有效的提升方式，就是直接写出准确的目标目录和函数。对比一下：

较弱：

• “Add an example for object extraction.”

较强：

• “Use develop-ai-functions-example to add a minimal generateObject() example under examples/ai-functions/src/generate-object/ that extracts invoice fields from plain text and prints validated JSON.”

后者把 API 选择和文件落位的歧义基本都消掉了。

一开始就说明输出的用途

用户最在意的，往往是这个示例到底是用来证明支持、教学演示，还是当 fixture。把这一点放在 prompt 第一段里。因为代码最终长什么样，往往会被这个决策直接影响。

第一版就要避免过度设计

一个很常见的失败模式，是模型返回了带额外包装层、应用脚手架，甚至混杂多种职责的代码。你可以明确要求：

• minimal code
• one responsibility
• no UI
• no framework setup
• only essential comments

这样更容易让示例保持在 examples tree 应有的风格里，而不是膨胀成一个 mini app。

要求它匹配本地模式

想提高 develop-ai-functions-example skill 的结果质量，可以明确告诉模型：在命名、imports 和 env 处理上模仿附近示例。这个小要求，往往比泛泛要求“best practices”更有效。

示例：

• “Match the style of sibling files in examples/ai-functions/src/stream-text/ and avoid introducing a new pattern unless required.”

明确输入内容和预期输出形态

另一个常见失败点，是 demo 逻辑太模糊。如果你明确给出示例输入和预期输出，生成结果会更容易验证。

更有效的 prompt 细节包括：

• 输入文本或 payload
• 预期响应形式
• 输出是应该 streamed、logged，还是做 schema validation
• 什么情况算成功

通过“收紧范围”来迭代，而不是不断加需求

拿到第一版后，最有效的优化方式通常是减少歧义，而不是扩大范围：

• 把 “some provider” 换成具体 provider
• 把 “an object” 换成明确 schema
• 把 “example script” 换成具体目标目录
• 把 “works” 换成可验证的输出预期

对 develop-ai-functions-example 来说，最好的迭代路径通常是范围更窄，而不是功能更多。

接受输出前，先检查分类是否合适

在保留结果之前，先问自己：

• 这个函数放在这个目录里，是否正确？
• 这个示例是否足够精简，适合做验证？
• 它是否清楚展示了一个核心行为？
• 维护者看到它时，能否立刻理解它为什么属于这里？

如果答案是否定的，先改 prompt，再改代码。很多时候，这样反而更快。

用 provider 和环境假设把 prompt 说清楚

如果示例依赖凭证或某种 provider-specific 行为，要直接说出来。否则模型很可能给出“理论上说得通、但在仓库里不容易跑起来”的代码。

有用的补充信息包括：

• 必需的 env var 名称
• provider SDK 假设
• 如果稳定性重要，写明 model 名称
• 是否允许 fallback

以同级示例为验收标准

提高输出质量的一个很实用的方法，是拿生成文件去对照附近示例，而不是按泛化代码标准来评估。
如果它明显比同级文件更复杂、更分散焦点，或者结构差异过大，就应该要求重写，并明确对齐本地模式。