简而言之：技能是一个 markdown 文件，用于教会智能体某种习惯——将它放入 ~/.claude/skills/<name>/SKILL.md（全局生效）或 .claude/skills/<name>/SKILL.md（仅在当前项目中生效）。智能体会根据文件中的描述字段自动加载。
技能是让智能体养成习惯的最小单元。一个 markdown 文件，两个字段，几行说明文字。放入正确的目录后，智能体会在下一轮对话中自动加载，并从此改变行为。本教程介绍技能的本质、存放位置，以及安装他人编写的技能的两种方式。
在自己动手编写之前，先来安装一个别人写的技能。这才是正确的入门方式——就像你会先 brew install 一个工具，然后再去研究它的源码一样。技能是一个小而专注的智能体行为单元："当遇到 X 情况时，按 Y 方式处理。"团队里有人把他们反复解释却无人记住的规范写成技能，交给你，你把它放进一个目录，智能体就懂了。
整个机制比听起来简单得多。智能体在每一轮对话中都会读取所有可用技能的一行描述，如果描述与当前情境匹配，就会加载该技能的正文——通常是几段普通文字——并按其中的指示执行。基本用法不需要构建步骤、运行时环境或插件管理器。
本教程讲的是使用侧。如果你想从头编写自己的技能，完成本教程后请前往 编写自定义技能。
SKILL.md 文件的实际内容打开别人分享给你的任意技能文件，大致长这样：
---
name: test-before-commit
description: Use when the user says "commit", "push", or "ship". Always run `npm test` first and report the result before staging anything.
---
Before any commit, run the project's test suite:
1. Check for a `package.json` and run `npm test` (or the equivalent for the stack).
2. If tests pass, proceed with staging and the commit.
3. If tests fail, stop and surface the failure — do not commit.
就这些。顶部的 YAML 前置元数据有两个必填字段：name（用于手动调用技能）和 description（供智能体判断何时加载）。下方的 markdown 内容是实际指令——技能触发后智能体应当做什么。
描述字段是核心所在。智能体每一轮都会读取所有技能的描述，然后判断当前情境是否匹配。越具体的描述效果越好，比如"当用户说 commit、push 或 ship 时"；而"帮助测试"这样模糊的描述则往往被忽略。
CLAUDE.md 始终加载——用于存放项目级别的固定规范。技能只在描述匹配时加载——用于特定情境下的习惯行为。MCP 服务器用于添加新能力（与 API 对话、查询数据库等）——当智能体需要目前无法完成的操作时使用。
LingCode 不止是 Mac 应用——还有 lingcode CLI 和 Claude 提供商聊天面板，它们使用不同（更旧）的加载器。两个加载器会在不同的目录查找技能，你需要知道自己的目标是哪个。
| 如果你使用… | 技能存放在… |
|---|---|
| LingCode Mac 应用——斜杠命令弹窗和技能草稿审阅面板 | ~/.cursor/skills/<name>/SKILL.md（全局）.cursor/skills/<name>/SKILL.md（每个项目单独，与代码并存） |
lingcode CLI 或任意聊天中的 Claude 提供商 |
~/.claude/skills/<name>/SKILL.md（全局）.claude/skills/<name>/SKILL.md（每个项目单独） |
如果两个位置都定义了同名技能，项目级别的会覆盖全局的——适用于"此仓库覆盖我的个人习惯"的场景。
~/.cursor/skills/ 中的技能对 CLI 不可见；~/.claude/skills/ 中的技能对 Mac 应用的斜杠菜单不可见。如果你想在两处都能使用，需要在两个目录中各放一份文件。这是"刚安装的技能看起来没有任何作用"最常见的原因。
最简单的安装方式：别人给你一个 SKILL.md 文件（或粘贴其内容）。你想让它在 Mac 应用的斜杠菜单中可用。
# 1. Make the folder. The folder name becomes the skill name.
mkdir -p ~/.cursor/skills/test-before-commit
# 2. Save the SKILL.md inside it.
mv ~/Downloads/SKILL.md ~/.cursor/skills/test-before-commit/
# 3. Confirm the layout.
ls ~/.cursor/skills/test-before-commit/
# → SKILL.md若要安装为项目级别——例如某个技能只与这个仓库的规范相关——将 ~/.cursor/skills/ 替换为项目根目录下的 .cursor/skills/。将该目录提交到 git，团队成员下次拉取后即可使用。
确认技能已加载：
/，在弹出列表中查找你的技能名称。出现即表示智能体也能看到它。/skills——所有已加载的技能都会列出，附带各自的描述。如果别人分享的是插件而非单个文件，那本质上就是一个包含 .claude-plugin/plugin.json 清单文件以及一个或多个技能的目录。安装一次，插件内的所有技能便在加载该插件的地方全部可用。
# Local folder (someone gave you a directory):
lingcode plugin install ./team-skills
# Git URL (a published plugin):
lingcode plugin install https://github.com/your-team/lingcode-plugin-ship-checklist插件内的技能会以 <plugin>:<skill> 的命名空间区分，因此两个插件各自包含名为 tdd 的技能时不会冲突。调用带命名空间的技能时使用 /team-skills:tdd。
插件还可以打包 hooks、斜杠命令、智能体和 MCP 服务器配置——超出技能范畴的内容另有说明。完整插件模型请参阅 安装与配置插件。
如果智能体没有加载你刚安装的技能，原因几乎总是以下三种之一：
name: 和 description:。其中任何一个缺失或为空，加载器都会静默跳过该技能——没有报错，只是不存在。重新打开文件检查一下。~/.cursor/skills/，而不是 ~/.claude/skills/。CLI 用户：反之。如果不确定自己在测试哪个界面，两个目录都放一份文件。/<skill-name> 手动调用技能。/your-skill-name 也能显式加载技能。在排查描述调优问题之前，先用这个方法确认文件可以被正常解析。