MemoryLake
返回全部文章
Tutorial2026 年 11 月 20 日·11 分钟阅读

为什么你的 Claude Skills 没有出现在 Claude Code 中?当技能从 claude.ai 同步时,为什么同名的本地技能会胜出,以及为什么同步文件夹中的编辑会被覆盖 (2026)

你在 Claude 的 Web 应用中构建了一个用于编写团队周报的技能。它在那里运行良好。但当你在终端打开 Claude Code,输入斜杠和技能名称时,却没有任何匹配项。另一天它出现了,但名称变长了且带有前缀。当你修复了电脑上该技能文件中的拼写错误后,第二天早上发现修复的内容消失了。

这三种行为都源于同一个特性。Anthropic 的 Claude Code 文档解释说,在某些会话中,“Claude Code 会加载为你 claude.ai 账户启用的技能,无需你进行任何设置”。它还解释了限制:同步仅在特定会话中运行,它会向同名的其他命令让路,并且同步是单向的。“Claude Code 下载同步的技能,绝不会上传它们。”

本指南涵盖了 Claude Code 查找技能的位置、技能何时从 claude.ai 同步、哪些会话不进行同步、为什么同名的本地技能会胜出、为什么同步文件夹中的编辑无法持久、为什么某些技能在特定会话中加载较晚或根本不加载,以及如何找回似乎消失的技能。

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

登录并从控制面板生成密钥。像处理其他凭据一样,将其存储在代码仓库之外。

MemoryLake 控制台显示 API 密钥屏幕,在此处创建并复制新密钥以供代理使用
MemoryLake 控制台显示 API 密钥屏幕,在此处创建并复制新密钥以供代理使用

第 2 步:上传你的第一批记忆

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

MemoryLake 工作区显示已上传的首批文档,列出了每个文件变为可搜索记忆的过程
MemoryLake 工作区显示已上传的首批文档,列出了每个文件变为可搜索记忆的过程

第 3 步:连接你的 AI 和代理

连接 Claude Code、Codex 以及你使用的其他助手。每个助手都可以参考关于你技能的相同笔记。

MemoryLake 集成屏幕列出了可以连接到记忆层的 AI 客户端和代理框架
MemoryLake 集成屏幕列出了可以连接到记忆层的 AI 客户端和代理框架

这在实践中改变了什么

第一个区别是减少了丢失的编辑。你知道该更改哪个副本。

第二个是更快的故障排除。当技能缺失时,你知道它应该来自哪里。

第三个是跨工具的一致性。技能背后的相同原因在 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/。

常见问题

为什么我的 claude.ai 技能没有出现在 Claude Code 中?

会话可能未同步。同步需要使用 /login 进行 claude.ai 登录,且无法在 API key、Bedrock、裸模式或安全模式下运行。

Claude Code 将同步的技能保存在哪里?

保存在 ~/.claude/skills/synced/。

为什么我的技能只能通过 /anthropic-skills:name 运行?

另一个命令占用了短名称。/name 会运行该命令。

我可以在 Claude Code 中编辑同步的技能吗?

编辑不会保存到 claude.ai 且可能会被覆盖。请在 claude.ai 上更改技能。

Cowork 会话会加载我的本地技能吗?

不会。Cowork 和云端会话加载的是为你 claude.ai 账户启用的技能。

如何查看哪些技能已同步?

运行 /skills。同步的技能列在 claude.ai sync 下。

我的个人技能去哪了?

检查 ~/.claude/skills/.trash/ 并将文件夹移回原位以恢复它。