Mastra Agent Builder 中的 Spreadsheet Agent 技能为表格数据场景生成可靠 Agent 的完整写作手册【免费下载链接】mastraMastra is the modern TypeScript framework for AI-powered applications and agents.项目地址: https://gitcode.com/GitHub_Trending/ma/mastra本篇指南聚焦于 Mastra 编辑器中 Agent Builder 内置的spreadsheet-agent作者手册SKILL.md它是 Builder Agent 在生成读写 Google Sheets / Excel / CSV / Airtable 等表格数据类 Agent 时所依赖的核心 Playbook。读完本文你将理解 Builder Agent 如何在运行时按需加载这份手册、手册中每一节身份模板、缺失输入策略、系统提示词模板、完成标准、反模式各自约束什么以及为什么验证写回与破坏性操作先 dry-run是表格类 Agent 不出事故的两条底线。手册的定位Builder Agent 的作者技能spreadsheet-agent/SKILL.md位于 packages/editor/src/ee/workspace/skills/spreadsheet-agent/SKILL.md是 Agent Builder 自身的一组作者技能authoring skills之一。需要特别注意代码库中 skills 一词有两层含义二者不可混淆见 skills 目录 READMEBuilder 作者技能本目录只读 Markdown 手册教 Builder Agent 如何为某类原型archetype写出高质量系统提示词。它们通过工作区技能工具skill、skill_search、skill_read在运行时按需加载——因为 agent-builder-agent.ts 中为 Builder 配置了Workspace并声明skills: [skills]。用户可附加的 Agent 技能产品特性最终用户创建、可附加到所建 Agent 上的技能存放在编辑器的 skill store 中。作者技能绝不能被附加到生成的 Agent 上也不能向用户提及。加载链路在源码层面可以确认Builder Agent 的Workspace以本地文件系统挂载workspace/目录agent-builder-agent.ts#L13-L20核心的技能工具工厂createSkillTools会暴露skill、skill_search、skill_read三个工具其中skill工具是无状态设计——直接返回完整 SKILL.md 内容作为工具结果指令自然持久在对话历史中上下文被压缩时模型只需再次调用见 createSkillTools 实现 及 技能工具测试。Builder 的运行时流程在 skills README 中定义为六步把用户需求归类到某一原型 → 用skill_search按名称/描述找到对应技能 → 用skill激活并加载完整手册 → 综合出一份具体的运行契约run contract→ 用手册加运行契约写出生成 Agent 的名称、描述、模型、能力与系统提示词 → 写入前自审。若归类不确定则回退到通用规则技能agent-prompt-quality-bar再回退到generic-assistant。spreadsheet-agent正是当前原型表中的成员之一读取或写入表格数据Sheets、Excel、Airtable、CSV时 Builder 会选中它见 skills 目录 README 的原型表。何时选中这份手册触发词清单手册开头的 When to use 一节给出了明确的触发词集合。当用户提到以下任一概念时Builder 应选择本手册平台与格式Google Sheets、Google Spreadsheet、Excel、XLSX、CSV、Airtable、Notion database表格结构词table、rows、columns、cells、ranges、sheet、tab、worksheet、pivot、lookup、VLOOKUP、formula表格工作流动词短语update my leads list、fill in the sheet、weekly report 这类更新/填充/汇报意图。值得注意的是frontmatter 的description字段承载了这些触发词frontmatter 中name: spreadsheet-agent描述以 Authoring playbook for building agents that read or write tabular data — Google Sheets, Microsoft Excel, CSV, Airtable, Notion databases... 开头。这不是随意的文档说明按 skills README 的规范skill_search依据 description 排序命中模糊的描述会被跳过且name必须与目录名一致小写 连字符、description 最长 1024 字符。换句话说description 就是这份手册被检索到的索引字段。Agent 身份模板命名与描述如何生成手册的 Agent identity template 规定生成 Agent 的身份要锚定领域 动作给出三种命名模式和一句式描述模式命名模式示例Domain Sheet UpdaterLeads Sheet UpdaterOutcome TrackerWeekly Sales TrackerSource-to-Sheet SyncerStripe-to-Sheet Syncer描述只允许一句话必须点明哪张表/哪个数据源以及做什么动作。手册给的范例Reads your weekly sales sheet, flags accounts that dropped, and writes a follow-up column.读取每周销售表标记下滑客户并写入跟进列。这与 Builder 主系统提示词中名称要短、好记、锚定结果不许叫 Agent Xagent-builder-agent.ts#L114-L118的要求一致身份模板把这条通用规则落实到了表格场景的具体句式上。缺失输入策略五种情形各有定式Missing-input policy 一节要求生成的系统提示词必须从可用能力出发选择最安全的策略。手册按集成是否可用 × 表身份是否可知划分了五种情形没有任何表格工具Agent 必须拒绝执行并解释需要连接一个表格集成有访问权限且恰好可见一张相关表默认使用它并在最终回执receipt中说明这一假设有访问权限但表身份未知、工具能列出可见表先列出可见选项请用户选择后再写入有访问权限但工具无法列出表先向用户索要表的标识链接、id 或名称拿到之前不写入破坏性写入删除/清空/覆盖公式先 dry-run 并停下等待明确确认除非用户明确要求自主执行且提示词中编码了安全阈值。这套策略的边界可以概括为一句话只有唯一相关表这一种情形允许默认行动其余情形一律先问清再写。对应的标准拒绝话术也在 skills README 的 Good missing-integration refusals 中登记为表格场景的定式I need access to your spreadsheet first. Connect a Google Sheets, Excel, Airtable, or table integration and try again.系统提示词模板逐节解析手册的核心资产是一段带占位符的完整系统提示词模板SKILL.md 第 29–80 行Builder 需要把其中的agent name、specific sheet or table、target user、safe row threshold等占位符实例化。逐节看它约束了什么角色与所有权What you own。开头句式为 You are agent name. You update / read / sync / report on specific sheet or table for target user.——动作动词必须在 update / read / sync / report 中四选一保证角色单一。任务被限定为单一具体结果且对写操作要求以确切的 sheet、tab/table、range 和行数确认结果。触发与输入Trigger and input。一次运行由用户主动要求读取/更新/同步/汇报某张表启动或由配置好的计划/事件把待处理行传入。这正对应 run contract 的第一项Trigger / input。选表与缺失输入Sheet selection and missing inputs。把上一节的五条缺失输入策略逐条展开为提示词指令无集成时输出那句标准拒绝话术唯一表时输出 Assumption: using sheet/table name.多表且无目标时列出选项请用户挑选无法列出选项时索要表的链接、id 或名称。决策规则How to make decisions。这是表格场景最容易被忽视的一组细节规则除非用户另有说明首行视为表头写入前必须先读当前值——永远不在未检查现状的情况下覆盖已有数据匹配既有列的类型——货币列写数字不写字符串追加操作写到最后一个非空行之后除非表有显式插入规则破坏性操作删行、清空范围、覆盖公式必须 dry-run 出精确的行/范围并停下等确认除非自主执行 安全阈值被显式编码。沟通格式How you communicate。完成的读写必须以结果开头定式为 Updated N rows in Sheet name Tab name, range A2:D17.dry-run 以 Confirmation needed 开头并列出将变更的精确行/范围对用户解释用平实语言除非用户要公式否则解释中不出现公式跳过的行必须用短列表说明原因。拒绝规则Refusals。无表格工具时干净地拒绝并指名缺失的连接凭据缺失或过期时用平实语言给出确切错误并停下变更将删除/清空超过safe row threshold行时拒绝并建议更小、可审查的批次在表格工具确认之前绝不宣称写入成功。完成标准Completion criteria。手册用 you are NOT done until 句式列出四条且声明只有当所有适用条件都为真才允许停止读/汇报类读了相关范围/表最终回答引用了所考虑的 sheet/table 与行写类写入有工具成功响应并且通过回读受影响范围验证、或工具返回了更新后的值破坏性操作类要么在 dry-run 后停下等确认要么只完成了被显式授权的安全阈值内操作最终消息必须说明 sheet/table、tab如适用、range 或行 id、行数、状态、以及跳过/失败的行。若有行写入失败要报告行号/id 和原因。这份完成标准与 skills README 中登记的表格场景范例完全一致write succeeded; affected range verified by read-back or returned updated values; final receipt states sheet, tab, range, row count, and skipped rows.内置工作示例Worked example。模板末尾内嵌了一个完整的运行示例用来示范一次成功运行长什么样用户Mark all closed-won deals from this week as paid in the Pipeline sheet.打开 Pipeline sheettab 为 Deals读表头定位 Stage、Close Date、Payment Status 三列找出 Stage Closed Won 且 Close Date 在本周的行仅对匹配行在 Payment Status 写 Paid回读受影响范围或使用返回的更新值回复Updated 7 rows in Pipeline Deals, column G (Payment Status), rows 14, 22, 23, 31, 39, 44, 51. Verified by reading back G14:G51.这个示例刻意演示了精确的范围引用column G、G14:G51、逐行 id 的确认回执、以及读取-写-回读验证的闭环。Builder 的自审规则也要求生成的提示词中worked example 必须演示一次完整运行skills README 最终审计清单。必须强制执行的四条行为规则Required behavioral rules 一节规定了 Builder 产出提示词时必须内嵌的约束带安全边界果断性仅当恰好存在一张相关表时才允许默认否则写入前必须问清缺失的表身份输出格式确认信息必须包含 sheet/table 名称、tab、range/行 id、行数、验证状态五要素完成标准标注 CRITICAL读/写发生 写入被验证 范围被报告或者 dry-run 已停下等待确认——这是整份手册最重要的章节安全性破坏性写入/删除/清空必须显式确认除非编码了自主安全阈值。这四条与 Builder 主提示词中质量门槛呼应写入set-agent-instructions前的自审清单同样要求无占位符残留、能力只描述真实附加的、完成标准具体可验证、缺失访问的回退路径存在、最终回复格式明确agent-builder-agent.ts#L149-L157 与 质量门槛清单。能力选择原则只挂一个表格工具Capabilities to prefer 一节给出了带优先级的能力清单用户平台对应的那个表格工具Google Sheets、Excel/Office365、Airtable——除非用户的成果是在两个系统之间同步否则恰好只挂一个若 Agent 需要推理时间节奏this week、last month附一个日期/时间工具若用户提到周期每日、每周用工作流按计划运行该 Agent。并有一条反向约束除非用户明确要求用代码计算自定义公式否则不要附加代码执行工具。这与 Builder 主提示词不许以防万一地附加任何能力agent-builder-agent.ts#L199的硬性规则同源。反模式清单五种必须拒绝的错误提示词形态手册把常见错误具象化为五类反模式作为 Builder 自审时的拒绝清单没有验证写回步骤的表格 Agent——模型会幻觉出成功这是被放在第一条的反模式对应完成标准中回读或工具返回更新值的要求在多张候选表之间静默自选——只在恰好可见一张相关表时才允许默认同一轮里 dry-run 之后未经确认就执行破坏性操作同时挂 Sheets 和 Excel 两个工具却没有同步理由——Agent 会开始猜该写哪个系统缺少凭据缺失即拒绝规则的表格 Agent 提示词。完整工作示例从一句需求到生成 Agent手册末尾的 Worked example (full) 演示了 Builder 拿到一句非技术需求后的完整产出用户请求Build me an agent that updates my Google Sheet of leads every morning.给我建一个每天早上更新我 Google Sheet 线索表的 Agent。产出的 Agent名称Leads Sheet Updater套用Domain Sheet Updater命名模式描述Refreshes your leads sheet each morning with new entries and flags stale rows.一句话点明数据源与动作模型结构化、大批量工作选用快速、低成本可用的模型附加工具仅 Google Sheets 集成若用户要求则再加调度器。若表单快照中根本没有 Sheets 集成生成的系统提示词必须指示 Agent 拒绝执行并要求连接集成——缺失能力回退被写进提示词而不是被忽略系统提示词摘录You are Leads Sheet Updater. Each morning you refresh the Leads sheet by appending new leads and flagging leads with no activity in 14 days.Completion criteria: new rows appended; stale rows flagged in the Status column; affected range verified by read-back or returned updated values; final receipt states sheet, tab, range, counts, and skipped rows.这个示例浓缩了整份手册的落点命名/描述模式、最小能力集单一表格工具 可选调度、缺失集成的强制回退、以及带验证动作的完成标准全部在一次用户请求 → 生成 Agent中体现。小结这份手册回答了哪三个问题spreadsheet-agent/SKILL.md表面上是一份提示词模板实际上是 Agent Builder 保证表格类 Agent 能真正干完活的三问三答写什么以 run contract 为骨架触发、拥有的结果、真实能力、缺失回退、完成标准、最终回复格式用身份模板、选表策略、决策规则逐节实例化且所有能力必须来自表单快照中真实存在的能力怎么不出事写入前回读、匹配列类型、破坏性操作 dry-run 显式确认、超阈值拒绝、凭据缺失干净拒绝怎么证明干完了写入必须有工具成功响应加回读/返回值验证最终回执必须包含 sheet、tab、range、行数与跳过行——在工具确认之前绝不宣称写入成功。如果你想为 Mastra 的 Builder 增加新的 Agent 原型skills README 给出了完整的操作步骤新建archetype-agent/目录、按九段式内部模板编写 SKILL.md、在 description 中放入用户会使用的触发词、显式定义 run contract 各要素与完成标准由于工作区在构建时通过静态的skills: [skills]路径加载*/SKILL.md新增技能不需要任何代码改动。【免费下载链接】mastraMastra is the modern TypeScript framework for AI-powered applications and agents.项目地址: https://gitcode.com/GitHub_Trending/ma/mastra创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考