一、概述
本文档定义 Skills 技能的开发规范,确保所有技能保持一致的质量和风格。
二、目录结构
skill-name/
├── SKILL.md # 技能定义文件(必需)
├── README.md # 详细使用文档(可选)
├── config/ # 配置目录
│ └── config.yaml
├── data/ # 数据存储
│ ├── raw/ # 原始数据
│ ├── processed/ # 处理后数据
│ └── cache/ # 缓存数据
├── plugins/ # 插件模块
│ ├── productivity/ # 生产力插件
│ ├── development/ # 开发工具插件
│ ├── media/ # 媒体处理插件
│ └── integration/ # 集成插件
├── references/ # 引用目录
│ └── resources/ # 资源定义
├── scripts/ # 自动化脚本
│ ├── automation/ # 批量处理脚本
│ ├── deployment/ # 部署脚本
│ └── maintenance/ # 维护脚本
├── code/ # 生成代码库
│ ├── libraries/ # 自定义库
│ ├── modules/ # 功能模块
│ └── packages/ # 可复用包
├── web/ # Web应用
│ ├── frontend/ # 前端代码
│ ├── backend/ # 后端代码
│ └── static/ # 静态资源
└── tests/ # 测试目录
├── unit-tests/ # 单元测试
└── integration-tests/ # 集成测试
三、命名规范
3.1 基本规范
| 规范 | 示例 | 说明 |
|---|---|---|
| 小写字母 | contract-analyzer |
全小写 |
| 连字符分隔 | git-commit |
多个单词用 - 连接 |
| 描述性名称 | prometheus-host-monitor |
清晰表达功能 |
| 避免特殊字符 | ❌ git_commit@v1 |
只用字母、数字、- |
3.2 正确与错误示例
| 正确 ✅ | 错误 ❌ |
|---|---|
git-commit |
gitCommit (驼峰) |
prometheus-host-monitor |
git_commit (下划线) |
3.3 SKILL命名
必须与目录名一致:
目录:skills/git-commit/
name: git-commit ✅
目录:skills/prometheus-host-monitor/
name: prometheus-host-monitor ✅
3.4 描述规范
| 规范 | 示例 |
|---|---|
| 中文,祈使句 | "智能生成 Git 提交信息" ✅ |
| 简洁明了 | "通过 Prometheus 扫描主机资源" ✅ |
| 避免"了"、"可以" | "智能生成了提交信息" ❌ |
| 不超过 50 字 | - |
四、质量标准
4.1 功能完整
- [ ] 可以独立完成预期任务
- [ ] 边界情况有处理
- [ ] 错误提示清晰友好
- [ ] 技能执行支持复用
4.2 代码质量
- [ ] 代码结构清晰,易于维护
- [ ] 有适当的错误处理
- [ ] 遵循语言最佳实践
4.3 禁止的代码风险
| 风险类型 | 说明 |
|---|---|
| 大查询 | 可能导致性能问题 |
| 内存泄漏 | 资源未正确释放 |
| 死循环 | 程序卡死 |
| 事务中使用线程 | 并发问题 |
| 硬编码URL | 维护困难 |
| SQL注入 | 安全漏洞 |
| 空指针风险 | 运行时错误 |
| 异常吞没 | 问题难排查 |
| 敏感信息泄露 | 安全风险 |
| 硬编码密钥 | 安全风险 |
| 大事务 | 性能问题 |
| 连接池泄漏 | 资源耗尽 |
4.4 文档完整
- [ ] SKILL.md 格式正确
- [ ] README.md 格式正确
- [ ] 复杂逻辑有注释说明
4.5 测试覆盖
- [ ] 核心功能有单元测试
- [ ] 测试用例覆盖主要场景
五、SKILL.md 模板
重要建议:每个技能目录下的MD文件名称建议统一为 SKILL.md,方便统一管理。
---
name: skill-name
description: "简短描述技能功能,说明何时触发。"
tags: [category1, category2]
keywords: [keyword1, keyword2]
allowed-tools: Bash, Read, Write
output_format: markdown
metadata:
author: your-name
version: '1.0.0'
---
# 技能名称(中文)
## 技能概述
详细描述技能的功能和使用场景。
## 触发条件
**关键词**:关键词1、关键词2
## 功能特性
- 功能1:描述...
- 功能2:描述...
## 使用方法
1. 步骤一
2. 步骤二
六、字段说明
| 字段 | 类型 | 必需 | 说明 |
|---|---|---|---|
name |
string | ✓ | 技能唯一标识 |
description |
string | ✓ | 功能描述 |
tags |
array | ✓ | 分类标签 |
keywords |
array | ✓ | 关键词,辅助AI思维决策 |
allowed-tools |
array | ✗ | 允许使用的工具 |
output_format |
string | ✗ | 输出格式 |
七、TAG标签分类
7.1 标签类别
| 类别 | 标签示例 | 说明 |
|---|---|---|
| 开发工具 | devops, git, workflow | - |
| 监控运维 | monitoring, devops, ops | - |
| 文档处理 | document, report, office | - |
| 项目管理 | project, management | - |
| 领域 | database, monitoring, logging, security, network | 技能所属领域 |
| 语言 | python, java, go, javascript, typescript | 涉及的编程语言 |
| 工具 | git, docker, kubernetes, redis, prometheus | 相关工具 |
| 流程 | cicd, testing, debugging, code-review, deployment | 开发流程 |
| 团队 | devops, platform, data, frontend, backend | 维护团队 |
7.2 标签使用建议
| 建议 | 说明 |
|---|---|
| 数量 | 3-5 个标签为宜 |
| 优先级 | 优先选择领域和工具标签 |
| 避免 | 避免过于宽泛的标签(如 utils、helper) |
| 格式 | 标签使用小写 |
八、使用方式
8.1 命令行方式
# 示例命令
python scripts/main.py --xxx
8.2 作为 WinCode技能使用
# 触发技能的示例话术
请帮我 xxx
九、常见问题
Q: 技能名称可以更改吗?
A: 避免频繁更改技能名称,因为其他团队可能已在使用。如必须更改,需要在 README 中说明新旧名称映射。
Q: 一个技能可以有多个 SKILL.md 吗?
A: 不可以。一个技能目录只能有一个 SKILL.md 作为入口定义。
Q: 技能可以调用其他技能吗?
A: 可以,但需注意循环依赖。建议使用 allowed-tools 明确声明的工具。
Q: 如何测试技能?
A: 两种方式:
1. 本地测试:直接在 WinCoder 中触发技能
2. 单元测试:在 tests/ 目录编写测试用例
评论
发表评论