一、Skill 核心概念与运行机制

1.1 什么是 Skill？

Skill 是一套标准化、可复用的AI技能模块，本质是包含元数据、执行规则、操作流程的目录文件，核心主文件为 SKILL.md，支持搭配脚本、配置文件实现复杂自动化能力。

简单理解：Skill = 给AI的专属操作说明书 + 可执行扩展逻辑，用于约束AI行为、固化业务流程、实现场景自动化。

1.2 Skill 两大生效范围

• 全局Skill：对当前电脑所有项目生效，所有AI会话均可调用

• 项目级Skill：仅对当前项目生效，隔离性强，适合项目专属规范

1.3 主流工具Skill目录对照表

AI工具	全局Skill目录	项目级Skill目录
Claude Code	~/.claude/skills/	项目根目录/.claude/skills/
Cursor	~/.cursor/skills/	项目根目录/.cursor/skills/
Trae	~/.trae/skills/	项目根目录/.trae/skills/

> 核心规则：AI启动时会自动扫描对应目录下的Skill并加载，无需复杂编译配置。

二、Skill 标准目录结构（官方规范）

标准Skill必须以独立文件夹存在，禁止直接散落文件，最简结构如下：

my-first-skill/          # 技能根目录（自定义英文小写，中划线分隔）
├── SKILL.md             # 【必须】核心配置+技能逻辑文件
├── config.json          # 【可选】技能配置参数
├── scripts/             # 【可选】配套脚本（py/sh/js等）
│   └── run.py
└── README.md            # 【可选】技能使用说明

关键要求：SKILL.md 是唯一必需文件，缺少该文件Skill无法被识别加载。

三、手把手编写第一个标准 Skill

我们以最常用的代码规范检查Skill为例，从零编写可直接使用的标准技能。

3.1 SKILL.md 语法规范

文件头部为YAML元数据（必须），用于定义技能基础信息；正文为Markdown格式，定义技能触发条件、执行步骤、输出规范。

元数据必填字段：

• name：技能名称（简洁易懂，64字符内）

• description：技能功能描述+触发场景（核心，AI靠此字段识别调用时机）

3.2 完整实战示例（可直接复用）

新建文件夹 code-lint-skill，新建 SKILL.md，写入以下完整内容：

---
name: 代码规范自动检查
description: 当用户要求代码优化、代码检查、规范整改、重构代码时，自动触发本技能，对项目代码进行规范化校验，输出问题清单和整改方案
---

## 技能功能
自动检查代码命名规范、注释完整性、代码冗余、格式错误、语法隐患，输出标准化检查报告和可直接落地的修改代码。

## 触发条件
1. 用户提及：代码检查、规范优化、重构代码、代码整改
2. 用户上传代码文件、粘贴代码片段需要优化
3. 生成新代码时，自动遵循本规范输出

## 执行步骤
1. 扫描当前文件/选中代码，逐行校验编码规范
2. 分类统计：命名问题、格式问题、冗余代码、逻辑隐患、注释缺失
3. 逐条输出问题位置、问题原因、优化建议
4. 给出完整修改后的代码，保证功能不变、规范达标

## 输出格式
### 代码规范检查报告
1. 检查文件：{{文件路径}}
2. 问题总数：{{数量}}
3. 详细问题清单：
- 【级别】行数：问题描述 + 整改建议
4. 优化后完整代码：
```对应代码```

## 异常处理
1. 无代码内容时，提示「请提供需要检查的代码文件或代码片段」
2. 代码无问题时，输出「代码规范校验通过，无违规项」

3.3 编写核心要点

• 描述必须明确触发场景，避免AI无法主动调用

• 执行步骤尽量具体化、步骤化，减少AI自由发挥

• 配置固定输出格式，统一返回结果样式

• 增加异常兜底，避免空执行、报错卡死

四、Skill 打包规范（发布/上传必备）

本地编写完成后，如需分享、上传平台、批量部署，需打包为 zip 压缩包（所有Skill市场、平台均支持zip格式）。

4.1 正确打包方式

✅ 正确：压缩技能根文件夹

❌ 错误：直接压缩SKILL.md文件

4.2 手动打包步骤

1. 选中 code-lint-skill 整个文件夹

2. 右键压缩为 code-lint-skill.zip

3. 确保压缩包内结构：zip包->文件夹->SKILL.md

4.3 命令行打包（Windows/Linux/Mac通用）

# 进入技能上级目录
cd 你的技能所在目录

# 打包技能文件夹
zip -r code-lint-skill.zip code-lint-skill/

五、Skill 三种安装方式（全覆盖）

Skill 支持手动本地安装、CLI命令一键安装、平台市场一键安装三种方式，适配不同使用场景。

5.1 手动安装（最通用、新手首选）

适用于本地自制Skill、第三方下载的Skill压缩包，支持全局/项目级安装。

5.1.1 全局安装（所有项目生效）

1. 打开对应AI工具的全局skill目录（参考前文对照表）

2. 将解压后的技能文件夹放入 skills 目录

3. 重启AI工具（Cursor/Claude/Trae），自动扫描加载

示例（Claude Code全局安装）：

# 创建目录（无则创建）
mkdir -p ~/.claude/skills

# 移动技能文件夹到目录
mv code-lint-skill ~/.claude/skills/

5.1.2 项目级安装（仅当前项目生效）

1. 在项目根目录创建对应工具的skill目录

2. 放入技能文件夹

3. 重启AI工具，项目内自动生效

示例（Cursor项目级安装）：

项目根目录/.cursor/skills/code-lint-skill/

5.2 CLI命令一键安装（推荐GitHub开源Skill）

社区通用工具支持从GitHub仓库一键安装开源Skill，无需手动下载解压。

# 安装语法
npx skills add 仓库作者/仓库名

# 示例：安装微软Playwright测试技能
npx skills add microsoft/playwright-cli

安装完成后自动存入全局skill目录，即时生效。

5.3 平台市场一键安装（零手动操作）

主流AI Copilot均内置Skill市场，适合新手快速安装官方/社区技能：

1. 打开AI工具内置Skill市场/插件中心

2. 搜索需要的技能名称

3. 点击「安装」，系统自动下载、解压、加载，无需手动配置

六、Skill 激活与使用方法

6.1 验证Skill是否安装成功

安装完成后，可通过工具内置能力查看已加载技能：

• Claude Code：输入命令 /skills list 查看已加载技能

• Cursor/Trae：设置-扩展/技能管理，查看已安装Skill列表

6.2 主动触发Skill使用

两种调用方式，均可精准触发：

方式1：自然语言触发（自动匹配）

直接输入预设触发词，AI自动调用对应Skill：

帮我检查当前项目代码规范，输出检查报告

方式2：精准指令触发（强制调用）

使用【代码规范自动检查】技能，检查当前文件代码

6.3 技能生效特征

Skill生效后，AI输出会严格遵循你编写的步骤和格式，不会自由发挥，输出结果标准化、规范化。

七、Skill 更新、卸载与版本管理

7.1 更新Skill

1. 进入skill安装目录，找到对应技能文件夹

2. 直接修改SKILL.md内容或配套脚本

3. 重启AI工具，修改即时生效

7.2 卸载Skill

• 手动安装：直接删除对应技能文件夹即可

• CLI安装：使用卸载命令
  npx skills remove 仓库作者/仓库名

• 市场安装：在技能管理页面点击卸载

八、常见问题排错（必看）

8.1 安装后Skill不生效

排查步骤：

1. 检查目录是否正确：必须放入对应工具的skills目录

2. 检查文件完整性：必须存在SKILL.md且YAML头部无语法错误

3. 检查层级错误：不能直接放文件，必须嵌套技能文件夹

4. 重启AI工具（核心步骤，多数不生效是未重启）

8.2 AI无法主动调用Skill

原因：description描述不清晰，无明确触发场景

解决：补充明确的触发关键词、使用场景，降低AI识别成本

8.3 技能加载报错

大概率是YAML头部语法错误，检查：

• 前后---分隔符完整

• name、description字段无语法符号错误

• 无多余空格、换行错乱

九、进阶拓展：复杂Skill开发

基础Skill仅靠SKILL.md即可运行，复杂场景可拓展能力：

1. 脚本联动：在scripts目录放置python/sh/js脚本，让AI调用本地脚本实现自动化运维、批量处理

2. 参数配置：通过config.json定义可配置参数，支持用户自定义技能规则

3. 多文件拆分：超长技能可拆分子文档，通过目录关联，避免单文件臃肿

总结

本文完整覆盖了AI Skill 编写→规范校验→打包→多方式安装→使用→更新排错全流程，核心关键点复盘：

1. SKILL.md 是核心，YAML元数据+步骤化正文是生效关键

2. 严格遵循目录结构，文件夹嵌套存放，避免加载失败

3. 全局/项目级安装按需选择，适配不同使用场景

4. 修改后必须重启AI工具，技能才能更新生效

掌握本教程后，可自定义各类专属技能：代码生成规范、接口文档生成、自动化测试、运维脚本、项目初始化等，彻底定制AI编程能力。