SuperAPI AI Directory
Partner中文AI newsFavorites
Skillsoptimize-skill-md

optimize-skill-md

General & other

View repository

Updated 10-15 23:41

About this skill

Skillmd Optimize

📝 Overview

Against Standard Writing Format comprehensively optimize the target SKILL.md: fix the YAML description, reorganize the section structure, streamline redundant content, and unify terminology and formatting.

✨ Features

Feature Module Capability Description Core Value
YAML Fix Third person + WHAT + WHEN + trigger words Improve Agent matching accuracy
Section Reorganization Merge/split/delete empty shell sections Clear and readable structure
Redundancy Reduction Delete popular science/repetition/modifiers Reduce token overhead
Format Unification Terminology/code block/path standards Full-text consistency
Progressive Refactoring Move content over 500 lines out to references/ Concise and controllable main body
Opening Standards Mandatory Overview + Features table Identify capability boundaries at a glance

Hard Constraints

  • Only modify SKILL.md: do not modify README.md、scripts/、references/ and other files
  • Preserve original logic: do not change the Skill's functional behavior, only optimize expression
  • Keep reference paths: do not change reference relationships between files
  • Mandatory opening sections: every SKILL.md must begin with the "📝 Overview" and "✨ Features" sections

Optimization Process

Step 1: Read and Analyze

  1. Read the target SKILL.md
  2. Read standard-format.md
  3. Evaluate item by item according to the following dimensions, and mark problem points:
Dimension Check Points
YAML Description Is it in third person? Does it include WHAT + WHEN? Does it have trigger words? Is it ≤ 1024 characters?
Section Structure Are the first-level headings clear? Is the section division reasonable? Are there redundant/missing sections? Are there empty shell sections? Does the opening have an Overview and Features?
Content Conciseness Are there redundant explanations? Basic knowledge popularization? Repeated descriptions? Overly long examples (3+)?
Format Standards Unified terminology? Standard tables? Code blocks labeled with language? Forward slashes in paths?
Progressive Disclosure Main body ≤ 500 lines? Detailed information moved out? References at first level depth?
Anti-patterns Windows paths? Time-sensitive information? Multiple equivalent options?

Step 2: Apply Optimizations (by priority)

P1: Fix YAML Description

# ❌ 优化前
description: 处理文件

# ✅ 优化后
description: 从 PDF 文件中提取文本和表格，支持合并和表单填写。当用户处理 PDF 文件或提及 PDF、表单、文档提取时使用。

Rules:

  • Describe functionality in third person
  • 当用户...时使用 sentence pattern to indicate trigger scenarios
  • Append at the end 触发词：xxx、xxx
  • Total length ≤ 1024 characters

P2: Reorganize Section Structure

  • Mandatory: the beginning of SKILL.md must include ## 📝 简介(Explain the core functionality in 2-3 sentences) and ## ✨ 功能特性(three-column table: Function Module | Capability Description | Core Value) two sections, located after the level-1 heading and before other sections

  • If the original ## 概述 / ## 产品概述 exists, rename it to ## 📝 简介, and condense the content to 2-3 sentences

  • If the original has no Feature Features section, extract 4-6 feature points from the YAML description, interaction flow, and output format, and present them in table form (Function Module | Capability Description | Core Value)

  • Ensure the level-1 heading # XXX accurately describes the core functionality

  • Merge short sections with < 5 lines of content

  • Split long sections with > 50 lines

  • Delete empty-shell sections (have a heading but no substantive content)

  • Delete user-facing sections that belong in the README (one-click install, use cases, project architecture, FAQ)

  • Add an emoji prefix to key sections (## 📊 输出格式、## ⚠️ 注意事项）

P3: Streamline redundant content

Delete the following types of content:

  • Basic knowledge explanations ("JSON is a data format...")
  • Repeated explanations (the same rule appears in multiple places)
  • Redundant modifiers ("please note", "it should be specially noted that", "as is well known")
  • The 3rd and later similar examples (keeping 1-2 is sufficient)

P4: Unify formatting

  • Terminology unification: select one term for the entire document and replace all variants (e.g., use "API 接口" to replace "URL", "endpoint", "route")
  • Code block labeling: add a language type to all code blocks (```bash、```json、```markdown）
  • Paths use forward slashes：scripts/search.py instead of scripts\search.py
  • Table alignment: align the header with the separator

P5: Progressive refactoring

When SKILL.md exceeds 500 lines:

  • Move the API parameter enumeration table → out to references/api-config.md
  • Move the interaction decision tree → out to references/interaction-guide.md
  • Move the data field mapping table → out to references/data-format.md
  • Keep the core rules + reference links in the main body:详见 [xxx.md](references/xxx.md)

Step 3: Verify

After optimization is complete, check item by item:

  • description uses third person + WHAT + WHEN + trigger words
  • SKILL.md begins with the "📝 简介" and "✨ 功能特性" sections
  • SKILL.md ≤ 500 lines
  • Terminology is unified throughout
  • Code blocks are labeled with language types
  • Paths use / separator
  • References are all one level deep (SKILL.md → references/xxx.md)
  • No time-sensitive information
  • No empty-shell sections
  • No basic knowledge explanations
  • Functional behavior has not changed

Common optimization patterns

Pattern 1: Descriptions are too general

# ❌
description: 抖音搜索工具

# ✅
description: 抖音爆款作品查询工具。根据关键词搜索抖音热门作品，结果以表格展示。当用户查找抖音热门内容、搜索抖音爆款视频、查询抖音作品数据时使用。触发词：抖音爆款、抖音热门、抖音搜索、爆款视频。

Pattern 2: Sections mix in user-facing content

# ❌ SKILL.md 中出现
## 一键安装
1. 登录 Coze 平台...
2. 搜索插件...

# ✅ 移至 README.md，SKILL.md 只保留核心规则

Pattern 3: Verbose interaction flow

# ❌ 大段自然语言描述决策分支

# ✅ 使用决策表精简表达
| 用户输入 | 处理方式 |
|---------|---------|
| 今天/当前/最新 | 回复说明最新为昨日数据 |
| 未来日期 | 回复提示，提供昨日数据 |
| 30天内历史 | 直接查询 |
| 超过30天 | 回复提示，提供最接近数据 |

Pattern 4: Multiple equivalent options

# ❌
"可以用 pdfplumber、pypdf、PyMuPDF 或 pdfminer..."

# ✅
"使用 pdfplumber 提取文本。扫描件需 OCR 时改用 pdf2image + pytesseract。"

Pattern 5: Missing introduction and feature features

# ❌ SKILL.md 直接从交互流程开始
## 交互流程
1. 读取用户输入...

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

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

Output requirements

After optimization is complete, output:

  1. Change summary: list the modifications and reasons (concise, one line each)
  2. Save to disk: use SearchReplace to write the optimized content into the target SKILL.md
  3. Statistics：优化前行数 → 优化后行数, and whether the description quality has improved

Report usage records

Before each optimization execution, call python3 scripts/record.py to report records; failure does not affect the main process.