develop-ai-functions-example

develop-ai-functions-example 技能總覽

develop-ai-functions-example 是做什麼用的

develop-ai-functions-example 技能是一份聚焦的建置指南，專門用來在 vercel/ai 儲存庫中的 examples/ai-functions/src/ 建立或修改可執行的範例。它的職責不是做一般性的 prompting，而是幫你產出符合該儲存庫慣例的範例，涵蓋 AI SDK function demos、provider 驗證，以及類似測試 fixture 的用途。

哪些人適合使用這個技能

如果你正在做以下事情，就很適合使用 develop-ai-functions-example 技能：

• 為某個 AI SDK function 新增範例
• 把既有範例改成另一個 provider
• 驗證某個 provider 是否支援某項功能
• 在既有範例樹下建立最小重現案例或 fixture
• 想遵循 repo 既有結構，而不是自己發明一套模式

如果你只是想抽象地問 LLM generateText() 怎麼運作，那這個技能可能比你需要的更聚焦、更窄。

真正要解決的工作需求

大多數使用者不是想看說明文字，而是想要一個能跑的範例：放在正確資料夾、長得像 repo 內其他檔案、使用正確的 SDK function，並盡量少犯 repo 特有的錯誤。develop-ai-functions-example 最適合被視為 AI Functions 範例區域中的 repo-aware 實作助手。

它和一般 coding prompt 有什麼不同

一般 prompt 也能草擬範例程式碼，但通常會漏掉本地分類方式與檔案放置邏輯。這個技能補上了實務上的上下文，例如：

• examples/ai-functions/src/ 底下已存在的範例分類
• 功能類型與目標目錄之間預期的對應關係
• 這些範例在 repo 中的用途：驗證、示範與 fixtures
• 傾向產出精簡、可執行的範例，而不是大而全的教學

最適合的使用範圍

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/

這個範圍很重要。此技能是針對這個 repo 版面中的範例開發而優化，不是拿來設計 app、SDK API surface，或 production 架構。

如何使用 develop-ai-functions-example 技能

安裝情境與適用位置

請在 vercel/ai 儲存庫中，或你想仿照其範例結構時，參考 develop-ai-functions-example install 指引。常見的安裝方式如下：

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

之後，當你的任務是要在 examples/ai-functions/src/ 底下建立、編輯或驗證範例檔案時，再呼叫這個技能。

先選對範例類別，再開始寫

在要求產生程式碼之前，先確認目標 function family。這是影響最大的決策，因為它會同時決定資料夾位置與範例應有的形式。

例如：

• 一次性文字輸出 → generate-text/
• token 或 chunk 串流輸出 → stream-text/
• 受 schema 約束的結構化輸出 → generate-object/
• 串流式結構化輸出 → stream-object/
• 單一輸入的 embeddings → embed/
• 批次輸入的 embeddings → embed-many/
• 使用 tool 的多步驟流程 → agent/

如果跳過這一步，產出的範例很可能連 API 都用錯。

這個技能需要你提供哪些輸入

develop-ai-functions-example usage 的品質，很大程度取決於你的需求描述是否夠具體。建議提供：

• 目標 function，例如 generateObject() 或 streamText()
• provider 與 model（若已知）
• 這個範例是拿來做驗證、文件式示範，還是測試 fixture
• 預期的輸入與輸出
• 是否需要 streaming、tools、schema validation 或 middleware
• 對 dependencies、檔名或環境變數的限制

較弱的輸入：

• 「做一個 AI 範例。」

較強的輸入：

• 「在 examples/ai-functions/src/generate-object/ 下建立一個最小的 generateObject() 範例，用 Zod schema 測試從產品評論文字中抽取結構化資訊，並使用這個 repo 已支援的 provider。」

把模糊需求改寫成適合技能處理的 prompt

好的 develop-ai-functions-example guide prompt，會清楚點出目標成果、目標目錄、使用的 function，以及驗證意圖。

實用格式可以包含：

• 你要建立什麼
• 它應該放在哪裡
• 要使用哪個 AI SDK function
• 允許哪些 provider 前提
• 要多精簡，還是要偏 production 風格
• 什麼情況算成功

範例 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.md。請先讀它，因為裡面整理了類別對照與 repo 特定用途。接著，再去看你打算修改的目標目錄中的相鄰範例。和去翻大範圍的 repo 文件相比，這樣通常更快掌握本地命名與寫法模式。

建議閱讀順序：

1. skills/develop-ai-functions-example/SKILL.md
2. examples/ai-functions/src/ 下的目標資料夾
3. 與你預計功能最接近的 1 到 2 個同層範例
4. 附近使用到的 provider-specific imports 或 env 模式

讓範例符合它的用途

這個 repository 裡的範例不只是文件用途。你的 prompt 應明確指出你想優化的是哪一種：

• provider 支援驗證
• 功能示範
• 可重現的 fixture
• 迭代中的實驗

這件事很重要，因為：

• 驗證型範例應該更精簡且更明確
• 示範型範例應該聚焦在關鍵 API 行為
• fixture 應避免不必要的變化
• 實驗型範例可以粗一點，但仍需要放在正確資料夾

產出要精簡，但一定要能跑

最佳的 develop-ai-functions-example skill 輸出通常是做得更少，而不是更多。你可以明確要求：

• 一個清楚的 function call
• 只保留必要 imports
• 輸入一看就懂
• 簡短的輸出處理
• 明確列出 env variables
• 除非資料夾本來就有此預期，否則不要加 framework scaffolding

這能降低一種常見誤差：模型加了太多 app 程式碼，反而把你真正想示範的 SDK 行為蓋掉。

建議在需求中直接提到的 repository 路徑

如果你希望輸出更貼近 repo 既有模式，請在需求中直接寫出路徑。實用路徑包括：

• 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/

直接提及路徑，有助於這個技能選對模式，而不是自己發明一個中性的範例。

建立新範例的實際工作流程

一個可靠的流程如下：

1. 先確認目標 function family
2. 查看該資料夾中的同層範例
3. 用資料夾、function、provider 與用途來下 prompt
4. 先產出初版範例
5. 刪掉所有對驗證或示範不必要的內容
6. 用預定 provider 實際執行
7. 依照附近檔案調整命名、輸入與 env 處理方式

這通常比起一開始盲目要求「完整範例」，最後再硬改到符合 repo，來得更快。

什麼時候該用它，而不是一般 prompt

當主要風險是與 repository 不相符時，就該使用 develop-ai-functions-example usage：例如放錯資料夾、選錯 AI SDK function、複雜度不對，或 demo 根本不適合 examples tree。若你需要的是超出 examples/ai-functions/src/ 範圍的整體架構協助，那就改用一般 prompt。

develop-ai-functions-example 技能常見問題

develop-ai-functions-example 只能用在 vercel/ai repo 嗎

它在這裡最有價值，因為這個技能就是圍繞 examples/ai-functions/src/ 的範例分類而設計。你仍然可以把它當作自己範例 repo 的模式參考，但如果你不在意是否貼合這個結構，價值就會明顯下降。

這個技能對新手友善嗎

算是友善，前提是你已經知道自己要示範哪一種功能。它會把你的目標映射到正確的範例類別，縮小決策空間。但如果你還在猶豫該選 text generation、structured generation、embeddings、agents，還是 middleware，那它就沒那麼適合新手。

它比一般 coding request 強在哪裡

主要優勢是更貼 repo。develop-ai-functions-example 能幫你避免一些常見錯誤，例如把 structured-output 範例放進純文字資料夾、用非 streaming API 來做 streaming demo，或把原本應該是 fixture 的內容過度擴張，混入不相干的 app 程式碼。

什麼情況下不該使用 develop-ai-functions-example

如果你需要的是以下內容，就不該用它：

• production app 架構
• UI 整合指引
• 通用型 AI SDK 教學
• 跨 repo 重構建議
• 超出範例建立範圍的 evaluation 或 benchmarking 策略

它本來就是刻意設計得很窄。

我一定要先知道確切的 provider 嗎

不一定，但如果你有指定，輸出通常會更好。若你還不確定，可以要求使用附近範例裡已經出現過的 provider，這樣產出的檔案會更容易符合現有 repo 模式，也比較容易驗證。

它能幫我改既有範例，而不只是新增嗎

可以。它很適合用來修改或收斂既有範例，尤其是當你想更換 SDK function、替換 provider、把重現案例簡化，或讓某個檔案回到正確類別時。

如何提升 develop-ai-functions-example 技能的使用效果

給這個技能明確的 repository 目標

最有效的改進方式，就是直接指出確切的目標資料夾與 function。比較如下：

較弱：

• 「新增一個 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 第一段就寫清楚。因為程式碼的形狀，往往會隨這個決策而改變。

第一版就先避免過度設計

常見失敗模式之一，就是回傳內容多了額外包裝層、app scaffolding，或把不同關注點混在一起。你可以直接要求：

• 最小化程式碼
• 單一職責
• 不要 UI
• 不要 framework setup
• 只保留必要註解

這樣比較能讓範例維持在 examples tree 的風格，而不是長成一個小型 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 驗證
• 什麼結果算成功

迭代時要收斂，不要越改越廣

拿到第一版後，改善方式通常是減少歧義，而不是增加功能：

• 把「some provider」換成具體 provider
• 把「an object」換成 schema
• 把「example script」換成目標目錄
• 把「works」換成可驗證的輸出期待

對 develop-ai-functions-example 來說，最好的迭代路徑通常是縮小範圍，而不是加入更多功能。

接受輸出前，先檢查類別是否真的對

在你決定保留結果之前，先問自己：

• 這個 function 放在這個資料夾對嗎？
• 這個範例對驗證來說夠精簡嗎？
• 它是否清楚示範了一個核心行為？
• 維護者看得出來它為什麼屬於這裡嗎？

如果答案是否定的，先改 prompt，再改程式碼。這通常是更快的修正方式。

用 provider 與環境前提來強化 prompt

如果範例依賴 credentials 或 provider-specific 行為，請直接寫明。否則模型可能會產出技術上看似合理、但在 repository 中很難實際跑起來的程式碼。

實用補充包括：

• 必要的 env var 名稱
• provider SDK 假設
• 若穩定性重要，請指定 model name
• 是否接受 fallback

用同層範例當作驗收標準

提升輸出品質的一個實用方法，是拿生成的檔案去和附近範例比較，而不是拿去對照泛用的程式碼標準。如果它明顯比同層檔案更複雜、焦點更分散，或結構差很多，就應該要求重寫，改成貼近本地模式。