根据官方 Claude Code 技能文档，技能是一个包含 SKILL.md 文件的文件夹，其中包括 YAML 前置信息和 Markdown 说明。Claude 启动时加载名称和描述，只在需要技能时才拉取完整内容。这种渐进式披露设计保持上下文精简。你在这里得到的是：一个从零开始编写的原创内链审计技能，包括触发测试用例、结果评分标准和重复使用的打包步骤。
一个可用的 SKILL.md 示例
让我们从完成的制成品开始，这样你可以看到我们的目标。下面是一个审计网站内链的技能。复制它，安装它，然后阅读文章的其余部分以理解每个决策。
description: >
Audits internal links in a project's HTML or Markdown output.
Use when the user asks to check broken links, find dead anchors,
audit site links, or review internal navigation before a deploy.
``
## Internal Link Audit
``
Run a link audit against the built output or source files.
``
### Steps
``
1. Collect all internal links (href or markdown link targets starting
with / or a relative path).
2. Resolve each link against the project root.
3. Check whether the resolved target file or anchor exists on disk.
4. Report broken links grouped by source file. For each broken link,
show: source file, link text, href, and the reason it fails
(missing file, missing anchor, or redirect loop if detectable).
5. List passing links only in a summary count, not individually.
6. If zero broken links are found, say so explicitly.
``
### Output format
``
- Broken links: grouped table per source file.
- Summary line: "X of Y internal links are broken."
- If scripts/ contains check-links.sh, run it first and append
Claude's analysis below the script output.
这是一个真实、可用的技能。将其保存到 ~/.claude/skills/internal-link-audit/SKILL.md，它会立即在每个项目中可用。
有一点需要注意：官方文档确认自定义命令已并入技能。两者都可以用 /name 调用。所以 /internal-link-audit 可作为直接命令，Claude 也会从自然语言请求中自动匹配它。这些不是两个独立的机制。
选择一个狭隘的任务并编写描述
描述字段不是文档。它是触发器。其中的每个词要么帮助 Claude 在正确的时刻匹配技能，要么增加噪音，使匹配变得更糟。
Hidekazu Konishi 的指南直言不讳：模糊的描述是技能永远不会触发的最常见原因。用第三人称编写。以主要用例开头。然后列出用户实际输入的短语，因为匹配发生在这些短语上，而不是你对技能的内部想法。
不好的描述：帮助 web 项目中的链接和相关内容。
更好的：审计项目 HTML 或 Markdown 输出中的内链。
Use when the user asks to check broken links, find dead anchors,
audit site links, or review internal navigation before a deploy.
注意第二个版本前置了操作（"审计内链"），命名了文件类型，然后在"使用情况"子句中提供了四个具体的触发短语。每个短语都是开发者实际会输入的。
狭隘更好
抵制构建"通用链接检查器"的冲动。做好一件事的技能会可靠地触发。承诺检查链接、验证重定向和报告页面速度的技能会不可靠地触发，输出也不一致。选择最小的有用切片。你总是可以为其余部分编写第二个技能。
对于内链审计，缩小范围的决策是：
- 仅限内链，不包括外部链接（不同的工具，不同的故障模式）
- 检查文件存在和锚点存在，不检查 HTTP 状态
- 按源文件分组报告损坏的链接，而不是平面列表
每个缩小范围的决策都让触发短语更具体，也让输出格式更容易验证。
控制技能调用和支持文件
当Claude匹配描述时，技能会自动加载，同时也支持显式的/skill-name命令。根据官方文档，Claude在启动时扫描四个位置：个人（~/.claude/skills/）、项目（.claude/skills/）、插件和企业。企业设置覆盖个人设置，个人设置覆盖项目设置。当你向本地化可能发生冲突的团队发布技能时，了解这个层级很重要。
对于调用，你有两条路径：
- 自动：Claude读取你的请求，与已加载的描述匹配，触发该技能。不需要斜杠命令。
- 显式：你输入/internal-link-audit。Claude加载完整的SKILL.md正文并运行它。适合测试和自动匹配不触发的情况。
两条路径执行相同的指令。区别不是"手动对自动"，而是Claude用哪个信号来判断该技能是否适用。
支持文件
一个技能文件夹可以包含不仅仅是SKILL.md：
scripts/：技能正文引用的可执行代码（Bash、Python）。internal-link-audit技能如果存在会引用scripts/check-links.sh，这样你可以稍后不修改指令就换入真正的链接检查脚本。references/：Claude按需加载的详细文档，不是每次调用都加载。适合那些你不想在主指令中出现的边界情况规则。assets/：模板和输出格式。
对于第一个技能，单独的SKILL.md就够了。当你有实际想运行的命令时添加scripts/。当你的指令变得很长、因为你在内联处理十多个边界情况时添加references/。
如果你已经在管理项目范围的CLAUDE.md，技能与之并行，不是替代品。面向代理机构的Claude.md文章涵盖了如何单独结构化该文件；技能处理不属于全局指令文件的狭窄、可复用的任务。
运行正面和负面触发测试
编写很容易。测试是大多数人停下来太早的地方。根据Towards Data Science指南关于生产级Claude Code技能，这里的"测试"意味着用真实提示攻击技能并检查其行为是否正确，而不是软件意义上的单元测试。
你需要两种测试用例：正面（应该触发）和负面（不应该触发）。
internal-link-audit的正面触发用例
这些提示都应该自动调用该技能：
- "在我部署前检查坏掉的内部链接。"
- "找出我markdown输出中的死链接。"
- "审计构建文件夹中的网站链接。"
- "网站上是否有断链？"
- "检查项目中的内部导航。"
负面触发情况
这些提示不应触发该技能。如果触发了，说明存在过度触发问题。
- "检查README中的外部链接是否仍然有效。"（外部链接，属于不同技能范围）
- "验证我的sitemap.xml。"（完全不同的任务）
- "查找页面上的破损图像。"（图像，不是链接）
- "检查我的API端点的HTTP状态。"（HTTP，不是文件系统）
结果标准
/internal-link-audit的良好输出必须满足以下所有条件：
| 标准 | 通过条件 |
|---|---|
| 按源文件分组破损链接 | 是的，每个文件一个表格 |
| 显示源文件、链接文本、href和失败原因 | 每个断链都包含全部四个字段 |
| 正常链接仅显示在摘要计数中 | 没有长列表的工作链接 |
| 当检查无问题时显示明确的"零个断链"消息 | 在适用时显示 |
| 如果check-links.sh存在，脚本输出在前面 | 脚本先运行，分析追加在下方 |
| 不检查外部链接 | 外部链接不出现在报告中 |
先运行正面情况。如果技能在所有五个情况中都触发，则转到负面情况。如果在任何负面情况中触发，说明描述有问题。
修复过度触发、漏触发和输出不完整
三种故障模式，三种解决方案。它们是独立的问题，每种都有不同的解决方法。
过度触发意味着技能在不应该时触发。通常由过于宽泛的描述导致。解决方法是在 Use when 条款中添加排除语言：
Do NOT use for external link checks, HTTP status checks,
sitemap validation, or image audits.
添加明确的排除条件可以缩小匹配范围，而不会移除正向触发器。
漏触发意味着技能存在但从不自动触发。描述与真实用户语言不匹配。解决方法是添加更多反映人们实际提问方式的触发短语，而不是你会正式描述的方式。"有死链接吗？"不同于"审计内部导航"，两者都应该触发同一个技能。
Towards Data Science 指南描述了一个优化循环：分割测试用例、测量触发率、生成改进的描述、选择最佳分数。你可以用几个提示手动完成，或者使用 Anthropic 的技能创建工具来半自动化。
输出不完整意味着技能触发了但输出不一致或不完整。这是一个体问题，不是描述问题。查看你定义的评分标准。哪些条件失败了？添加更具体的格式化指令。如果输出缺少失败原因列，在指令中明确说明。如果它列出了所有通过的链接（你不想要的），添加"不要单独列出通过的链接"。
如果你正在管理一堆 Claude Code 自动化并想要了解技能适配的全局图景，Claude Code 超级能力文章涵盖了周围的工作流程。
对于处理多个客户项目的成长型团队或代理机构，专门的 Claude Code 代理机构设置页面值得一看，它说明了如何跨多项目环境组织技能。
打包技能并维护它
一旦技能通过了所有正向测试且不通过任何负向测试，就将其正确打包。
最终文件夹结构
~/.claude/skills/internal-link-audit/
├── SKILL.md
├── scripts/
│ └── check-links.sh (optional, referenced in instructions)
└── references/
└── anchor-edge-cases.md (optional, for edge-case rules)
跨项目和人员共享
~/.claude/skills/ 中的个人技能在你机器上的每个项目中都可用。对于团队分发，将技能移到共享存储库，让团队成员将其符号链接或复制到他们的个人技能文件夹，或将其提交到共享项目存储库中的 .claude/skills/ 以获得项目范围的访问权限。
技能格式是开放标准。根据 freeCodeCamp 的构建指南，相同的 SKILL.md 结构适用于 Claude Code、GitHub Copilot、Cursor 和 Gemini CLI，安装路径不同但文件格式相同。对于 Claude Code，路径是 ~/.claude/skills/。对于 Copilot，是 ~/.copilot/skills/。相同的文件，不同的主目录。
维护
技能会漂移。项目结构改变、输出格式需要更新，或触发短语不再匹配团队谈论任务的方式。像对待任何其他仓库文档一样对待 SKILL.md：对其进行版本控制，在底层工作流程改变时审查它，并在编辑描述后重新运行触发测试。
一份编号的维护检查清单：
- 任何描述更改后重新运行所有正向和负向触发测试。
- 如果输出格式要求改变，更新结果评分标准。
- 如果你在
scripts/中添加脚本，在SKILL.md正文中明确引用它，以便 Claude 知道使用它。 - 当将个人技能提升为团队技能时，审查触发短语，团队成员可能使用与你不同的语言。
- 删除不再使用的技能。过时的技能意外触发会比根本没有技能更糟糕。
FAQ
SKILL.md 文件究竟需要放在哪里?
对于在所有项目中可用的个人技能，路径是 ~/.claude/skills/your-skill-name/SKILL.md。目录名称会成为斜杠命令。对于项目范围的技能（仅在一个代码库中可用），在项目根目录内使用 .claude/skills/your-skill-name/SKILL.md。企业级技能遵循由你所在组织的 Claude Code 管理员管理的单独路径。
Claude 启动时每次都加载技能的完整内容吗?
不会。根据官方文档，Claude 在启动时扫描技能目录，但只将名称和描述加载到上下文中。完整的 SKILL.md 正文仅在技能与请求匹配时才会加载。这就是渐进式披露设计：描述保留在上下文中，完整说明按需加载。
同一请求能触发多个技能吗?
技能是单独匹配的。如果两个技能的描述都与同一请求匹配，优先级层级适用：企业级覆盖个人级，个人级覆盖项目级。在同一层级内，你应该更仔细地区分描述，以便只有目标技能触发。重复触发通常表明两个技能有重叠的作用域，应该合并或缩小范围。
如果描述说"使用时机"但用户直接输入斜杠命令会怎样?
技能会运行。通过 /skill-name 显式调用会完全绕过自动匹配，直接加载完整正文。description 字段的"使用时机"条款仅适用于自动匹配。所以直接斜杠命令总是有效的，即使用户的措辞不会触发自动检测。
什么时候用技能而不是在 CLAUDE.md 中添加说明?
CLAUDE.md 用于始终启用的上下文：项目结构、编码规范、Claude 应该在每个会话中知道的东西。技能用于按需任务：你有时候做的事情，不是总是做，且希望输出保持一致。如果你发现自己在 CLAUDE.md 中添加多步工作流，它可能应该是一个技能。
description 字段完成了大多数人认为正文应该做的工作。使用你的团队实际使用的触发短语，保持任务狭窄，其余的就迎刃而解了。