read-file

read-file 技能概览

read-file 技能帮助 agent 使用 DuckDB 读取并检查数据文件，而不是只根据文件名猜内容。它最适合需要快速预览、结构检查，或对 CSV、JSON、Parquet、Avro、Excel、SQLite、空间文件，或者远程 URL 做轻量分析的用户。如果你的任务是“告诉我这个文件里有什么”或“概括这个数据集”，read-file 技能很合适；如果你要编辑源代码，它就不适合。

read-file 是做什么的

它的核心工作是快速理解数据：读取文件、识别格式，并回答关于内容、结构或明显问题的具体问题。相比通用提示词，这种方式更有用，因为这个技能是围绕 DuckDB 的文件读取器构建的，既支持本地路径，也支持常见的远程来源，例如 https:// 和 s3://。

read-file 最适合什么场景

当输入是一个真实的数据产物，而且你需要一个基于文件本身的答案时，使用 read-file 技能最合适。它尤其适合在把数据载入 notebook、pipeline 或 BI 工具之前，先做第一轮分析。

read-file 的关键差异点

read-file 的主要优势在于支持格式广、而且是一条命令就能跑通的工作流。它的设计目标是减少环境搭建摩擦，解析裸文件名，并处理多种存储后端，而不需要 agent 从零发明一个解析器。

如何使用 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 输入正确的内容

好的 read-file usage 应该从一个明确的文件引用开始，并配上与文件类型匹配的问题。高质量输入会同时说明文件名、来源和你想要的结果：read-file s3://bucket/events.parquet summarize row count, key columns, and date range。像“分析一下这个”这种模糊输入，会迫使技能自己猜重点。

先阅读仓库文件

做 read-file guide 相关工作时，先看 SKILL.md，再检查相邻的仓库文件，了解约定或 agent 行为。在这个仓库里，SKILL.md 是主要事实来源；没有 rules/、resources/ 或 scripts/ 这些辅助目录来扩展工作流。这意味着，最重要的判断点是理解基于宏的 DuckDB 读取路径，以及远程文件前缀。

能显著提升输出的工作流建议

在调用技能前，先把模糊任务改写成具体分析请求。可以直接要求你真正需要的切片，例如“展示列名、类型、前 20 行，以及可疑空值”，或者“比较这个 Excel 文件里的各个 sheet”。对于 read-file for Office Documents，如果你已经知道工作簿或 sheet，最好明确指出，这样能减少误读，也能节省工具调用次数。

read-file 技能 FAQ

read-file 只适合数据文件吗？

是的。这个技能面向结构化或半结构化数据，不适合应用源代码或纯文字文档。如果用户要做代码审查，应使用其他技能，或者直接用代码阅读类提示词。

使用它需要懂 DuckDB 吗？

不需要。这个技能已经把大部分 DuckDB 复杂性隐藏起来了，但如果你给出聚焦的问题，效果会更好。新手只要能指向一个文件，并说清楚想知道什么，就可以安全使用。

这和直接让 AI“打开文件”有什么不同？

read-file 更可靠，因为它采用明确的文件读取工作流和按格式选择的加载器。这能减少凭空编造的摘要，并改善它在混合文件类型、远程 URL 和较大数据集上的表现。

什么情况下不应该用 read-file？

当文件是源代码、你需要大规模转换，或者输入根本不是文件或 URL 时，不要使用它。如果你需要的是完整的数据库操作，而不是检查和概述，它也不合适。

如何改进 read-file 技能

提出你真正需要的分析

质量提升最大的地方，在于把任务收窄。不要只说“总结这个表格”，而是改成“找出前 10 个类别、每一列的缺失值，以及任何可疑异常值”。read-file 技能最擅长回答能直接对应表格检查的问题。

提供与格式相关的提示

如果文件是 Excel 工作簿，说明你只关心某一个 sheet，还是所有 sheet。若是远程文件，请写全 URL，并在相关时注明存储类型。这些细节能帮助技能选择正确的读取路径，避免不必要的探测。

留意常见失败模式

最常见的问题是歧义：只有裸文件名、存在多个相似文件，或者没有定义数据切片，却要求一个业务结论。另一个失败模式，是把 read-file 当成编辑或 ETL 技能来用。要始终把任务重心放在读取、概况分析和解释文件内容上。

在第一轮之后继续迭代

用第一轮输出来细化下一条提示词。如果初次读取已经暴露了列信息，就只针对重要字段继续深入检查：重复值、空值模式、日期覆盖范围，或分组级汇总。这样能在不把第一轮调用压得过重的前提下，最快拿到更好的 read-file 结果。