Optimize Skill Md

Skillmd Optimize

📝 简介

对照 标准书写格式 对目标 SKILL.md 进行全面优化：修复 YAML 描述、重组章节结构、精简冗余内容、统一术语格式。

✨ 功能特性

硬约束

• 仅改 SKILL.md：不修改 README.md、scripts/、references/ 等其他文件
• 保留原有逻辑：不改变 Skill 的功能行为，仅优化表达
• 保持引用路径：不改动文件间的引用关系
• 强制开头章节：每个 SKILL.md 必须以「📝 简介」和「✨ 功能特性」章节开头

优化流程

Step 1: 读取并分析

1. 读取目标 SKILL.md 2. 读取 standard-format.md 3. 按以下维度逐项评估，标记问题点：

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. 读取用户输入...

# ✅ 开头先展示简介和功能特性
## 📝 简介
根据关键词搜索抖音热门作品，结果以表格展示。支持按日期和赛道筛选。

## ✨ 功能特性
| 功能模块 | 能力描述 | 核心价值 |
|---------|---------|---------|
| 爆款搜索 | 关键词搜索抖音爆款作品 | 精准发现高热度内容 |
| 日期筛选 | 支持按日期范围筛选 | 定位特定时间段热门内容 |
| 赛道分类 | 支持按赛道分类查询 | 精准定位垂直领域 |
| 表格输出 | 结构化表格展示结果 | 直观对比作品数据 |

输出要求

优化完成后输出：

1. 变更摘要：列出修改项及原因（简洁，每条一行） 2. 落盘：使用 SearchReplace 将优化后的内容写入目标 SKILL.md 3. 统计：优化前行数 → 优化后行数，描述质量是否提升

上报使用记录

每次执行优化前，调用 python3 scripts/record.py 上报记录，失败不影响主流程。

SKILL.md Structural Optimizer / optimize-skill-md

---

Introduction

A one-click tool that audits and optimizes any SKILL.md against the Skills MD Standard Format, covering description quality, section structure, content conciseness, and formatting consistency — making skill documentation more standardized and easier for Agents to match accurately.

Core Value

• Better Descriptions: Automatically fixes the YAML description to include third-person phrasing, WHAT + WHEN context, and trigger keywords, improving Agent trigger accuracy.
• Clear Structure: Enforces the standard opening sections (Introduction + Features), restructures/merges/removes empty sections for a clean document hierarchy.
• Lower Token Cost: Strips redundant explanations and filler text, keeping the main body within 500 lines.

Ideal For

• 🛠️ Skill Developers — Quickly bring hand-written or legacy SKILL.md files up to standard without manual checklist review.
• 📦 Skill Maintainers — Batch-normalize terminology, formatting, and section structure across an entire skill library.
• 🆕 New Skill Authors — Get structural guidance on first write, avoiding common anti-patterns.

---

Features

Core Capabilities

• YAML Description Fix: Auto-completes third-person descriptions, trigger scenarios, and trigger keywords within a 1024-character limit.
• Section Restructuring: Enforces the standard opening (📝 Introduction + ✨ Features), merges short sections, splits long sections, and removes empty sections.
• Redundancy Removal: Strips background knowledge explainers, repeated statements, and filler phrases while preserving core business rules and constraints.
• Format Normalization: Unifies terminology across the document, labels code blocks with language types, uses forward-slash paths, and aligns tables.
• Progressive Refactoring: Suggests moving detailed content to a references/ directory when the file exceeds 500 lines, keeping the main body lean.

---

Usage Guide

Simply describe your optimization need in natural language — no commands to memorize.

Common Phrases

---

Use Cases

---

SKILL.md 结构优化工具 / optimize-skill-md

---

简介

一键对照《Skills MD 标准书写格式》，对任意 SKILL.md 进行描述质量、章节结构、内容简洁度与格式规范的全方位优化，让技能文档更规范、更易被 Agent 准确匹配。

核心价值

• 描述提质：自动修复 YAML description，确保第三人称、WHAT + WHEN、触发词齐全，提升 Agent 触发准确率。
• 结构规范：强制简介 + 功能特性章节开头，重组/合并/删除空壳章节，文档层次清晰。
• 降本增效：精简冗余科普与重复说明，降低 token 开销，保持主体 ≤ 500 行。

适用对象

• 🛠️ Skill 开发者 — 快速将手写或历史 SKILL.md 规范化，省去逐条对照检查的时间。
• 📦 技能维护者 — 批量统一术语、格式与章节结构，保持技能库整体一致性。
• 🆕 新手 Skill 作者 — 首次编写 SKILL.md 时获得结构引导，避免常见反模式。

---

功能特性

核心功能

• YAML 描述修复：自动补全第三人称描述、触发场景与触发词，控制 1024 字符以内。
• 章节结构重组：强制「📝 简介 + ✨ 功能特性」开头，合并短章节、拆分长章节、删除空壳章节。
• 冗余内容精简：删除基础知识科普、重复说明、冗余修饰词，保留核心业务规则与约束。
• 格式统一规范：术语全文一致、代码块标注语言类型、路径使用正斜杠、表格对齐。
• 渐进式重构：超过 500 行时自动建议将详细信息外移至 references/ 目录，主体保持精简。

---

使用指南

直接用自然语言描述你的优化需求即可，无需记忆命令。

常用说法速查

---

使用场景

---

Skills MD 标准书写格式

本文档定义了 SKILL.md 的书写规范，涵盖描述质量、章节结构、内容简洁度、格式一致性四大维度。

---

1. YAML Frontmatter 规范

description 字段（关键）

description 是 Agent 决定何时应用该 Skill 的核心依据，必须满足：

检查清单：

• [ ] 使用第三人称
• [ ] 包含 WHAT（功能描述）
• [ ] 包含 WHEN（触发场景 + 触发词）
• [ ] ≤ 1024 字符

---

2. 章节结构规范

2.1 层级规范

# 一级标题              → Skill 名称，简洁描述核心功能
## 二级标题             → 主要章节（概述、鉴权、流程、输出格式等）
### 三级标题            → 子章节（仅在内容确实需要细分时使用）

2.2 推荐章节（SKILL.md 用）

2.3 不应写入 SKILL.md 的内容

以下内容属于 README.md（用户文档），不应出现在 SKILL.md：

• "一键安装" 步骤
• "使用场景" 的角色扮演描述
• "项目架构" 的目录树和技术栈
• "常见问答"
• 基础知识科普（Agent 已知的背景信息）

---

3. 内容简洁度规范

3.1 核心原则

默认假设：Agent 已经非常聪明。只添加它不知道的上下文。

每条信息写入前问自己：

• "Agent 真的需要这个解释吗？"
• "我能假设 Agent 知道这个吗？"
• "这一段值得它的 token 开销吗？"

3.2 删减目标

3.3 行数控制

• SKILL.md 主体 ≤ 500 行
• 超过 500 行时：将详细信息外移至 references/ 目录

---

4. 格式一致性规范

4.1 术语统一

全文使用同一术语，禁止混用：

4.2 表格规范

| 列1 | 列2 | 列3 |
|-----|-----|-----|
| 内容 | 内容 | 内容 |

• 表头与分隔符对齐
• 内容短时不强制对齐空格

4.3 代码块规范

````markdown

python3 scripts/search.py "关键词"

{"key": "value"}

````

• 必须标注语言类型
• 禁止无标注的代码块

4.4 路径规范

• ✅ scripts/search.py
• ✅ references/api-config.md
• ❌ scripts\search.py（Windows 风格）
• ❌ ./scripts/search.py（冗余 ./ 前缀）

4.5 Emoji 使用

适度使用 emoji 强化关键节点识别：

• 章节标记：## 📊 输出格式
• 状态提示：⚠️ 注意、✅ 正确、❌ 错误
• 数据展示：📊 榜单、🔥 热门、📩 订阅

禁止：每行都用 emoji 装饰，喧宾夺主。

---

5. 渐进式披露规范

5.1 文件组织

skill-name/
├── SKILL.md              # 核心指令（≤ 500 行）
├── references/           # 详细参考资料
│   ├── api-config.md     # API 配置细节
│   ├── interaction-guide.md  # 交互流程细节
│   └── data-format.md    # 数据字段说明
└── scripts/              # 可执行脚本

5.2 引用方式

在 SKILL.md 中引用：

详见 [api-config.md](references/api-config.md)

• 保持 一级深度：只从 SKILL.md 直接引用 references/ 下的文件
• 禁止深层嵌套引用（references/a.md → references/b.md）

5.3 外移判断标准

以下内容应外移至 references/：

• 超过 20 行的 API 参数枚举表
• 超过 30 行的交互决策树
• 完整的数据字段映射表（超过 10 个字段）
• 历史版本 / 废弃用法

---

6. 反模式

---

7. 快速检查清单

优化完成后逐项验证：

• [ ] description 第三人称 + WHAT + WHEN + 触发词
• [ ] SKILL.md 开头包含「📝 简介」和「✨ 功能特性」章节
• [ ] SKILL.md 包含「🔑 鉴权」章节且位于功能特性之后
• [ ] SKILL.md ≤ 500 行
• [ ] 术语全文统一（选择一个术语，全文替换）
• [ ] 代码块标注语言类型（``bash、``json 等）
• [ ] 路径使用 / 分隔符
• [ ] 引用文件均为一级深度
• [ ] 无时间敏感信息
• [ ] 无 Windows 风格路径
• [ ] 无空壳章节
• [ ] 无基础知识科普