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

optimize-skill-md

Writing & research

View repository

Updated 10-16 08:08

About this skill

Optimize SKILL.md

📝 Overview

This duck follows Standard Writing Format to comprehensively optimize the target SKILL.md: fix the YAML description, reorganize the section structure, streamline redundant content, and unify terminology and formatting, making the skill document standardized, easy to use, and easy for an Agent to match accurately.

✨ Features

Feature Module Capability Description Core Value
YAML Fixes 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 externally to references/ Keep the main body concise and controllable
Opening Standardization Mandatory Overview + Features table Identify capability boundaries at a glance

Hard Constraints

  • Only modify SKILL.md: do not modify README.md、scripts/、references/ or 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 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? ≤ 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? Are there Overview and Features at the beginning?
Content Conciseness Are there redundant explanations? Basic knowledge popularization? Repeated explanations? 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 externally? References one level deep?
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
  • 当用户...时使用 Use sentence patterns to indicate trigger scenarios
  • Append at the end 触发词：xxx、xxx
  • Total length ≤ 1024 characters

P2: Reorganize chapter structure

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

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

  • If the original text has no feature 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-one heading # XXX accurately describes the core functionality

  • Merge short sections with content < 5 lines

  • Split long sections > 50 lines

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

  • Delete user-oriented sections that belong in a README (one-click installation, use cases, project architecture, FAQ)

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

P3: Condense 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 subsequent similar examples (keeping 1-2 is sufficient)

P4: Unify formatting

  • Terminology unification: Select one term for the entire text and replace all variants (e.g., use "API interface" to replace "URL", "endpoint", "route")
  • Code block annotation: Add a language type to all code blocks (bash、json、```markdown）
  • Forward slashes in paths：scripts/search.py instead of scripts\search.py
  • Table alignment: Align headers with separators

P5: Progressive refactoring

When SKILL.md exceeds 500 lines:

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

Step 3: Verification

After optimization is complete, check item by item:

  • description is third-person + WHAT + WHEN + trigger words
  • The beginning of SKILL.md includes the "📝 Introduction" and "✨ Features" sections
  • SKILL.md ≤ 500 lines
  • Terminology is unified throughout the text
  • Code blocks are annotated with language types
  • Paths use the / 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 is unchanged

Common optimization patterns

Pattern 1: Description is too general

# ❌
description: 抖音搜索工具

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

Pattern 2: Sections mix in user-oriented content

# ❌ SKILL.md 中出现
## 一键安装
1. 登录平台...
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 features

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

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

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

Output requirements

After optimization is complete, output:

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