原创文章

技能名称(中文)

一、概述

本文档定义 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 个标签为宜
优先级 优先选择领域和工具标签
避免 避免过于宽泛的标签(如 utilshelper
格式 标签使用小写

八、使用方式

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/ 目录编写测试用例


十、相关资源

评论

发表评论