Claude Code Skills是Anthropic官方推出的模块化AI能力扩展系统,通过SKILL.md文件让Claude按需加载专业工作流。本文将详细介绍4种安装方法、SKILL.md文件结构、个人级与项目级作用域区别,以及常见问题排查,帮助你从零掌握Claude Code Skills的安装与使用。 Claude Code Skills是什么
Claude Code Skills是Anthropic于2025年10月推出的Agent Skills标准实现,它是一种模块化能力包——每个Skill本质上是一个包含SKILL.md文件的文件夹,里面写入特定任务的专业指令、工作流和最佳实践。Claude会根据任务需求自动识别并加载匹配的Skill,无需手动切换。
根据Anthropic官方GitHub仓库(github.com/anthropics/skills)的说明,Skills的设计理念是渐进式披露(Progressive Disclosure):会话启动时,Claude只读取每个Skill的名称和简短描述(仅几个token),当用户请求匹配某个Skill的描述时,才加载完整的SKILL.md正文内容。这意味着你可以安装数十个Skills而几乎不影响性能——大部分Skill在不需要时只占一行描述的开销。
Skills与普通提示词的核心区别:
| | |
|---|
| | |
| | |
| | YAML frontmatter + Markdown规范 |
| | |
| | |
Claude Code Skills安装前准备
在安装Skills之前,需要确认以下环境已就绪:
- Claude Code CLI已安装:终端运行
claude --version 确认安装成功,若未安装可参考官方文档 code.claude.com/docs/setup
- Git已安装:运行
git --version 确认,部分安装方式需要克隆仓库
- Node.js 18+:使用 skills CLI(npx)安装方式时需要
- 文件系统访问权限:需要能够在用户目录或项目目录下创建文件夹
Skills在Claude Code中有两种存放位置,决定了不同的生效范围:
| | |
|---|
| | 个人偏好、跨项目通用工具,如代码提交风格、个人工作流 |
| | 团队规范、项目专属工作流,可提交到Git供团队共享 |
如果同名Skill同时存在于两个位置,项目级优先于个人级。项目级Skills提交到Git仓库后,团队成员克隆仓库即可自动获得,无需额外安装。
Claude Code安装Skills的4种方法
以下是四种主流安装方式,按推荐程度从高到低排列。根据使用场景选择最适合的方式即可。
方法一:插件市场安装(推荐)
这是Anthropic官方最推荐的安装方式,通过Claude Code内置的插件系统完成,支持版本管理和自动更新。
步骤1:注册官方插件市场
在Claude Code会话中输入:
/plugin marketplace add anthropics/skills
步骤2:安装技能包
官方仓库提供两个主要技能包:
- 文档处理包(含docx、pdf、pptx、xlsx):
/plugin install document-skills@anthropic-agent-skills
- 示例技能包(含创意设计、开发工具、企业沟通等):
/plugin install example-skills@anthropic-agent-skills
也可以安装单个Skill:
/plugin install pdf@anthropic-agent-skills
步骤3:重启Claude Code
安装完成后退出并重新启动Claude Code,新Skills即可在会话中生效。
方法二:Skills CLI安装
通过 npx skills 命令行工具安装,适合批量管理和跨Agent环境使用。
安装指定Skill:
npx skills add owner/repo/skill-name --agent claude-code
例如安装前端设计Skill:
npx skills add anthropics/skills/frontend-design --agent claude-code
搜索可用Skill:
npx skills find "database"
查看已安装Skill:
npx skills list -g
从项目根目录运行命令会安装到项目级(.claude/skills/),从其他位置运行则安装到个人级(~/.claude/skills/)。
方法三:自然语言安装(最简单)
直接用自然语言告诉Claude Code你要安装哪个Skill,它会自动完成下载和配置。
在Claude Code会话中输入:
帮我安装skill,项目地址是:https://github.com/anthropics/skills/blob/main/skills/pdf
Claude会自动执行以下操作:下载Skill文件、放到 ~/.claude/skills/ 目录、确认安装成功。这种方式适合不熟悉命令行操作的用户。
方法四:手动安装(最灵活)
适合从GitHub下载或自定义Skill的安装方式。
步骤1:克隆仓库或下载Skill文件夹
git clone https://github.com/anthropics/skills.git ~/anthropic-skills
步骤2:复制Skill到对应目录
个人级安装(所有项目可用):
cp -r ~/anthropic-skills/skills/pdf ~/.claude/skills/
项目级安装(仅当前项目可用):
cp -r ~/anthropic-skills/skills/pdf .claude/skills/
步骤3:重启Claude Code
手动安装后需要重启Claude Code,使其扫描并加载新的Skill目录。如果之前不存在 .claude/skills/ 顶级目录,首次创建时必须重启才能被识别。
SKILL.md文件结构与编写
了解SKILL.md结构有助于自定义Skill和排查安装问题。一个标准的Skill文件夹结构如下:
my-skill/
├── SKILL.md (必需 - 核心指令和元数据)
├── scripts/ (可选 - 可执行脚本)
├── references/ (可选 - 参考文档)
└── assets/ (可选 - 模板、示例文件)
SKILL.md文件由两部分组成:YAML frontmatter和Markdown正文。
YAML frontmatter(必填字段):
- name:Skill的唯一标识符,只能用小写字母、数字和连字符(如
my-skill-name)
- description:Skill功能描述,这是最重要的字段——Claude仅通过description判断是否加载某个Skill,描述模糊的Skill等同于不存在
可选字段:
- allowed-tools:限制Skill可使用的工具列表
- disable-model-invocation: true:禁止自动触发,仅允许手动
/skill-name 调用
- context: fork:在独立子Agent中运行,隔离上下文
最简SKILL.md示例:
---
name: my-skill-name
description: A clear description of what this skill does and when to use it
---
# My Skill Name
[这里写入Claude需要遵循的指令]
编写时有几个关键规则:文件夹名必须是kebab-case(如 my-skill,不能用 MySkill 或 my_skill);文件名必须精确为 SKILL.md(大小写敏感),skill.md、Skill.md 都会被静默忽略;description应在前250个字符内说明核心用例,因为Skill数量多时描述会被截断。
安装后如何验证和使用Skills
安装完成后,通过以下方式验证和使用:
验证Skill已加载:
- 在Claude Code会话中输入
/,查看自动补全列表中是否出现已安装的Skill
- 输入"What skills are available?"让Claude列出所有已加载的Skill
- 运行
ls ~/.claude/skills/ 查看目录结构是否正确
使用Skill的两种方式:
- 自动触发:正常描述任务,Claude根据description自动匹配并加载Skill。例如安装了pdf Skill后,直接说"分析这个PDF文件"即可自动触发
- 手动调用:输入
/skill-name 显式调用指定Skill,适合需要精确控制的场景
Skills支持实时变更检测:编辑、添加或删除 ~/.claude/skills/ 或项目 .claude/skills/ 中的文件会立即在当前会话生效,无需重启。唯一的例外是首次创建顶级 skills/ 目录时需要重启Claude Code。
Claude Code安装Skills的注意事项
- 文件夹层级不要嵌套过深:SKILL.md必须直接位于Skill文件夹内,不能多套一层目录。常见的解压错误就是压缩包内多了一层包装文件夹,导致SKILL.md无法被发现
- description字段决定Skill能否被发现:Claude仅通过description判断是否加载Skill,描述过于笼统或缺少关键词会导致Skill永远不会触发。应在description前250字符内写入触发场景和核心功能
- Skill触发不灵敏时优先优化description:如果Claude没有在你期望的场景自动使用某个Skill,说明description没有覆盖到你使用的表述方式。应该把团队实际使用的触发词写入description
- Skill触发过于频繁时添加限制:如果某个Skill(如部署类)不该自动触发,在frontmatter中添加
disable-model-invocation: true,限制为仅手动 /skill-name 调用
- 个人偏好不要提交到项目级:项目级Skills会通过Git共享给团队,个人偏好(如模型选择、API密钥)应放在
~/.claude/CLAUDE.md 中,不要提交到项目仓库
- Skill内容加载后会在会话中持续占用上下文:一旦Skill被触发加载,其完整SKILL.md内容会作为消息留在会话中直到结束。自动压缩后仅保留每个已调用Skill的前5000 token,共享25000 token的总预算
- 跨平台兼容性:SKILL.md格式是开放标准,同一份Skill文件也可在Cursor、Codex CLI、Gemini CLI、Windsurf等工具中使用,只需调整目标安装路径
以上信息综合自 Anthropic 官方 GitHub 仓库(github.com/anthropics/skills)及 Claude Code 官方文档,Skills 功能与安装方式可能随版本迭代而变化,具体以官方文档最新公布为准。