# 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: 不用于单点事实问答