第八部分：FAQ（20个常见问题）
Q1：Skill和Command有什么区别？
A：Command是"按钮"（触发器），Skill是"APP"（能力包）。Command用于显式触发，Skill用于封装知识和工具。两者通常配合使用：Command作为入口，Skill提供能力。
Q2：必须要SKILL.md吗？
A：是的，SKILL.md 是Skill的唯一必需文件。没有它Claude Code无法识别这是一个Skill。
Q3：SKILL.md可以是任意大小吗？
A：理论上可以，但建议控制在1000行以内。太大的SKILL.md会影响加载速度和AI理解。如果内容很多，考虑使用scripts/、config/等资源文件夹。
Q4：scripts支持哪些语言？
A：主要支持Python和Bash。推荐Python，因为生态好、跨平台、易维护。JavaScript也可以，但不如Python常用。
Q5：如何让Skill自动激活？
A：在SKILL.md的YAML Frontmatter中配置description字段。Claude Code会根据description判断何时激活。例如：
---
description: 当用户要求"添加注释"或"代码注释"时激活
---Q6：可以有多个Skill吗？
A：可以。每个Skill是 .claude/skills/ 下的独立目录，可以有任意多个。
Q7：Skill之间会冲突吗？
A：如果description中描述的触发场景重复可能会冲突。建议每个Skill使用独特的触发场景描述。
Q8：如何更新Skill版本？
A：在SKILL.md的Markdown Body开头添加"版本历史"章节，记录每次变更。例如：
## 版本历史
### V2.0.0 (2025-01-18)
- 适配当前版本新特性
- 改为SKILL.md单文件结构
### V1.0.0 (2025-01-01)
- 初始版本Q9：SKILL.md多大合适？
A：建议单个SKILL.md不超过1000行。太长会影响加载速度和AI理解。大的Skill应该考虑拆分成多个子Skill或使用scripts/。
Q10：如何调试Skill？
A：
- 验证YAML Frontmatter格式
- 手动运行scripts/中的脚本测试
- 检查description是否清晰
- 查看Claude Code的Skill加载日志
Q11：Hot Reloading不生效怎么办？
A：
- 确认修改的是SKILL.md而不是其他文件
- 检查YAML Frontmatter格式是否正确
- 尝试使用
/compact压缩上下文后重试 - 最后手段：重启Claude Code
Q12：如何处理中文路径问题？
A：Windows上尽量避免中文路径。如果必须使用，确保SKILL.md文件编码为UTF-8（带BOM或不带BOM都可以，但要一致）。
Q13：Skill可以调用MCP吗？
A：可以。在SKILL.md的Markdown Body中可以引用MCP工具。Claude Code会自动识别并调用。
Q14：如何共享Skill给团队？
A：将整个 .claude/skills/你的skill/ 目录提交到Git仓库。团队成员克隆后即可使用。
Q15：Skill可以跨项目使用吗？
A：可以。将Skill放在全局配置目录（~/.claude/skills/）即可在所有项目中使用。
Q16：如何回退到旧版本Skill？
A：使用Git回退到旧版本的提交，或者在SKILL.md的版本历史中查看旧版本的内容。
Q17：SKILL.md中可以使用变量吗？
A：SKILL.md 支持一个特殊内置变量 ${CLAUDE_SKILL_DIR}，其他自定义模板变量不支持。
${CLAUDE_SKILL_DIR\} 变量说明：
- 含义：指向当前 Skill 文件（SKILL.md）所在的目录路径
- 用途：在 SKILL.md 正文中引用同目录下的其他文件（模板、配置、示例等）
- 示例：
请阅读 ${CLAUDE_SKILL_DIR}/templates/code-review.md 中的代码审查模板
请参考 ${CLAUDE_SKILL_DIR}/config/rules.yaml 中的规则配置- 优势：使 Skill 可以组织为包含多个文件的目录结构，而不是将所有内容塞进一个 SKILL.md
- 如果需要更复杂的动态内容，使用 scripts/ 中的脚本生成
Q18：如何测试Skill是否正常工作？
A：
- 检查SKILL.md文件结构是否完整（YAML + Markdown）
- 验证YAML Frontmatter格式
- 手动测试scripts/中的脚本
- 在Claude Code中测试触发词
Q19：Skill加载很慢怎么办？
A：
- 减少SKILL.md的行数
- 优化scripts/中的脚本性能
- 检查是否有不必要的config/文件
Q20：如何学习更高级的Skill开发？
A：
- 阅读公众号写作助手项目中的 SKILL.md 正文
- 参考官方Skill示例
- 实践中不断迭代优化
- 理解渐进式披露和Hot Reloading机制