FAQ 常见问题
按安装、加载、调用和任务执行四个阶段排查 Skill 问题。
基础概念
Skill、Rules、MCP、插件怎么区分？
| 概念 | 主要用途 | 例子 |
|---|---|---|
| Rules / 项目指令 | 规定项目约束；有些工具支持按目录或条件生效 | 代码规范、提交范围 |
| Skill | 保存某类任务的方法、参考资料和脚本 | 文档格式转换、品牌排版 |
| MCP | 用统一协议连接工具和数据 | 查询业务数据、读取外部文档 |
| CLI / API | 另一种调用工具的方式 | gh、Wrangler、HTTP API |
| 插件 | 打包分发 Skills、应用连接或其他扩展 | Codex 插件目录中的集成 |
| Sub-agent | 委派一项独立工作 | 分头查资料，再汇总证据 |
外部工具可以通过 MCP、CLI、API 或原生集成调用。Skill 不会自动增加账号权限，插件也不一定包含上述所有能力。客户端可以按需发现 MCP 工具，不能笼统判断 MCP 一定比 Skill 更耗上下文。
普通提示词什么时候够用？
一次性任务先直接描述目标、输入和输出。反复需要同样的资料、脚本或验收标准时，再考虑 Skill。先比较实际产物，不用为了“更专业”而安装。
所有工具都能通用吗？
SKILL.md 的核心格式可以共享，但工具扩展、调用语法和执行环境会不同。跨工具搬运后，需要检查依赖、路径、权限和实际输出。
安装了但找不到
按顺序检查：
- 当前项目目录是否正确？全局安装和项目安装有没有混淆？
- 目标目录里是否存在
技能目录/SKILL.md？ - 文件名是否准确？frontmatter 是否包含有效的
name和description？ - 客户端是否支持这个目录和当前格式？
- 如果用安装器，是否选中了正在使用的 Agent？
用 npx skills list 和 npx skills list -g 辅助排查。目录表见 快速入门。
找到了但没有调用
先明确点名，再判断自动触发是否合适：
| 工具 | 显式调用入口 |
|---|---|
| Claude Code / Cursor | /技能名 |
| Codex | $技能名；CLI/IDE 可通过 /skills 选择 |
| Cascade | @技能名 |
自然语言也可以明确说“使用某某 Skill”。如果描述只写“帮助用户”，自动匹配会不清楚；写明任务、输入或限制条件。
Codex 的可选 agents/openai.yaml 可以设置 allow_implicit_invocation: false，禁用隐式调用后仍可显式使用。这不是安装失败。字段解释见 文件结构。
修改后需要重启吗？
- Claude Code 支持发现技能目录内的修改；首次创建技能目录时可能需要
/reload-skills。 - Codex 通常会检测技能变化；没有发现时可以重启客户端再检查。
- 其他工具按当前版本文档处理，不要一概判断必须重启或一定即时生效。
调用了但执行失败
| 现象 | 先查什么 |
|---|---|
| 找不到命令、包或字体 | Skill 的运行依赖是否已安装 |
| 找不到脚本或素材 | 路径是否相对技能目录解析 |
| API / 登录失败 | 账号、认证、服务权限和网络 |
| 输出格式不对 | 是否给了样例、输出要求和完整输入 |
| 部分步骤跳过 | 流程是否过长、前置条件是否满足 |
| 文件生成了但打不开 | 文件格式、内容和实际渲染结果 |
安装成功仅代表文件已放好。生成文件、保存草稿、上传成功、公开发布也需要分别确认；以当前任务的产物为准。
与项目规则冲突怎么办？
先保留项目约束，指出冲突，再修改 Skill 或项目规则。Skill 里写一句“覆盖其他规则”不会自动获得更高优先级，也不能绕过用户授权。
相同规则只维护在一个地方，Skill 引用项目约束，避免复制后各自漂移。
全局还是项目安装？
跨项目高频的能力可以放全局；业务知识、框架约束和发布流程放项目。数量不代表能力，闲置但有价值的技能可以保留来源记录，需要时再安装。
依然不稳定怎么办？
缩小到一个输入、一个目标文件、一个可验证结果。用相同样例比较直接提示词和 Skill，再修描述、脚本或流程。维护方法见 创建 Skill。
工具行为参考：Claude Code、Codex Skills、Cursor、Cascade Skills。