redfox-data Skillmd Optimize
📝 简介
对照 标准书写格式 对目标 SKILL.md 进行全面优化：修复 YAML 描述、重组章节结构、精简冗余内容、统一术语格式。
✨ 功能特性
| 功能模块 | 能力描述 | 核心价值 |
|---|---|---|
| YAML 修复 | 第三人称 + WHAT + WHEN + 触发词 | 提升 Agent 匹出准确率 |
| 章节重组 | 合并/拆分/删除空壳章节 | 结构清晰易读 |
| 冗余精简 | 删除科普/重复/修饰词 | 降低 token 开销 |
| 格式统一 | 术语/代码块/路径规范 | 全文一致性 |
| 渐进重构 | 超 500 行外移至 references/ |
主体精简可控 |
| 开头规范 | 强制简介 + 功能特性表格 | 一眼定位能力边界 |
硬约束
- 仅改 SKILL.md：不修改
README.md、scripts/、references/等其他文件 - 保留原有逻辑：不改变 Skill 的功能行为，仅优化表达
- 保持引用路径：不改动文件间的引用关系
- 强制开头章节：每个 SKILL.md 必须以「📝 简介」和「✨ 功能特性」章节开头
优化流程
Step 1: 读取并分析
- 读取目标
SKILL.md - 读取 standard-format.md
- 按以下维度逐项评估，标记问题点：
| 维度 | 检查要点 |
|---|---|
| YAML 描述 | 是否第三人称？包含 WHAT + WHEN？有触发词？≤ 1024 字符？ |
| 章节结构 | 一级标题是否清晰？章节划分合理？有冗余/缺失章节？有空壳章节？开头是否有简介和功能特性？ |
| 内容简洁度 | 存在冗余解释？基础知识科普？重复说明？过长示例（3+）？ |
| 格式规范 | 术语统一？表格标准？代码块标注语言？路径正斜杠？ |
| 渐进披露 | 主体 ≤ 500 行？详细信息在外移？引用一级深度？ |
| 反模式 | Windows 路径？时间敏感信息？多个等价选项？ |
Step 2: 应用优化（按优先级）
P1: 修复 YAML 描述
# ❌ 优化前
description: 处理文件
# ✅ 优化后
description: 从 PDF 文件中提取文本和表格，支持合并和表单填写。当用户处理 PDF 文件或提及 PDF、表单、文档提取时使用。
规则：
- 第三人称描述功能
当用户...时使用句式标注触发场景- 末尾追加
触发词：xxx、xxx - 总长 ≤ 1024 字符
P2: 重组章节结构
强制：SKILL.md 开头必须包含
## 📝 简介（2-3 句话说明核心功能）和## ✨ 功能特性（三列表格：功能模块 | 能力描述 | 核心价值）两个章节，位于一级标题之后、其他章节之前若原文
## 概述/## 产品概述存在，将其重命名为## 📝 简介，内容精简为 2-3 句话若原文无功能特性章节，从 YAML description、交互流程、输出格式中提炼 4-6 条功能要点，以表格形式呈现（功能模块 | 能力描述 | 核心价值）
确保一级标题
# XXX精确描述核心功能合并内容 < 5 行的短章节
拆分 > 50 行的长章节
删除空壳章节（有标题无实质内容）
删除属于 README 的用户向章节（一键安装、使用场景、项目架构、常见问答）
为关键章节添加 emoji 前缀（
## 📊 输出格式、## ⚠️ 注意事项）
P3: 精简冗余内容
删除以下类型内容：
- 基础知识科普（"JSON 是一种数据格式..."）
- 重复说明（同一规则在多处出现）
- 冗余修饰词（"请注意"、"需要特别说明的是"、"众所周知"）
- 第 3 个及以上的相似示例（保留 1-2 个即可）
P4: 统一格式
- 术语统一：全文选定一个术语，替换所有变体（如 "API 接口" 替换 "URL"、"端点"、"路由"）
- 代码块标注：所有代码块添加语言类型（```bash、```json、```markdown）
- 路径正斜杠：
scripts/search.py而非scripts\search.py - 表格对齐：表头与分隔符对齐
P5: 渐进式重构
当 SKILL.md 超过 500 行时：
- 将 API 参数枚举表 → 外移至
references/api-config.md - 将交互决策树 → 外移至
references/interaction-guide.md - 将数据字段映射表 → 外移至
references/data-format.md - 主体中保留核心规则 + 引用链接：
详见 [xxx.md](references/xxx.md)
Step 3: 验证
优化完成后逐项核对：
- description 第三人称 + WHAT + WHEN + 触发词
- SKILL.md 开头包含「📝 简介」和「✨ 功能特性」章节
- SKILL.md ≤ 500 行
- 术语全文统一
- 代码块标注语言类型
- 路径使用
/分隔符 - 引用均为一级深度（SKILL.md → references/xxx.md）
- 无时间敏感信息
- 无空壳章节
- 无基础知识科普
- 功能行为未改变
常见优化模式
模式 1: 描述过于笼统
# ❌
description: 抖音搜索工具
# ✅
description: 抖音爆款作品查询工具。根据关键词搜索抖音热门作品，结果以表格展示。当用户查找抖音热门内容、搜索抖音爆款视频、查询抖音作品数据时使用。触发词：抖音爆款、抖音热门、抖音搜索、爆款视频。
模式 2: 章节混杂用户向内容
# ❌ SKILL.md 中出现
## 一键安装
1. 登录 Coze 平台...
2. 搜索插件...
# ✅ 移至 README.md，SKILL.md 只保留核心规则
模式 3: 冗长交互流程
# ❌ 大段自然语言描述决策分支
# ✅ 使用决策表精简表达
| 用户输入 | 处理方式 |
|---------|---------|
| 今天/当前/最新 | 回复说明最新为昨日数据 |
| 未来日期 | 回复提示，提供昨日数据 |
| 30天内历史 | 直接查询 |
| 超过30天 | 回复提示，提供最接近数据 |
模式 4: 多个等价选项
# ❌
"可以用 pdfplumber、pypdf、PyMuPDF 或 pdfminer..."
# ✅
"使用 pdfplumber 提取文本。扫描件需 OCR 时改用 pdf2image + pytesseract。"
模式 5: 缺少简介和功能特性
# ❌ SKILL.md 直接从交互流程开始
## 交互流程
1. 读取用户输入...
# ✅ 开头先展示简介和功能特性
## 📝 简介
根据关键词搜索抖音热门作品，结果以表格展示。支持按日期和赛道筛选。
## ✨ 功能特性
| 功能模块 | 能力描述 | 核心价值 |
|---------|---------|---------|
| 爆款搜索 | 关键词搜索抖音爆款作品 | 精准发现高热度内容 |
| 日期筛选 | 支持按日期范围筛选 | 定位特定时间段热门内容 |
| 赛道分类 | 支持按赛道分类查询 | 精准定位垂直领域 |
| 表格输出 | 结构化表格展示结果 | 直观对比作品数据 |
输出要求
优化完成后输出：
- 变更摘要：列出修改项及原因（简洁，每条一行）
- 落盘：使用 SearchReplace 将优化后的内容写入目标 SKILL.md
- 统计：
优化前行数 → 优化后行数，描述质量是否提升
上报使用记录
每次执行优化前，调用 python3 scripts/record.py 上报记录，失败不影响主流程。