Datawhale AI 夏令营 学习笔记 讯飞 Skill 参赛踩坑实录整合版面向参加讯飞 AI 开发者大赛 Skill 类赛题要写参赛作品说明 / Skill 规范文件SKILL.md的同学。本文本身是 Markdown 文件可直接当示例对照看。整合来源① 今天「讯飞 AI 开发者大赛 Skill 类赛题」整轮实战采访→定义→生成→自检→打包② 真实审核反馈多源表格批量清洗合并助手因公式注入被拒。一、Markdown 基础创建1. 创建文件新建文本文件扩展名改为.md如notes.md/SKILL.md。纯文本编辑器即可VS Code、记事本、Typora不需要特殊软件。预览VS Code 右上角「打开预览」或拖进浏览器需插件/支持 md 的查看器。2. 标题#数量 层级# 一级标题最大 ## 二级标题 ### 三级标题#后必须有一个空格建议一篇只一个一级标题。3. 强调粗体 / 斜体**加粗** *斜体* ***加粗斜体***用英文星号*不是中文。4. 列表- 无序项 A - 无序项 B - 子项前加 2 空格缩进 1. 有序项一 2. 有序项二无序用-/*/有序用数字.符号后必须空格缩进用空格不用 Tab。5. 代码行内反引号包裹如print(hi)。代码块三个反引号 包裹并标注语言defhi():print(hello)踩雷点写完一定要用三个反引号闭合否则后面全文变代码。6. 表格| 列1 | 列2 | | --- | --- | | A | B |第二行| --- | --- |是分隔行不能省列数要一致。7. 链接与图片[显示文字](https://example.com) 链接[]()图片多一个!路径用相对路径更稳。8. 引用与分割线 这是引用常用于提示/备注。 --- !-- 三个减号独占一行 分割线 --9. 任务列表- [x] 已完成 - [ ] 待办10. FrontmatterYAML 头用于 SKILL.md用---上下包裹放在文件最开头--- name: 多源表格批量清洗合并助手 description: 输入多个Excel/CSV文件夹清洗去重合并为merged.xlsx适用于汇总各班成绩单的场景触发词合并表格、汇总成绩单、去重合并数据 ------必须独占一行字段名后冒号:紧跟一个空格。Agent Skills 标准里 frontmatter只保留namedescription两个必填字段不要多加。二、讯飞 Skill 开发全流程 SOP结合今天实战今天我们用「教练 产品经理 创建助手」连续流程做了两个 Skill沉淀出可复用 SOP1. 先对齐赛题四大方向方向覆盖赛题举例一、智能文档解析金融材料解析、医疗理解、多源检索分析二、智能分析与决策数据智能分析、人才匹配、代码辅助三、智能生成与创作全场景内容创作、电商内容、政务公文、办公协同四、智能服务与陪伴智慧生活助理、教育智能辅助与个性化学习2. 3 轮采访法≤3 轮、每轮 ≤3 问信息够就停止追问第1轮身份 → 最重复/耗时/易错的工作 → 交付结果。第2轮补缺口——赛题类别 / 用户输入 / 期望输出。第3轮验收标准——什么算成功 / 什么不能编造 / 有无真实样例。3. 收敛成「需求定义卡」12 字段名称、目标用户、赛题类别、覆盖赛题、关键词价值点、真实场景、用户输入、Skill 输出、标准流程、触发词、验收标准、不该做什么。4. 生成 SKILL.md开头---包裹 frontmatter仅namedescription。正文写清角色定位、何时使用、范式方法论、输入处理、输出模板、工作流程、约束、示例。可附带references/范式详解assets/样例让 Skill 更厚实。5. name 命名公式细分场景 核心动作 定位中文8–15 字具象禁止泛化如文档助手“办公助手”、禁止版本号/英文后缀。例学生PPT结构化大纲生成器、学生假期出游行程规划助手、多源表格批量清洗合并助手。6. description 三段式顺序不可逆分号分隔核心能力 适用场景 触发词核心能力段写清「输入类型 处理动作 输出产物」精确到格式。适用场景段讲清何时加载并隐含能力边界。触发词段≥6 个书面口语混合必须是用户真会说的原话。7. 自测 打包无真实样例 → 先造最小模拟样例跑通显式提醒请替换为真实样例。打包PowerShell路径含特殊字符用双引号Compress-Archive-Pathskill-folder/*-DestinationPathskill-folder.zip-Force今日产物student-ppt-outline-generator.zip智能生成与创作、student-trip-planner.zip智能服务与陪伴。三、踩雷实战整合原雷 1–10 今日新增雷 1Frontmatter 的---不干净错误---前后多空格、写成--/----YAML 直接解析失败。正确正好三个减号独占一行文件第一行就是---。雷 2YAML 冒号后没空格# 错误name:多源表格批量清洗合并助手# 正确name:多源表格批量清洗合并助手缺空格会导致整个 frontmatter 报错连带「请求参数不合法」。雷 3中英文标点混用Markdown 符号# * - |等必须英文半角。常见事故用中文当分割线、用中文引号包路径渲染器全不认。雷 4提交「请求参数不合法」的 3 个真凶按概率作品名称 ≠ frontmatter 的name表单作品名称必须一字不差等于name含汉字、不带引号/空格/版本号。包里混入了非允许文件平台通常只允许.md.py。把样例class1.csv一起打进 ZIP 会被拒。ZIP 套了多余文件夹 / 体积不符要求解压后SKILL.md在根目录zip/SKILL.md不要多套一层zip/skill/...。雷 5写出数据时的「公式注入」安全坑今日已真实触发审核不通过并已修复真实案例多源表格批量清洗合并助手本次审核暂不能通过——脚本在clean_merge.py:149、clean_merge.py:168把多份 Excel/CSV 内容直接导出到merged.xlsx和summary.xlsx却没有对 - 开头的单元格做中和存在公式注入风险。原理单元格以 - 开头如备注写成HYPERLINK(...)或cmd|...甚至看似无害的22Excel 会当公式执行可造成数据外泄/执行风险。错误修复踩过的坑只在写入前给危险字符串加前导单引号是不够的——pandas/openpyxl 写出链路仍可能把以开头的内容再次识别为公式。审核实测22经写前加前缀后生成的merged.xlsx里该单元格仍是公式单元格。正确修复两层兜底写前neutralize()给 - 开头的用户可控字符串加前导单引号第一道防线。写后用 openpyxl重新打开已写出的 xlsx对触发符单元格显式设置quotePrefixTruenumber_format文本格式彻底强制按文本存储FORMULA_TRIGGERS(,,-,)defneutralize(v):ifisinstance(v,str)andv[:1]inFORMULA_TRIGGERS:returnv# 写前第一道防线returnvdefforce_text_cells(path):wbload_workbook(path)forwsinwb.worksheets:forrowinws.iter_rows():forcellinrow:rawcell.valueifisinstance(cell.value,str)elseifraw[:1]:rawraw[1:]ifcell.data_typeforraw[:1]inFORMULA_TRIGGERS:cell.valueraw cell.quotePrefixTrue# 带引号文本前缀cell.number_format# 强制文本格式wb.save(path)# to_excel 之后调用 force_text_cells(merged_path) / force_text_cells(summary_path)验证技巧别只看 pandas 读回的值必须直接检查 xlsx 底层 XML 是否含f公式节点才算数。已补regression_test.py构造含22、3、-4、SUM(A1)的 CSV跑完整 CLI断言无data_typef单元格、危险单元格quotePrefixTrue、底层 XML 无f——实测 PASS。雷 6代码块忘了闭合写一半去忙回来发现后面全成代码块——最高频「排版炸了」。习惯先写开头立刻写结尾再填中间。雷 7列表缩进用 Tab不同渲染器对 Tab 支持不一子列表可能不生效。统一用空格通常 2 个缩进。雷 8表格列数对不齐分隔行与内容行列数必须相同少了错位、多了被忽略。长表格先 Excel 排好再粘成 md可用在线互转工具。雷 9特殊字符未转义显示字面#*\|可在前加\\# 这不是标题是井号表格单元格里写|要转义成\|否则被当列分隔。雷 10改了文件但预览没刷新编辑器缓存 / 预览未自动刷新误以为改动没生效。手动 CtrlS 并重开预览确认。雷 11采访问题太开放 / 漏关键输入维度现象第1轮问最耗时工作若不加约束会收到一句很多或像出游规划那轮用户没选天数Skill 跑起来缺主语。对策每问绑死服务于选方向/定场景/定输入输出在 SKILL.md 写兜底如天数缺失则主动询问或默认 3 天。雷 12description 模糊 / name 泛化现象写处理各类文档让 AI 不知何时加载、跨场景误触发name 用智能办公助手 v2直接不及格。对策description 写死输入/输出格式 能力边界name 用 8–15 字具象命名公式。雷 13编造实时信息 / 无样例空口说已测试现象出游规划把票价、开放时间写成确定值或没样例就宣称跑通评委一问露馅。对策实时/客观信息一律标以官方为准/待核实先造最小模拟样例跑通并提醒替换。雷 14路径含特殊字符打包报错现象用户名kk带单引号PowerShell 路径易出错。对策路径用双引号包裹单引号在双引号内为字面量正常执行。雷 15教育类 Skill 未确认就硬编现象把13 节课默认成某门内置课结果跑偏。对策先问清「课程来源用户提供/内置/AI生成/ 输出形态对话每课报告·仅对话·仅报告/ 真实样例」再写。四、快速自检清单提交前过一遍Markdown / FrontmatterSKILL.md开头是干净---namedescription 干净---YAML 冒号后有空格---独占一行所有 Markdown 符号为英文半角代码块全部闭合并标注语言表格分隔行存在、列数一致Skill 规范name8–15 字具象无泛化/版本号/英文后缀且 表单作品名称description三段式核心能力适用场景触发词触发词 ≥6 且真实包内只有.md和.py无 CSV/图片/子文件夹ZIP 解压后SKILL.md在根目录不套多余层若导出表格已防公式注入写前neutralize()中和 - 前缀且写后force_text_cells()强制文本化quotePrefix 文本格式底层 XML 无f公式节点用regression_test.py覆盖 - 验证 PASS无真实样例时已用最小模拟样例自测并提醒替换流程 / 内容采访已收敛到单一具体场景与明确输入输出验收标准可量化如动线合理/预算可控/细节齐全/可照做不编造实时/客观信息缺失标待核实关键输入维度缺失已在 SKILL.md 写兜底逻辑