SolonCode 技能开发实战：从零写一个 Agent Skill

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 要写清楚什么场景该用下一步逛逛技能市场SkillHubskillhub.cn和 Clawhubclawhub.ai搜索 GitHub 上的awesome-claude-skills有大量技能可参考把团队常用规范做成技能放进 Git 仓库统一管理