AI 编码助手装了一大堆技能，但大多数都不贴自己团队的实际流程。其实自己写一个技能只需要 10 分钟。

技能到底是什么？

在 SolonCode 里，技能就是一个包含 SKILL.md 的目录。AI 读取这个文件后，就知道怎么按你的规矩干活。

跟普通提示词的区别：

	普通对话	技能
复用性	每次手打	一次编写，到处用
上下文占用	每轮都塞进提示	只有用时才加载
版本管理	无	Git 管理
团队共享	聊天记录复制	技能池统一挂载

随便举几个例子：代码规范检查、API 文档生成、安全审查、发布检查流程……都可以做成技能。

第一步：目录结构

my-skill/
├── SKILL.md          # 核心文件（必选）
├── templates/        # 模板文件（可选）
├── scripts/          # 脚本文件（可选）
└── examples/         # 示例文件（可选）

SolonCode 只认一件事：目录下有没有 SKILL.md。有就是技能，没有就不是。

第二步：写 SKILL.md

顶部是 YAML 元数据：

---
name: "xxx-skill"
description: "一句话描述这个技能能干什么"
---

name 是技能的唯一标识，description 是 AI 判断"该不该用这个技能"的依据。所以 description 要写清楚：

• 能干什么
• 不能干什么
• 什么场景下用

正文建议结构：

## 基本规则
- 规则一
- 规则二

## 执行流程
1. 第一步做什么
2. 第二步做什么
3. 第三步做什么

## 约束条件
- 不做什么
- 必须做什么

实战：写一个 API 文档生成技能

创建目录

mkdir -p ~/.soloncode/skills/api-doc-generator

编写 SKILL.md

---
name: "api-doc-generator"
description: "为 Solon 项目生成 RESTful API 文档。识别 @Controller、@Mapping 等注解，输出 Markdown 格式的接口文档。"
---

## 基本规则
- 只扫描 src/main/java 下的 Java 文件
- 只识别 @Controller 和 @Mapping 注解的类和方法
- 输出格式为 Markdown 表格

## 执行流程
1. 用 glob 找到所有 `**/*.java` 文件
2. 用 grep 搜索 @Controller 定位控制层
3. 逐个读取，提取 @Mapping 路径和 HTTP 方法
4. 输出表格

## 输出示例
| 方法  | 路径           | 说明         |
|-------|---------------|--------------|
| GET   | /user/{id}    | 获取用户详情   |
| POST  | /user         | 创建新用户     |

## 约束
- 不修改项目代码
- 不扫描 test 目录

验证

启动 SolonCode，输入：

请使用 api-doc-generator 技能，为我当前项目的所有 Controller 生成 API 文档。

AI 会读 SKILL.md，按流程扫描代码并输出文档。

三个关键机制

1. 挂载位置

位置	适合场景
~/.soloncode/skills/	共享复用
.soloncode/skills/	项目专用
自定义挂载池	公司内部统一技能库

2. 懒加载

SolonCode 先只读 name 和 description，只有 AI 觉得该用时才加载完整 SKILL.md。技能再多也不挤爆上下文。

3. 技能嵌套

SKILL.md 写不下时，拆分到 references/ 子目录：

my-skill/
├── SKILL.md
├── references/
│   ├── quick_start.md
│   └── api_design.md

几个实战技巧

技巧一：给出具体 grep 命令

## 审查清单
### SQL 注入风险
用 grep 搜索：
grep -n -E "SELECT.*\+" **/*.java

命令越具体，AI 输出越稳定。

技巧二：说明风险等级

脚本类的技能，标注好风险等级：

## 约束
- 高风险脚本执行前需用户确认
- 不要修改代码，只输出报告

技巧三：给 AI 留示例

在 examples/ 目录放输入输出示例，AI 输出格式会更稳定。

排错快速检查

问题	检查
技能没被发现	目录有没有 SKILL.md？有没有执行 skillrefresh？
技能太多	拆分到项目级 .soloncode/skills/
同名冲突	工作区级 > 用户级；或用 @挂载名/技能名 精确定位
描述不匹配	description 要写清楚"什么场景该用"

下一步

• 逛逛技能市场：SkillHub（skillhub.cn）和 Clawhub（clawhub.ai）
• 搜索 GitHub 上的 awesome-claude-skills，有大量技能可参考
• 把团队常用规范做成技能，放进 Git 仓库统一管理