read-file

read-file 技能概覽

read-file 技能能幫助代理程式用 DuckDB 讀取並檢視資料檔案，而不是只憑檔名猜內容。它最適合需要快速預覽、檢查 schema，或對 CSV、JSON、Parquet、Avro、Excel、SQLite、空間檔案或遠端 URL 做輕量檢視的使用者。如果你的工作是「告訴我這個檔案裡有什麼」或「摘要這份資料集」，read-file 技能很適合；如果你要編輯原始碼，則不適合。

read-file 的用途是什麼

read-file 的核心任務是快速理解資料：讀取檔案、辨識格式，並回答關於內容、結構，或明顯問題的提問。這比一般化的提示更有用，因為這個技能是圍繞 DuckDB 的檔案讀取器設計，除了本機路徑，也支援常見的遠端來源，例如 https:// 和 s3://。

read-file 最適合什麼情境

當輸入是真正的資料工件，而且你需要根據檔案本身得出答案時，就該使用 read-file 技能。它特別適合在把資料載入 notebook、pipeline 或 BI 工具之前，先做第一輪分析。

read-file 的主要差異

read-file 的主要優勢在於支援的格式廣，以及單一指令的工作流程。它的設計目的是降低設定摩擦、解析裸檔名，並在不要求代理程式從零打造 parser 的前提下，處理多種儲存後端。

如何使用 read-file 技能

安裝並呼叫 read-file

先在倉庫的技能系統中安裝 read-file 技能，接著用路徑或 URL 搭配一個簡短問題來呼叫它。實際的呼叫方式可以像這樣：read-file sales_q1.csv what columns exist and are there nulls?。read-file install 流程很重要，因為這個技能預期的是 DuckDB 支援的環境，而不是一般只能聊天的提示介面。

提供正確的輸入給技能

最好的 read-file usage 會先提供具體的檔案參照，並搭配與檔案類型相符的問題。強而有力的輸入會明確寫出檔名、來源與你要的結果，例如：read-file s3://bucket/events.parquet summarize row count, key columns, and date range。像「分析這個」這類模糊輸入，會迫使技能去猜真正重點。

先閱讀倉庫檔案

進行 read-file guide 工作時，先從 SKILL.md 開始，再查看旁邊任何說明慣例或代理行為的倉庫檔案。在這個倉庫裡，SKILL.md 是主要依據；沒有額外的 rules/、resources/ 或 scripts/ 資料夾可用來擴充工作流程。也就是說，最重要的判斷點，是理解以 macro 為基礎的 DuckDB 讀取路徑，以及遠端檔案前綴。

能提升輸出的工作流程建議

在呼叫技能之前，先把模糊任務轉成具體的分析請求。你可以明確要求你真正需要的切片，例如「列出欄位、型別、前 20 筆資料，以及可疑的空白值」或「比較這個 Excel 檔中的各個工作表」。對 read-file for Office Documents 而言，如果你已經知道工作簿或工作表，就直接講明，這樣能減少誤讀，也能節省工具呼叫次數。

read-file 技能 FAQ

read-file 只適合資料檔嗎？

是。這個技能是為結構化或半結構化資料而設，不適合應用程式原始碼或純文字文件。如果使用者要做程式碼審查，應改用其他技能，或直接用讀碼提示。

使用它需要懂 DuckDB 嗎？

不需要。這個技能會把大部分 DuckDB 的複雜度包起來，但若你能提出聚焦的問題，結果會更好。初學者只要能指出檔案，並說明想知道什麼，就可以安全使用。

這和叫 AI「打開檔案」有什麼不同？

read-file 更可靠，因為它使用明確的檔案讀取工作流程，以及能辨識格式的載入器。這能降低憑空捏造摘要的風險，並改善在混合檔案類型、遠端 URL 與較大資料集上的表現。

什麼情況下不該用 read-file？

當檔案是原始碼、你需要大量轉換，或輸入其實不是檔案或 URL 時，就不要用它。如果你需要的是完整資料庫操作，而不是檢視與摘要，read-file 也不適合。

如何改進 read-file 技能

提出你真正需要的分析

品質提升最大的關鍵，是把任務範圍縮小。不要只說「摘要這個試算表」，而要改成「找出前 10 大類別、每欄缺漏值，以及任何可疑離群值」。read-file 技能最適合能清楚對應到表格檢視的問題。

提供與格式相關的提示

如果檔案是 Excel 活頁簿，就先說你在意的是單一工作表還是全部工作表。如果是遠端檔案，請附上完整 URL，必要時也寫清楚儲存類型。這些細節能幫助技能選對讀取路徑，避免不必要的探測。

留意常見失敗模式

最常見的問題是歧義：裸檔名、相似檔案太多，或是沒有定義資料切片就直接問商業答案。另一種失敗模式，是把 read-file 當成編輯或 ETL 技能使用。請把任務重心放在讀取、分析與解釋檔案內容。

在第一輪之後持續迭代

用第一輪輸出來修正下一個提示。如果初次讀取已經揭露欄位，就針對重要欄位再做更深入的檢查：重複值、空值分布、日期涵蓋範圍，或分組總計。這是取得更好 read-file 結果的最快方式，而且不會讓第一次呼叫負擔過重。