general-skill-refiner
Compare original and translation side by side
🇺🇸
Original
English🇨🇳
Translation
ChineseGeneral Skill Refiner
通用Skill优化器
Overview
概述
Purpose: Critical analysis and improvement of agent skills
Approach:
- Ruthless critique - identify all issues without sugar-coating
- Clear priorities - MUST/SHOULD/NICE to have classification
- Concrete solutions - specific fixes, not just complaints
- User feedback loop - user decides what to fix
- Verify changes - ensure quality after refactoring
Output: Improved skill + change report in
.tasks/skill-refactoring-[date]/目标： 对Agent Skill进行批判性分析与改进
方法：
- 严苛评审：毫不掩饰地识别所有问题
- 清晰优先级：划分为MUST（必须修复）/SHOULD（应该修复）/NICE（锦上添花）三个等级
- 具体解决方案：给出明确的修复方案，而非仅提出问题
- 用户反馈循环：由用户决定修复内容
- 验证变更：重构后确保质量达标
输出： 优化后的Skill + 变更报告，存储在目录下
.tasks/skill-refactoring-[date]/Guidelines
指南
What Makes a Good Skill
优质Skill的标准
Based on Agent Skills Complete Guide:
- Description is king - Most important field for skill triggering
- Progressive disclosure - SKILL.md <500 lines, detailed docs in references/
- Structure > prose - Numbered steps, bullet points, clear conditionals
- Only add what LLM doesn't know - No basic programming tutorials
- One skill = one domain - Focused scope, not "everything-tool"
- Include examples - Show input → output patterns
- No time estimates - Never mention how long things take
基于《Agent Skills完全指南》：
- 描述是核心：Skill触发的最重要字段
- 渐进式披露：SKILL.md文件行数控制在500行以内，详细文档放在references/目录中
- 结构优于行文：使用编号步骤、项目符号、清晰的条件分支
- 仅补充LLM未知的内容：不包含基础编程教程
- 单一Skill对应单一领域：聚焦特定范围，而非“万能工具”
- 包含示例：展示输入→输出的模式
- 无时间预估：绝对不能提及完成时长
Common Anti-Patterns to Look For
需要规避的常见反模式
- ❌ The Encyclopedia - 5000+ line SKILL.md (should split to references/)
- ❌ The Everything Bagel - Skill applies to every task (should be a rule)
- ❌ The Secret Handshake - Agent never loads skill (bad description)
- ❌ The Fragile Skill - Hardcoded absolute paths (use relative paths)
- ❌ The Wall of Text - Unstructured prose (needs headers/lists/steps)
- ❌ Time Estimates - Any mention of duration (strictly forbidden)
- ❌ 百科全书式：SKILL.md文件超过5000行（应拆分至references/目录）
- ❌ 万能工具式：Skill适用于所有任务（应调整为规则类）
- ❌ 隐秘触发式：Agent无法加载Skill（描述质量差）
- ❌ 脆弱Skill：使用硬编码绝对路径（应使用相对路径）
- ❌ 文本墙：无结构的大段文字（需添加标题/列表/步骤）
- ❌ 时间预估：任何提及时长的内容（严格禁止）
Priority Levels
优先级等级
🔴 PRIORITY 1: MUST FIX (breaking issues)
- Core guideline violations (time estimates, etc.)
- Structural problems (too long, disorganized)
- Missing critical functionality
- Contradictions or confusion
🟡 PRIORITY 2: SHOULD FIX (quality issues)
- Suboptimal workflow
- Redundant content
- Missing helpful features
- Can be simplified
🟢 PRIORITY 3: NICE TO HAVE (enhancements)
- Small improvements
- Additional examples
- Minor clarifications
🔴 优先级1：必须修复（影响功能的问题）
- 违反核心指南（如时间预估等）
- 结构问题（过长、混乱）
- 缺失关键功能
- 内容矛盾或模糊
🟡 优先级2：应该修复（质量问题）
- 工作流程不够优化
- 内容冗余
- 缺失实用功能
- 可简化的内容
🟢 优先级3：锦上添花（增强型改进）
- 小幅度优化
- 添加额外示例
- 细微的内容澄清
Examples
示例
Example 1: Identifying Time Estimates Problem
示例1：识别时间预估问题
Skill analyzed:
code-reviewProblem found:
markdown
Line 45: "This analysis should take about 5-10 minutes"
Line 89: "Quick scan (2-3 minutes)"Priority: 🔴 MUST FIX - Core guideline violation
Fix: Remove all time references:
markdown
Line 45: "This analysis covers security, performance, and style"
Line 89: "Quick scan of critical issues"分析的Skill：
code-review发现的问题：
markdown
第45行："This analysis should take about 5-10 minutes"
第89行："Quick scan (2-3 minutes)"优先级： 🔴 必须修复 - 违反核心指南
修复方案： 删除所有时间相关表述：
markdown
第45行："This analysis covers security, performance, and style"
第89行："Quick scan of critical issues"Example 2: Analysis Report Format
示例2：分析报告格式
For skill: (1200 lines in SKILL.md)
pdf-processorAnalysis presented to user:
undefined针对Skill： （SKILL.md文件共1200行）
pdf-processor呈现给用户的分析报告：
undefined🔴 MUST FIX
🔴 必须修复
1. SKILL.md Too Long (1200 lines)
1. SKILL.md Too Long (1200 lines)
Problem: Exceeds recommended 500 line limit
Impact: Loads unnecessary content into context
Fix: Move detailed API docs to references/api-reference.md
Problem: Exceeds recommended 500 line limit
Impact: Loads unnecessary content into context
Fix: Move detailed API docs to references/api-reference.md
2. Time Estimates Found
2. Time Estimates Found
Problem: Lines 234, 456, 789 contain time estimates
Fix: Remove phrases "takes 2 minutes", "quick 30 second scan"
Problem: Lines 234, 456, 789 contain time estimates
Fix: Remove phrases "takes 2 minutes", "quick 30 second scan"
🟡 SHOULD FIX
🟡 SHOULD FIX
3. Missing Examples Section
3. Missing Examples Section
Problem: No concrete input → output examples
Fix: Add examples showing PDF processing workflow
Problem: No concrete input → output examples
Fix: Add examples showing PDF processing workflow
🟢 What's Good
🟢 What's Good
- Clear step-by-step workflow
- Good error handling coverage
- Scripts are well-documented
---- Clear step-by-step workflow
- Good error handling coverage
- Scripts are well-documented
---Example 3: Before/After Refactoring
示例3：重构前后对比
Before:
markdown
undefined重构前：
markdown
undefinedHow to Use
How to Use
So basically when you want to process a PDF you should first
check if the file exists and then you know, read it and extract
the text content which might take a few minutes depending on the
size, and then process it according to what the user needs...
- Line count: 15 lines of prose
- Structure: Wall of text
- Time estimates: Yes (forbidden)
**After:**
```markdownSo basically when you want to process a PDF you should first
check if the file exists and then you know, read it and extract
the text content which might take a few minutes depending on the
size, and then process it according to what the user needs...
- 行数：15行散文式文本
- 结构：文本墙
- 时间预估：存在（禁止内容）
**重构后：**
```markdownHow to Use
使用方法
Process PDF files:
- Validate PDF exists
- Extract text using
scripts/extract.py - Parse output for required format
- Return processed content
For detailed extraction options, see references/extraction-guide.md
- Line count: 11 lines
- Structure: Clear numbered steps
- Time estimates: None ✅
---处理PDF文件：
- 验证PDF文件是否存在
- 使用提取文本
scripts/extract.py - 解析输出以符合要求格式
- 返回处理后的内容
详细提取选项请参考references/extraction-guide.md
- 行数：11行
- 结构：清晰的编号步骤
- 时间预估：无 ✅
---Workflow
工作流程
Phase 1: Read & Understand
阶段1：阅读与理解
Cel: Dogłębnie zrozumieć skill i jego strukturę.
Kroki:
-
Read main SKILL.md:
- Zrozum cel i workflow
- Zmierz długość (wc -l)
- Zidentyfikuj główne phases
-
Read wszystkie references:
- Sprawdź co jest w references/
- Zmierz długość każdego pliku
- Zrozum jak references wspierają main skill
-
Compare z innymi skillami:
- Porównaj długość SKILL.md z innymi skillami
- Sprawdź total długość references/
- Zidentyfikuj pattern differences
Output: Pełne zrozumienie skilla i jego kontekstu.
目标： 深入理解Skill及其结构。
步骤：
-
阅读主SKILL.md文件：
- 理解目标与工作流程
- 统计行数（使用wc -l命令）
- 识别主要阶段
-
阅读所有references文件：
- 检查references/目录中的内容
- 统计每个文件的行数
- 理解references如何支撑主Skill
-
与其他Skill对比：
- 对比SKILL.md文件行数
- 检查references/目录的总大小
- 识别模式差异
输出： 对Skill及其上下文的全面理解。
Phase 2: Critical Analysis
阶段2：批判性分析
Goal: Ruthlessly identify all problems and group by priority
Analysis Checklist:
Use for complete criteria. Key checks:
references/quality-criteria.mdStructure & Length:
- SKILL.md line count (target: <500 lines)
- Total references/ size
- Clear sections with headers
- Numbered steps for procedures
- Bullet points for criteria
Content Quality:
- No time estimates anywhere (NEVER allowed)
- No "wall of text" sections (needs structure)
- No redundant content between SKILL.md and references/
- Examples included (input → output)
- Only adds what LLM doesn't know
Description & Triggering:
- Description contains specific keywords
- Description explains WHEN to use
- Triggers match how users talk about task
- Not too broad ("everything-tool")
Workflow & Features:
- Clear step-by-step workflow
- No missing critical features
- No contradictions or confusion
- Proper references to supporting files
For Each Issue Found:
- Identify: What is the specific problem? (with line numbers)
- Classify: 🔴 MUST / 🟡 SHOULD / 🟢 NICE priority
- Explain: Why is this a problem?
- Propose: Concrete solution (not just "fix this")
Output: Complete prioritized list of issues with solutions
目标： 严苛识别所有问题并按优先级分组
分析检查清单：
完整标准请参考。核心检查项：
references/quality-criteria.md结构与长度：
- SKILL.md文件行数（目标：<500行）
- references/目录总大小
- 带有标题的清晰章节
- 流程使用编号步骤
- 标准使用项目符号
内容质量：
- 任何位置均无时间预估（绝对禁止）
- 无“文本墙”段落（需要结构化）
- SKILL.md与references/之间无冗余内容
- 包含示例（输入→输出）
- 仅补充LLM未知的内容
描述与触发：
- 描述包含特定关键词
- 说明适用场景
- 触发词符合用户谈论任务的方式
- 范围不过于宽泛（非“万能工具”）
工作流程与功能：
- 清晰的分步工作流程
- 无关键功能缺失
- 无矛盾或模糊内容
- 正确引用支持文件
针对每个发现的问题：
- 识别： 具体问题是什么？（标注行号）
- 分类： 🔴 必须修复 / 🟡 应该修复 / 🟢 锦上添花 优先级
- 解释： 为什么这是问题？
- 提议： 具体的解决方案（而非仅“修复此问题”）
输出： 完整的带解决方案的优先级问题列表。
Phase 3: Present & Gather Feedback
阶段3：呈现与收集反馈
Cel: Zaprezentować analizę użytkownikowi i zebrać feedback co poprawiać.
Presentation format:
undefined目标： 向用户展示分析结果并收集修复意见。
呈现格式：
undefined🔴 Główne problemy (MUST FIX)
🔴 核心问题（必须修复）
1. [Problem name]
1. [问题名称]
Problem: [clear description]
Konkretnie: [specific examples with line numbers]
Fix: [concrete solution]
问题： [清晰描述]
具体位置： [带行号的具体示例]
修复方案： [具体解决方案]
2. [Problem name]
2. [问题名称]
...
...
🟡 Średnie problemy (SHOULD FIX)
🟡 次要问题（应该修复）
[...]
[...]
🟢 Co jest dobre
🟢 优点
[List positive aspects - important for balance]
[列出积极方面 - 保持平衡很重要]
💡 Sugestie poprawek
💡 修复建议
Priority 1 (MUST fix):
- [Fix 1]
- [Fix 2]
Priority 2 (SHOULD fix):
[...]
Priority 3 (NICE to have):
[...]
**Zapytaj użytkownika:**
- "Zgadzasz się z tą analizą?"
- "Czy są rzeczy z którymi się nie zgadzasz?"
- "Powinienem wprowadzić te poprawki?"
- "Czy jest coś specyficznego co chcesz zachować/zmienić?"
**Listen for:**
- Co użytkownik zgadza się poprawić
- Co użytkownik chce zachować (nawet jeśli jest suboptimal)
- Dodatkowe insights od użytkownika
**Output:** Jasna lista co poprawiać z user approval.优先级1（必须修复）：
- [修复项1]
- [修复项2]
优先级2（应该修复）：
[...]
优先级3（锦上添花）：
[...]
**询问用户：**
- “您是否认同此分析？”
- “您对哪些内容有异议？”
- “我是否应该实施这些修复？”
- “您有什么特定内容想要保留/修改？”
**倾听重点：**
- 用户同意修复的内容
- 用户希望保留的内容（即使不够优化）
- 用户提供的额外见解
**输出：** 经用户确认的明确修复列表。Phase 4: Refactor
阶段4：重构
Cel: Systematycznie wprowadzić poprawki zgodnie z priorytetami i feedbackiem.
Refactoring workflow:
1. Start with Priority 1 issues:
- Fix one issue at a time
- Verify każdą zmianę
- Don't break other things
2. Then Priority 2:
- Continue systematically
- Show progress
3. Priority 3 if time:
- Only if user wants
- Quick wins first
Refactoring patterns:
Use :
references/refactoring-patterns.md- How to remove time estimates
- How to shorten SKILL.md (move to references)
- How to simplify question flows
- How to add missing features
- How to improve structure
Best practices:
- Make atomic changes
- Test that files are valid
- Keep backups (don't worry, git)
- Verify line counts after changes
Track changes:
Create log in :
.tasks/skill-refactoring-[skill-name]-[date]/changes.md- What was changed
- Why
- Before/after metrics
目标： 根据优先级和反馈系统性实施修复。
重构工作流程：
1. 从优先级1的问题开始：
- 逐个修复问题
- 验证每一项变更
- 避免破坏其他功能
2. 处理优先级2的问题：
- 持续系统性推进
- 展示进度
3. 如有时间处理优先级3的问题：
- 仅在用户要求时进行
- 优先处理快速见效的改进
重构模式：
请参考：
references/refactoring-patterns.md- 如何移除时间预估
- 如何缩短SKILL.md（迁移至references）
- 如何简化问题流程
- 如何添加缺失功能
- 如何优化结构
最佳实践：
- 进行原子化变更
- 验证文件有效性
- 保留备份（无需担心，使用git）
- 变更后重新统计行数
跟踪变更：
在中创建日志：
.tasks/skill-refactoring-[skill-name]-[date]/changes.md- 变更内容
- 变更原因
- 前后指标对比
Phase 5: Verify & Report
阶段5：验证与报告
Cel: Sprawdzić że wszystko działa i podsumować zmiany.
Verification checklist:
✅ Files are valid:
- SKILL.md syntax OK
- All references exist
- No broken links
✅ Metrics improved:
- SKILL.md shorter (if that was goal)
- No time estimates
- Better structure
✅ Quality checklist passed:
- Run through quality-criteria.md
- Wszystkie MUST fixes done
- SHOULD fixes addressed
Report to user:
"Gotowe! Poprawiłem skill [name].
Główne zmiany:
- [Change 1] - [metric before → after]
- [Change 2] - [metric before → after]
- [Change 3]
Metryki:
- SKILL.md: [X] → [Y] linii
- References: [X] → [Y] linii total
- Issues fixed: [Priority 1: X, Priority 2: Y]
Co zostało poprawione:
✅ [Issue 1]
✅ [Issue 2]
✅ [Issue 3]
Co jest lepsze:
- [Improvement 1]
- [Improvement 2]
Szczegółowy raport w "
.tasks/skill-refactoring-[name]-[date]/Zapytaj:
- "Czy chcesz żebym przejrzał jeszcze raz?"
- "Czy są dodatkowe poprawki?"
目标： 验证所有功能正常并总结变更。
验证检查清单：
✅ 文件有效：
- SKILL.md语法正确
- 所有references文件存在
- 无无效链接
✅ 指标优化：
- SKILL.md文件缩短（如果这是目标）
- 无时间预估
- 结构更清晰
✅ 通过质量检查清单：
- 对照quality-criteria.md检查
- 所有必须修复项已完成
- 应该修复项已处理
向用户报告：
“已完成！我优化了Skill [名称]。
主要变更：
- [变更1] - [变更前后指标对比]
- [变更2] - [变更前后指标对比]
- [变更3]
指标：
- SKILL.md：[X] → [Y] 行
- References：[X] → [Y] 行（总计）
- 修复问题数：[优先级1：X，优先级2：Y]
已修复问题：
✅ [问题1]
✅ [问题2]
✅ [问题3]
优化点：
- [优化1]
- [优化2]
详细报告请查看目录”
.tasks/skill-refactoring-[name]-[date]/询问用户：
- “您是否需要我再复查一遍？”
- “是否需要额外的修复？”
Special Cases
特殊情况
User disagrees z analizą
用户不认同分析结果
- To OK - user ma final say
- Explain reasoning ale respect decision
- Document why recommendation was made
- Proceed with user's preferences
- 没问题 - 用户拥有最终决定权
- 解释你的理由但尊重用户决策
- 记录推荐方案的原因
- 按照用户偏好推进
Skill jest fundamentalnie broken
Skill存在根本性问题
- Be honest: "Ten skill wymaga przepisania od zera"
- Explain dlaczego
- Zaproponuj: refactor vs rewrite from scratch
- Let user decide
- 坦诚告知：“此Skill需要从零重写”
- 解释原因
- 提议：重构 vs 从零重写
- 由用户决定
Multiple skille do poprawy
多个Skill需要优化
- Jeden na raz
- Priorytetyzuj który najpierw (ask user)
- Apply learnings z jednego do innych
- 逐个处理
- 确定优先顺序（询问用户）
- 将从一个Skill中学到的经验应用到其他Skill
Refactoring reveals deeper issues
重构过程中发现更深层次问题
- Stop and inform user
- "Zauważyłem [deeper issue] - powinienem to też naprawić?"
- Get approval before expanding scope
- 暂停并告知用户
- “我发现了[更深层次问题] - 是否需要一并修复？”
- 扩大范围前获得用户批准
Quality Checklist
质量检查清单
Przed zakończeniem, upewnij się że:
✅ Analysis was thorough: Checked all aspects z quality-criteria.md
✅ Problems prioritized: Clear MUST/SHOULD/NICE to have
✅ User feedback gathered: User approved changes
✅ Changes implemented: All agreed fixes done
✅ No time estimates: Removed all time references
✅ Structure improved: SKILL.md is clear and not too long
✅ References optimized: Supporting files helpful, not overwhelming
✅ Changes documented: Log created with before/after
✅ Verification done: Quality checklist passed
✅ User satisfied: Final approval received
完成前，请确保：
✅ 分析全面： 对照quality-criteria.md检查所有方面
✅ 问题已划分优先级： 清晰的MUST/SHOULD/NICE等级
✅ 已收集用户反馈： 用户已批准变更
✅ 变更已实施： 所有商定的修复已完成
✅ 无时间预估： 已移除所有时间相关表述
✅ 结构优化： SKILL.md清晰且不过长
✅ References优化： 支持文件实用且不过于繁杂
✅ 变更已记录： 创建包含前后对比的日志
✅ 已完成验证： 通过质量检查清单
✅ 用户满意： 获得最终批准
Key Reminders
关键提醒
DO:
- Be ruthlessly critical in Phase 2
- Prioritize problems clearly (MUST/SHOULD/NICE)
- Give concrete solutions, not just complaints
- Get user feedback before big changes
- Make atomic, verifiable changes
- Document what you changed and why
- Verify quality after refactoring
DON'T:
- Don't sugarcoat problems
- Don't fix without understanding
- Don't change everything at once
- Don't skip user feedback
- Don't ignore user preferences
- Don't forget to verify afterwards
- Don't leave broken files
Twoje podejście: Jesteś bezwzględnym code reviewer który chce żeby skill był najlepszy jaki może być. Identifikujesz problemy, proponujesz rozwiązania, ale ostatecznie user decyduje co poprawiać.
Pamiętaj:
- Skill quality matters - bad skills = bad results
- Be specific - "line 45 has time estimate" not "too many time estimates"
- Priorities are key - fix breaking issues first
- User knows their use case - respect their input
- Document changes - future you will thank you
- Verify everything - broken skill is worse than unchanged skill
需要做：
- 在阶段2进行严苛评审
- 清晰划分问题优先级（MUST/SHOULD/NICE）
- 给出具体解决方案，而非仅提出问题
- 重大变更前获取用户反馈
- 进行可验证的原子化变更
- 记录变更内容与原因
- 重构后验证质量
不要做：
- 不要掩饰问题
- 不要在未理解的情况下修复
- 不要一次性变更所有内容
- 不要跳过用户反馈
- 不要忽视用户偏好
- 不要忘记事后验证
- 不要留下损坏的文件
你的定位： 你是一位严苛的评审者，致力于打造最优的Skill。你识别问题、提出解决方案，但最终由用户决定修复内容。
请记住：
- Skill质量至关重要 - 劣质Skill会导致糟糕的结果
- 表述要具体 - 如“第45行存在时间预估”而非“过多时间预估”
- 优先级是核心 - 先修复影响功能的问题
- 用户了解其使用场景 - 尊重用户输入
- 记录变更 - 未来的你会感谢现在的记录
- 验证所有内容 - 损坏的Skill比未变更的Skill更糟糕