Claude Code 查找技能的位置
Claude Code 从多个位置加载技能。文档中的表格列出了这些位置:
- 个人 (Personal):
~/.claude/skills/<skill-name>/SKILL.md,适用于此机器上的所有项目。 - 项目 (Project): 代码仓库中的
.claude/skills/<skill-name>/SKILL.md。 - 嵌套 (Nested): 子目录内的
.claude/skills文件夹。 - 企业 (Enterprise): 组织通过托管设置部署的技能。
- 插件 (Plugin): 已启用插件内的技能,以插件前缀命名。
- claude.ai 账户: 为你的 claude.ai 账户启用的技能。
最后一个正是本指南的主题。你在 Claude Web 应用或桌面聊天中创建的技能并不存在于你创建的文件夹中。它存在于你的账户中,Claude Code 会在可以同步的会话中下载一份副本。
要查看已加载的内容,请运行 /skills。文档说明同步的技能会列在名为 claude.ai sync 的组下。
技能何时从 claude.ai 同步
文档指出,如果你使用 Cowork 或云端会话,“或者在终端中使用 claude.ai 账户登录 Claude Code”,则适用同步。
在终端会话中,其工作原理如下:“会话开始时,Claude Code 会在后台将你账户的技能下载到 ~/.claude/skills/synced/,然后在会话运行期间检查 claude.ai 的更改。”
检查并非持续运行。当你或 Claude 正在工作时,大约每 10 分钟运行一次检查。当会话空闲时,大约每 40 分钟检查一次。在长时间空闲后再次输入时,Claude Code 会在几分钟内进行检查。
有两个细节解释了技能为何延迟出现。
同步不会阻塞启动。 文档称:“同步绝不会延迟启动,因为 Claude 仅在调用该技能时才会等待其下载。”你刚刚在 claude.ai 上添加的技能可能需要一个检查周期才能到达。
简短的非交互式运行可能会错过新技能。 快速运行可能会在新增技能下载完成前结束,而稍后的会话会获取它。文档描述了一个设置,可以让非交互式运行等待技能列表加载完毕。
哪些技能会同步取决于你的 claude.ai 设置。Anthropic 的一些自带技能(如 pdf 和 xlsx)始终同步。对于其余技能,必须在 claude.ai 的技能设置中开启。
不进行同步的会话
当终端中缺失 claude.ai 技能时,这是首先要检查的内容。文档列出了 Claude Code 不进行同步的会话:
- 未使用
/login登录的会话,例如使用 API key 进行身份验证的会话,或者由身份验证令牌变量或 API key 辅助脚本提供凭据的会话。 - 不获取功能标志 (feature flags) 的会话,例如在 Amazon Bedrock 上的会话,或关闭了非必要流量的会话。
- 裸模式 (Bare mode) 和安全模式 (safe mode)。
- 托管设置将技能锁定到插件源的会话,或者设置源列表排除了用户设置的会话。
如果你在会话中途登录,还有一种情况:“如果你在会话期间通过 /login 登录,请重启 Claude Code 以开始同步。”
当会话无法同步时,之前同步的技能不会丢失。文档称:“早期会话同步的技能会保留在磁盘上。”即使没有连接到 claude.ai,Claude Code 也会在随后登录同一账户的会话中加载它们。
在 claude.ai 端,技能还取决于账户设置。Anthropic 的帮助中心表示,技能需要启用代码执行功能,而在企业版方案中,所有者必须为组织启用技能。
为什么同名的本地技能会胜出
每个同步的技能都有两个名称。文档解释道:“你可以通过短名称 /<name> 或全名 /anthropic-skills:<name> 调用同步技能。”
当其他内容已经使用了该短名称时,该内容会胜出。文档举了一个例子:“如果有一个本地 deploy 技能和一个同步的 deploy,/deploy 将运行本地技能,而 /anthropic-skills:deploy 将运行同步技能。”
其他命令几乎可以是任何东西:内置命令、捆绑技能、个人或项目技能、.claude/commands/ 中的文件、插件技能或 MCP 提示词。比较时还会忽略字母大小写和某些空格差异,因此名为 Commit 的同步技能和名为 commit 的本地技能会被视为同名。
这就是为什么技能看起来消失了,但实际上它以全名存在的原因。运行 /skills。文档提到,列表下方的注释会解释每个失去短名称的同步技能,如果你的 ~/.claude/ 中的个人技能或命令文件占用了该名称,注释会说明需要重命名或删除什么来释放它。
为什么同步文件夹中的编辑会被覆盖
同步文件夹是下载目的地,而不是编辑的地方。文档明确指出:“如果你或 Claude 编辑了 ~/.claude/skills/synced/ 下的文件,更改不会保存到你的 claude.ai 账户,且随后的同步可能会覆盖或删除它。”
其指令同样清晰:“要更改同步技能,请在 claude.ai 上更新它;下次同步将下载新版本。”
同样的逻辑也适用于删除。如果你在 claude.ai 上仍启用该技能的情况下手动删除了同步技能的文件夹,下次同步会再次下载它。要移除它,请在 claude.ai 上将其关闭。
如果你宁愿在本地处理副本,请将其放在个人技能文件夹中,并使用不同的文件夹名称。不要将文件夹命名为 synced。Claude Code 保留了该名称,并会跳过你在那里编写的技能。
同步技能在终端运行时会有什么变化
同步技能虽然可以加载,但其行为可能与 claude.ai 版本不同。文档描述了 Claude Code 在终端或 VS Code 会话中如何处理同步技能的主体:它不会运行注入 shell 输出的行,不会附加使用 @ 引用的文件,也不会填充占位符(如项目目录或会话 ID)。这些内容将以纯文本形式传给 Claude。
在云端会话中,主体行为类似于本地技能,因为会话在隔离的容器中运行。在桌面的 Cowork 会话中,shell 行会被占位符替换。
如果技能依赖于这些特性,它可能在一个地方工作正常,而在另一个地方看起来像是坏了。
仅存在于你机器上的技能
同步是单向运行的。你电脑上 ~/.claude/skills/ 中的技能不会传输到 claude.ai。
这对 Cowork 和云端会话很重要。文档称它们“不会读取你机器上的 ~/.claude/skills/”。它们会加载为你 claude.ai 账户启用的技能。
结果可能看起来像是反向的技能缺失。文档指出,如果一个技能仅存在于你的个人文件夹中,当云端计划任务调用它时,Claude Code 会报告未找到,因为每次运行都是作为一个全新的云端会话开始的。要使个人技能在那里可用,请在你的 claude.ai 账户上启用它。对于项目线程之外的云端会话,你也可以将其提交到代码仓库的 .claude/skills/ 中。
桌面计划任务则不同。它们在你的机器上运行,因此会加载 ~/.claude/skills/。
加载较晚或无法触发的技能
还有一些其他原因会导致技能看起来缺失,即使其文件已就绪。
嵌套技能按需加载。 位于你启动 Claude Code 目录之下的 .claude/skills 文件夹中的技能不会在启动时加载。文档称它们在“Claude 第一次读取或编辑该子目录中的文件时”加载。对该子目录运行 /add-dir 可以更早地加载它们。
新技能可能需要重新加载。 Claude Code 会监视技能文件夹的更改。如果新技能没有出现,文档建议运行 /reload-skills。
损坏的 frontmatter 会隐藏描述。 如果 SKILL.md 顶部的 YAML 无法解析,技能仍会加载,但未设置任何字段。你仍然可以输入它的名称,但 Claude 无法将你的请求与其描述匹配。使用 --debug 运行 Claude Code 会显示错误,claude plugin validate 可以检查技能文件夹。
技能过多可能会丢失描述。 Claude Code 会将技能名称和描述列表加载到上下文中。当技能很多时,它会丢弃一些描述以符合预算,这会移除 Claude 匹配时使用的关键词。运行 /doctor 查看列表的消耗,或将低优先级技能设置为仅按名称列出。
某些名称会被拒绝。 名为 anthropic-skills 的技能文件夹,或包含零宽空格、尖括号等字符的文件夹名称将无法加载。
消失的技能
如果你在 ~/.claude/skills/ 中创建的技能文件夹不见了,文档指向了一个地方:“查看 ~/.claude/skills/.trash/。”
有几种情况会将技能移至此处。使用 syncClaudeAiSkills 设置关闭同步会将同步的技能移至垃圾邮件文件夹。如果你的组织在 claude.ai 上关闭了 Skills,Claude Code 会移除下载的技能,文档称它们会移至同一个文件夹。在版本 2.1.280 之前,技能文件夹中名为 manifest.json 的文件也可能导致技能被移至此处。
你可以在保留期清理删除垃圾条目之前,通过将文件夹移回原位来恢复技能。
在我们的 Claude 插件与技能 指南中,我们介绍了在“自定义”菜单变为“插件”后,技能现在出现在 Claude 应用中的位置。
人们首先尝试的操作
在会话中途登录。 重启 Claude Code 以开始同步。
使用 API key 并期望同步。 同步需要通过 /login 登录。
输入短名称。 本地命令可能占用了它。尝试使用完整的 anthropic-skills: 名称。
编辑同步副本。 改为在 claude.ai 上更改技能。
期望 Cowork 能看到本地技能。 它加载的是你的 claude.ai 技能。
解决方法:为每个技能保持单一来源
第 1 步:运行 /skills
检查哪些技能已加载,哪些是从 claude.ai 同步的。
第 2 步:检查登录方式
如果你想要同步技能,请使用 /login 进行 claude.ai 登录。
第 3 步:解决名称冲突
重命名本地技能,或使用同步技能的全名。
第 4 步:记录每个技能的来源位置
注明哪些技能在 claude.ai 上维护,哪些在本地文件夹中维护。
在 MemoryLake 中设置
技能单向同步,在某些会话中加载而在另一些会话中不加载,并且可能以名称相似的多个副本存在。了解哪个副本是真实的,以及为什么要这样编写技能,是技能文件本身无法保存的上下文。
MemoryLake 是此类工作上下文(如约定、工作流决策以及技能背后的原因)的记忆层,保存在你维护的一个地方,并可供你连接的助手(如 ChatGPT、Claude Code 和 Codex)使用。
你用自己的语言亲自编写条目。不会从你的 claude.ai 技能、你的 ~/.claude/skills 文件夹、你的同步技能、你的设置文件或任何供应商的存储中读取、写入或删除任何内容。技能同步将按照 Anthropic 描述的方式运行。
第 1 步:创建 API key
登录并从控制面板生成密钥。像处理其他凭据一样,将其存储在代码仓库之外。

第 2 步:上传你的第一批记忆
从你在解决方法第 4 步中写下的内容开始:每个技能在哪里维护以及它存在的原因。每个条目对应一个技能。

第 3 步:连接你的 AI 和代理
连接 Claude Code、Codex 以及你使用的其他助手。每个助手都可以参考关于你技能的相同笔记。

这在实践中改变了什么
第一个区别是减少了丢失的编辑。你知道该更改哪个副本。
第二个是更快的故障排除。当技能缺失时,你知道它应该来自哪里。
第三个是跨工具的一致性。技能背后的相同原因在 Claude Code 和其他地方都可用。
Claude Code 中 Claude 技能的最佳实践
在 claude.ai 上编辑同步技能。 本地编辑会被覆盖。
避免名称冲突。 本地命令会占用短名称。
使用 /login 登录以进行同步。 API key 会话不会同步。
为 Cowork 和云端在 claude.ai 上启用技能。 它们不会读取本地文件夹。
保持 frontmatter 有效。 损坏的 YAML 会隐藏描述。
在重新构建之前检查垃圾文件夹。 移除的技能会先移到那里。
结论
Claude Code 会将为你 claude.ai 账户启用的技能同步到 ~/.claude/skills/synced/,但仅限于使用 claude.ai 账户登录并获取功能标志的会话。API key 会话、Bedrock、裸模式、安全模式和某些托管设置会停止同步,中途登录需要重启。早期同步的技能会保留在磁盘上。
同步技能会将短名称让给任何同名的其他命令,因此它可能仍以 /anthropic-skills: 存在。对同步文件夹的编辑不会上传且可能被覆盖,因此请在 claude.ai 上更改技能。Cowork 和云端会话不会读取你的本地技能文件夹,找回消失技能的首选位置是 ~/.claude/skills/.trash/。