Skill 示例
本文档提供完整的 Skill 实现示例，可直接复用。
示例 A：发布前风险审查 Skill
用途：上线前自动判断是否可发布。
SKILL.md
markdown
# 发布前风险审查 Skill
## 概述
在代码合并到主干前，自动评估发布风险，识别阻断问题和跟踪事项。
## 触发条件
- PR 创建或更新时
- 手动触发：`/risk-review`
## 输入
| 参数 | 类型 | 必填 | 说明 |
| ----------------- | ------ | ---- | ------------------------------ |
| change_summary | string | 是 | 变更说明，PR 描述或手动输入 |
| eval_report | object | 否 | 评测报告，包含通过率、失败样本 |
| security_scan | object | 否 | 安全扫描结果 |
| monitoring_config | object | 否 | 监控配置状态 |
## 输出
```json
{
"risk_level": "high|medium|low",
"decision": "block|conditional|proceed",
"blockers": [
{
"category": "security|quality|performance|monitoring",
"description": "问题描述",
"evidence": "证据链接或数据"
}
],
"warnings": [
{
"category": "string",
"description": "警告描述",
"suggestion": "建议处理方式"
}
],
"recommendations": {
"rollout_strategy": "canary|staged|direct",
"monitoring_focus": ["指标1", "指标2"],
"rollback_trigger": "回滚触发条件"
}
}
```
## 执行流程
1. **收集变更信息**
- 解析 PR 描述和 commit 信息
- 识别变更范围（API/数据/配置/前端）
2. **运行检查清单**
- 安全：依赖漏洞、敏感信息泄露、权限变更
- 质量：测试覆盖率、代码审查状态、评测结果
- 性能：性能基准、资源使用预估
- 监控：告警配置、日志覆盖、可观测性
3. **评估风险等级**
- High：存在安全漏洞、测试失败、核心功能变更
- Medium：存在警告、边界场景未覆盖
- Low：文档更新、小修复、低风险配置变更
4. **生成决策建议**
- Block：必须修复阻断问题
- Conditional：可发布但需跟踪
- Proceed：可直接发布
## 示例
### 输入
```json
{
"change_summary": "新增用户登录 API，支持多因素认证",
"eval_report": {
"pass_rate": 0.95,
"failed_cases": ["test_mfa_timeout"],
"total_cases": 100
},
"security_scan": {
"vulnerabilities": [],
"secrets_detected": false
},
"monitoring_config": {
"alerts_configured": true,
"logs_enabled": true,
"metrics": ["login_success_rate", "login_latency"]
}
}
```
### 输出
```json
{
"risk_level": "medium",
"decision": "conditional",
"blockers": [],
"warnings": [
{
"category": "quality",
"description": "MFA 超时测试用例失败",
"suggestion": "修复超时处理逻辑或更新测试预期"
}
],
"recommendations": {
"rollout_strategy": "canary",
"monitoring_focus": ["login_success_rate", "mfa_completion_rate"],
"rollback_trigger": "登录成功率 < 95% 持续 5 分钟"
}
}
```完整工作流
yaml
# .github/workflows/risk-review.yml
name: Risk Review
on:
pull_request:
types: [opened, synchronize, reopened]
jobs:
risk-review:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Run Risk Review Skill
uses: ./skills/risk-review
with:
change_summary: ${{ github.event.pull_request.body }}
eval_report: ${{ steps.eval.outputs.report }}
security_scan: ${{ steps.security.outputs.result }}
- name: Comment on PR
uses: actions/github-script@v7
with:
script: |
const result = ${{ steps.risk-review.outputs.result }});
const body = `## 🔍 发布风险审查
**风险等级**: ${result.risk_level === 'high' ? '🔴' : result.risk_level === 'medium' ? '🟡' : '🟢'} ${result.risk_level}
**决策**: ${result.decision === 'block' ? '❌ 阻断' : result.decision === 'conditional' ? '⚠️ 条件放行' : '✅ 可发布'}
${result.blockers.length > 0 ? `### 阻断问题\n${result.blockers.map(b => `- [${b.category}] ${b.description}`).join('\n')}` : ''}
${result.warnings.length > 0 ? `### 警告\n${result.warnings.map(w => `- [${w.category}] ${w.description}\n 💡 ${w.suggestion}`).join('\n')}` : ''}
### 建议
- 发布策略: ${result.recommendations.rollout_strategy}
- 重点监控: ${result.recommendations.monitoring_focus.join(', ')}
- 回滚条件: ${result.recommendations.rollback_trigger}
`;
github.rest.issues.createComment({
owner: context.repo.owner,
repo: context.repo.repo,
issue_number: context.issue.number,
body
});示例 B：需求澄清 Skill
用途：把模糊需求转成可执行用户故事。
SKILL.md
markdown
# 需求澄清 Skill
## 概述
将模糊的业务需求转化为清晰、可执行的用户故事和验收标准。
## 触发条件
- 手动触发：`/clarify-requirement`
- PR 描述包含 `需求:` 或 `Requirement:` 时自动触发
## 输入
| 参数 | 类型 | 必填 | 说明 |
| ------------- | ------ | ---- | ------------------------ |
| requirement | string | 是 | 原始需求描述 |
| context | object | 否 | 背景、目标用户、约束条件 |
| existing_docs | array | 否 | 相关文档链接 |
## 输出
```json
{
"summary": "一句话需求摘要",
"user_stories": [
{
"as_a": "角色",
"i_want": "功能",
"so_that": "目的",
"acceptance_criteria": [
"Given... When... Then...",
"Given... When... Then..."
]
}
],
"edge_cases": [
{
"scenario": "边界场景描述",
"expected_behavior": "预期行为"
}
],
"assumptions": ["假设1", "假设2"],
"risks": [
{
"category": "technical|business|user",
"description": "风险描述",
"mitigation": "缓解方案"
}
],
"clarification_questions": [
"需要澄清的问题1",
"需要澄清的问题2"
]
}
```
## 执行流程
1. **解析需求**
- 提取核心诉求
- 识别隐含假设
- 发现模糊点
2. **拆解用户故事**
- 识别用户角色
- 提取功能目标
- 澄清价值导向
3. **定义验收标准**
- 正常流程
- 异常流程
- 边界条件
4. **风险识别**
- 技术风险
- 业务风险
- 用户体验风险
## 示例
### 输入
```json
{
"requirement": "用户希望能够快速找到历史订单",
"context": {
"target_user": "C端用户",
"platform": "移动端 App",
"constraints": ["不能影响页面加载性能"]
}
}
```
### 输出
```json
{
"summary": "在移动端 App 中提供高效的历史订单搜索和筛选功能",
"user_stories": [
{
"as_a": "C端用户",
"i_want": "通过关键词搜索历史订单",
"so_that": "快速找到特定订单而不需要逐页翻找",
"acceptance_criteria": [
"Given 用户在订单列表页 When 输入订单号关键词 Then 显示匹配的订单列表",
"Given 用户在订单列表页 When 输入商品名称关键词 Then 显示包含该商品的订单",
"Given 用户输入无结果的关键词 Then 显示空状态和搜索建议"
]
},
{
"as_a": "C端用户",
"i_want": "通过时间范围筛选订单",
"so_that": "缩小搜索范围快速定位订单",
"acceptance_criteria": [
"Given 用户点击筛选按钮 When 选择时间范围 Then 显示该时间范围内的订单",
"Given 用户选择自定义时间范围 When 起止时间超过一年 Then 提示缩小范围"
]
}
],
"edge_cases": [
{
"scenario": "订单数量超过 1000 条",
"expected_behavior": "采用虚拟滚动或分页加载，保证性能"
},
{
"scenario": "搜索关键词包含特殊字符",
"expected_behavior": "正确转义，防止注入"
}
],
"assumptions": [
"订单数据已索引，支持全文搜索",
"用户已登录，有订单历史"
],
"risks": [
{
"category": "technical",
"description": "大数据量下搜索性能",
"mitigation": "引入 Elasticsearch 或预索引"
},
{
"category": "user",
"description": "用户不知道搜索入口位置",
"mitigation": "在订单列表顶部显示搜索框，首次使用引导"
}
],
"clarification_questions": [
"是否需要支持订单状态筛选？",
"是否需要搜索历史记录功能？",
"搜索结果是否需要高亮显示匹配内容？"
]
}
```示例 C：故障复盘 Skill
用途：规范事故复盘，形成可复用结论。
SKILL.md
markdown
# 故障复盘 Skill
## 概述
规范化故障复盘流程，输出结构化复盘报告和改进措施。
## 触发条件
- 手动触发：`/incident-review`
- 故障工单关闭后自动触发
## 输入
| 参数 | 类型 | 必填 | 说明 |
| ----------- | ------ | ---- | ---------- |
| incident_id | string | 是 | 故障 ID |
| timeline | array | 是 | 时间线事件 |
| impact | object | 是 | 影响范围 |
| root_cause | string | 否 | 初步根因 |
| resolution | string | 否 | 解决方案 |
## 输出
```json
{
"summary": {
"incident_id": "INC-001",
"title": "故障标题",
"severity": "P1|P2|P3",
"duration_minutes": 120,
"affected_users": 10000
},
"timeline_analysis": {
"detection_time": "发现时间（分钟）",
"response_time": "响应时间（分钟）",
"resolution_time": "解决时间（分钟）",
"bottleneck": "时间线瓶颈分析"
},
"five_whys": [
{
"why": "为什么发生？",
"answer": "原因"
}
],
"root_cause_category": "code|config|infrastructure|process|human",
"lessons_learned": [
{
"category": "prevention|detection|response|recovery",
"lesson": "经验教训",
"action": "改进行动",
"owner": "负责人",
"due_date": "截止日期"
}
],
"preventive_measures": [
{
"measure": "预防措施",
"type": "technical|process|tool",
"priority": "P0|P1|P2"
}
]
}
```
## 执行流程
1. **时间线分析**
- 标注关键节点
- 计算各阶段时长
- 识别响应瓶颈
2. **5 Whys 分析**
- 逐层追问根因
- 避免停留在表面
- 找到系统性问题
3. **影响评估**
- 用户影响范围
- 业务损失估算
- 信任影响评估
4. **改进建议**
- 预防措施
- 检测改进
- 响应优化
## 示例
### 输入
```json
{
"incident_id": "INC-2024-001",
"timeline": [
{ "time": "10:00", "event": "部署开始", "type": "deploy" },
{ "time": "10:05", "event": "错误率上升", "type": "alert" },
{ "time": "10:10", "event": "值班收到告警", "type": "notification" },
{ "time": "10:15", "event": "开始排查", "type": "investigation" },
{ "time": "10:30", "event": "定位根因：数据库连接池耗尽", "type": "root_cause" },
{ "time": "10:35", "event": "执行回滚", "type": "action" },
{ "time": "10:45", "event": "服务恢复", "type": "resolved" }
],
"impact": {
"affected_users": 5000,
"error_rate_peak": "15%",
"revenue_impact": "预估 $10,000"
}
}
```
### 输出
```json
{
"summary": {
"incident_id": "INC-2024-001",
"title": "数据库连接池耗尽导致服务不可用",
"severity": "P2",
"duration_minutes": 45,
"affected_users": 5000
},
"timeline_analysis": {
"detection_time": 5,
"response_time": 5,
"resolution_time": 35,
"bottleneck": "排查时间过长（15分钟），原因是日志不完整"
},
"five_whys": [
{ "why": "为什么服务不可用？", "answer": "数据库连接池耗尽" },
{ "why": "为什么连接池耗尽？", "answer": "新版本连接泄漏" },
{ "why": "为什么连接泄漏？", "answer": "事务未正确关闭" },
{ "why": "为什么事务未关闭？", "answer": "异常处理不完整" },
{ "why": "为什么异常处理不完整？", "answer": "代码审查未发现此问题，缺乏连接泄漏检测" }
],
"root_cause_category": "code",
"lessons_learned": [
{
"category": "prevention",
"lesson": "代码审查应包含资源泄漏检查",
"action": "新增代码审查清单项：检查连接、文件句柄等资源释放",
"owner": "Tech Lead",
"due_date": "2024-02-01"
},
{
"category": "detection",
"lesson": "连接池监控不足",
"action": "添加连接池使用率告警，阈值 80%",
"owner": "SRE Team",
"due_date": "2024-01-25"
},
{
"category": "response",
"lesson": "日志信息不完整导致排查时间长",
"action": "增强错误日志，记录连接池状态",
"owner": "Backend Team",
"due_date": "2024-01-30"
}
],
"preventive_measures": [
{ "measure": "静态代码分析检测资源泄漏", "type": "tool", "priority": "P1" },
{ "measure": "连接池使用率监控和告警", "type": "technical", "priority": "P0" },
{ "measure": "部署前连接泄漏测试", "type": "process", "priority": "P1" }
]
}
```示例 D：代码变更影响分析 Skill
用途：分析代码变更的潜在影响范围。
SKILL.md
markdown
# 代码变更影响分析 Skill
## 概述
分析代码变更的影响范围，识别潜在风险点。
## 输入
| 参数 | 类型 | 必填 | 说明 |
| ------------ | ------ | ---- | ------------------------ |
| diff | string | 是 | 代码 diff |
| file_path | string | 是 | 文件路径 |
| repo_context | object | 否 | 仓库上下文（依赖关系等） |
## 输出
```json
{
"change_type": "api|data|config|frontend|internal",
"affected_components": [
{
"name": "组件名",
"type": "service|module|api|database",
"impact": "直接|间接|潜在",
"risk": "high|medium|low"
}
],
"breaking_changes": [
{
"type": "api|data|config",
"description": "破坏性变更描述",
"migration": "迁移方案"
}
],
"test_coverage": {
"current": "当前覆盖率",
"affected_lines": "受影响行数",
"missing_tests": ["缺少测试的函数/模块"]
},
"recommendations": [
"建议1：需要回归测试的场景",
"建议2：需要关注的监控指标",
"建议3：需要通知的相关方"
]
}
```执行流程
变更分类
- API 变更
- 数据模型变更
- 配置变更
- 前端变更
- 内部逻辑变更
影响范围分析
- 直接依赖
- 间接依赖
- 潜在影响
风险评估
- 破坏性变更
- 测试覆盖
- 回滚难度
示例
输入
diff
diff --git a/src/api/user.ts b/src/api/user.ts
- async function getUser(id: string) {
+ async function getUser(id: string, options?: { includeDeleted: boolean }) {输出
json
{
"change_type": "api",
"affected_components": [
{
"name": "UserService",
"type": "service",
"impact": "直接",
"risk": "low"
},
{
"name": "OrderService",
"type": "service",
"impact": "间接",
"risk": "low"
}
],
"breaking_changes": [],
"test_coverage": {
"current": "85%",
"affected_lines": 3,
"missing_tests": ["getUser with includeDeleted option"]
},
"recommendations": [
"回归测试：用户详情页、订单用户信息展示",
"监控：getUser API 成功率和响应时间",
"通知：无破坏性变更，无需特别通知"
]
}Skill 文件结构建议
每个 Skill 建议包含以下文件：
txt
skills/
├── risk-review/
│ ├── SKILL.md # Skill 主文档
│ ├── README.md # 使用说明
│ ├── examples/ # 示例
│ │ ├── basic.md
│ │ └── advanced.md
│ ├── templates/ # 模板
│ │ ├── input.json
│ │ └── output.json
│ └── tests/ # 测试用例
│ └── test-cases.json
├── clarify-requirement/
│ └── ...
└── incident-review/
└── ...