Agent Skill 常见问题排查

Agent Skill 设计简单：带指令的 Markdown 文件。但简单不代表不会出问题。本文覆盖最常见问题及修复方法。

问题：Agent 不使用 Skill

已安装 Skill，但相关请求时 Agent 忽略 Skill 自己发挥。

检查 1：目录是否正确？

Skill 必须在 Agent 的技能目录：

# Claude Code
ls ~/.claude/skills/

# OpenAI Codex CLI
ls ~/.codex/skills/

装错位置就移动；Agent 只扫描指定目录。

检查 2：SKILL.md 是否有「When to activate」？

Agent 需要知道何时启用。缺少或模糊则可能永不触发。打开 SKILL.md 确认类似：

## When to activate
The user asks for release notes, changelog, or "what changed."

缺失则补上。

检查 3：请求是否够具体？

「帮我看看项目」匹配不到任何 Skill。「生成过去两周的发布说明」可以。Skill 靠具体触发词激活，不靠泛泛请求。

问题：Skill 激活但输出不对

Agent 用了 Skill，但结果不符合预期。

修复 1：检查输出格式指令

多数问题来自模糊格式。不要写：

Output the results in a nice format.

应写：

Output format:
## New Features
- Description of change (`commit-hash`)
## Bug Fixes
- Description of fix (`commit-hash`)

精确格式才有精确结果。

修复 2：加约束

不想要的内容用否定约束：

## Important rules
- Do not include author names
- Do not include dates unless requested
- Do not fabricate information

「不要」往往比「要」更能阻止多余输出。

修复 3：提供示例

## Example

Input: git log shows "feat: add search" and "fix: login bug"

Output:
## New Features
- add search (`abc1234`)

## Bug Fixes
- login bug (`def5678`)

一个示例胜过十条抽象规则。

问题：加载 Skill 后 Agent 变慢

原因：过大的 reference 文件

references/ 下大文档会进上下文，拖慢响应。

修复：只保留必需 reference

每次调用都需要的才放本地；罕用的改成 URL 按需拉取：

## References
- Full API documentation: https://example.com/api-docs (fetch when user asks about specific endpoints)
- Quick reference card: references/quick-ref.md (always loaded)

问题：多个 Skill 冲突

两个 Skill 任务重叠，Agent 选错或同时用两个。

修复：激活条件互斥

## When to activate
The user asks for release notes or changelog.
Do NOT activate for: git commit messages, PR descriptions, deployment notes.

## When to activate
The user asks to write a commit message for staged changes.
Do NOT activate for: release notes, changelogs, or general git history.

重叠是敌人。若真重复，留一个删一个。

问题：本地可用，发布后他人不行

检查 1：路径相对 Skill 目录

# 错误（本机绝对路径）
/Users/you/.claude/skills/my-skill/scripts/run.sh

# 正确（相对路径）
scripts/run.sh

检查 2：脚本可执行

chmod +x scripts/run.sh
git add scripts/run.sh
git commit -m "fix: add execute permission to script"

检查 3：平台差异

Shell 需在 macOS 与 Linux 都测：sed、date、realpath 行为可能不同。

问题：上下文被占满

装很多 Skill 会占 token，留给实际工作的变少。

修复：只装常用的

不要一次装 50 个。日常 10–15 个以内，一周没用的可删，需要再装。

ls ~/.claude/skills/

通用排查流程

1. 先看 SKILL.md — 多数是指令问题，不是平台 bug。
2. 要具体 — 模糊指令 → 模糊输出。
3. 加示例 — 一条具体示例胜过十条规则。
4. 增量测试 — 改一处、测一次。
5. 看 Agent 推理 — 多数会显示激活了哪些 Skill 及原因；推理错了就改激活条件。

某个 Skill 仍有问题？在 SkillMap 排行榜 找替代方案，或阅读 入门指南。