用途：编写供未来 Claude 实例使用的技能参考指南，帮助其快速找到并应用有效方法。技能需可发现、可快速浏览、可执行。核心原则：默认 Claude 已足够聪明，只补充其不具备的上下文。
何时创建：技术不直观、模式跨项目通用、会反复参考或对他人有价值时。不适用于一次性方案、已有完善文档的标准做法或项目约定（后者放 .claude/CLAUDE.md）。
结构：YAML frontmatter 仅支持 name 与 description 两字段（合计上限 1024 字符）。name 仅限字母、数字、连字符，最多 64 字符，用动名词形式，避免保留词 anthropic、claude。description 用第三人称，以 Use when... 开头，需同时包含触发条件与技能作用。正文推荐分段：Overview、When to Use、Quick Reference、Implementation、Common Mistakes，可选 Real-World Impact。
自由度：任务越灵活越应给宽泛指引，越关键越要写明确步骤与校验。
搜索优化（CSO）：未来 Claude 依据 description 判断相关性，应包含错误信息、症状、同义词、工具名等关键词。
命名：用动名词，如 creating-skills、processing-pdfs，避免 Helper、Utils 等模糊名称。
代码示例：一个优秀示例胜过多个平庸示例，需完整可运行、注释说明原因、来自真实场景、同时展示错误与正确做法。按场景选语言：测试用 TypeScript/JavaScript，系统调试用 Shell/Python，数据处理用 Python。
文件组织：内容约 500 词以内可自包含于 SKILL.md；需复用代码或多示例时附支持文件；参考超 100 行时单独成文件。SKILL.md 建议 500 行以内，高频加载技能总字数 200 词以内。
写作细节：用表格和列表而非流程图（仅非显而易见的决策点用流程图）；交叉引用只写技能名，不用文件路径或 @ 强制加载；内容保持长期有效，避免时间敏感信息；术语一致；脚本需显式错误处理与退出码。
验证：建议先用测试场景与评估，迭代开发，渐进披露，仅在验证通过后执行复杂操作。