65 lines
2.7 KiB
Markdown
65 lines
2.7 KiB
Markdown
# Skill Management Pitfalls
|
||
|
||
Learned from attempting to optimize the skill library based on SkillRouter paper findings.
|
||
|
||
## Pitfall 1: "Same Output" ≠ "Functionally Overlapping"
|
||
|
||
**Wrong:** Deleted `pptx-generator` (python-pptx) because `powerpoint` (pptxgenjs) also makes .pptx files.
|
||
**Right:** Different tech stacks = different fallback options. python-pptx is pure Python, pptxgenjs needs Node.js. Keep both.
|
||
|
||
**Rule:** Two skills overlap only when they use the same tools AND serve the same user intent. Same output format is not enough.
|
||
|
||
## Pitfall 2: Don't Cross-Reference in Descriptions
|
||
|
||
**Wrong:** In arxiv's description: "需要多源学术搜索优先用 sn-search-academic"
|
||
**Right:** Each skill describes itself only. No competitive recommendations.
|
||
|
||
**Why:** Creates circular dependencies. If skill A recommends B, and B recommends A, the LLM loops.
|
||
|
||
## Pitfall 3: Don't Expose Implementation Details
|
||
|
||
**Wrong:** In sn-infographic description: "需要 SN_API_KEY"
|
||
**Right:** "需要 SenseNova API"
|
||
|
||
**Rule:** Descriptions should express user-facing capabilities, not internal tool/API names.
|
||
|
||
## Pitfall 4: Check Hard Dependencies Before Deleting
|
||
|
||
**Wrong:** Marked sn-research-planning for deletion because it was "never called."
|
||
**Right:** sn-deep-research calls it via `skill_view("sn-research-planning")` at runtime. Deleting breaks the pipeline.
|
||
|
||
**How to check:**
|
||
```python
|
||
# Search all SKILL.md files for references to the target skill name
|
||
# Only HARD dependencies count: skill_view("target-name") or "读取 target-name"
|
||
# "Related skills" mentions are SOFT and don't block deletion
|
||
```
|
||
|
||
## Pitfall 5: "Never skill_view'd" ≠ "Unused"
|
||
|
||
Skills can be auto-loaded via the system prompt's "MUST load" instruction without explicit `skill_view()` calls. Session data only shows explicit tool calls.
|
||
|
||
**Better metric:** Check if the skill is referenced as a runtime dependency by other skills.
|
||
|
||
## Pitfall 6: Don't Batch Recommendations Without Verification
|
||
|
||
**Wrong:** Generated all 87 recommendations at once, sent to user, then had to fix multiple errors.
|
||
**Right:** Verify each category before sending. Check dependencies. Then send once.
|
||
|
||
**User feedback:** "你这建议就不能确认好之后再发给我吗" (Can you verify before sending?)
|
||
|
||
## Description Quality Formula
|
||
|
||
Good skill description = **What it does** + **Trigger words** + **Negative boundary**
|
||
|
||
Example:
|
||
```
|
||
"深度调研全流程编排器（入口 skill）。自动完成：规划→分维度取证→综合→成稿。
|
||
触发词：深度研究/调研/全面研究/调研报告/deep research。
|
||
不用于：单点事实问答、一句话摘要。"
|
||
```
|
||
|
||
- What: 深度调研全流程编排器
|
||
- Triggers: 深度研究/调研/全面研究
|
||
- Boundary: 不用于单点事实问答
|