Skill 结构设计
Skill 不是只写一篇说明文，而是要组织成"入口 + 资料 + 自动化"的结构。
推荐目录结构
txt
my-skill/
├── SKILL.md # 入口文件（必需）
├── references/ # 参考资料
│ ├── domain-knowledge.md # 领域知识
│ ├── checklists.md # 检查清单
│ ├── examples.md # 示例集合
│ └── glossary.md # 术语表
├── scripts/ # 可执行脚本
│ ├── run-check.sh # 检查脚本
│ ├── generate-report.ts # 报告生成
│ └── validate.ts # 验证脚本
├── assets/ # 模板与资源
│ ├── templates/ # 模板文件
│ │ ├── report.md
│ │ └── checklist.md
│ └── examples/ # 示例文件
│ ├── success-1.md
│ └── failure-1.md
└── tests/ # 测试用例
├── test-cases.md # 测试用例描述
└── expected/ # 期望输出
└── case-1.jsonSKILL.md 必需字段
基础字段
yaml
# SKILL.md 模板
name: my-skill # Skill 名称（必需）
version: 1.0.0 # 版本号（必需）
description: 简短描述 # 描述（必需）
author: 开发者 # 作者
created: 2026-03-08 # 创建日期
updated: 2026-03-08 # 更新日期
status: active # 状态：active | deprecated | experimental触发条件
yaml
# 触发条件
triggers:
# 关键词触发
keywords:
- 代码审查
- 安全检查
- review
# 命令触发
commands:
- /skill security-review
- /review --security
# 条件触发
conditions:
- event: pr_created
filters:
- "files_changed.includes('*.ts')"
- "author.team == 'engineering'"输入定义
yaml
# 输入参数
inputs:
- name: code_path
type: string
required: true
description: 代码路径或文件
- name: check_depth
type: enum
values: [quick, standard, deep]
default: standard
description: 检查深度
- name: focus_areas
type: array
items: [security, performance, style]
default: [security, style]
description: 关注领域工作流
yaml
# 执行流程
workflow:
# 阶段 1：收集
gather:
- step: 读取代码文件
action: file.read
input: '${inputs.code_path}'
- step: 获取代码历史
action: git.log
input: '${inputs.code_path}'
- step: 加载检查规则
action: file.read
input: ./references/checklists.md
# 阶段 2：分析
decide:
- step: 识别代码类型
action: analyze.code_type
- step: 选择检查策略
action: select_strategy
conditions:
- if: "code_type == 'frontend'"
then: use_frontend_rules
- if: "code_type == 'backend'"
then: use_backend_rules
# 阶段 3：执行
execute:
- step: 执行检查
action: run_checks
parallel: true
- step: 生成发现
action: compile_findings
- step: 计算风险等级
action: assess_risk
# 阶段 4：输出
verify:
- step: 验证输出格式
action: validate_output
- step: 检查完整性
action: check_completeness输出定义
yaml
# 输出格式
outputs:
format: json
schema:
type: object
required:
- summary
- findings
- recommendations
properties:
summary:
type: object
properties:
total_issues:
type: integer
critical:
type: integer
high:
type: integer
medium:
type: integer
low:
type: integer
findings:
type: array
items:
type: object
properties:
severity:
type: string
enum: [critical, high, medium, low]
category:
type: string
description:
type: string
location:
type: string
recommendation:
type: string
recommendations:
type: array
items:
type: string质量门禁
yaml
# 质量门禁
quality_gates:
- name: output_format
type: schema_validation
severity: blocking
- name: no_critical_issues
type: threshold
condition: findings.critical == 0
severity: warning
- name: coverage_check
type: coverage
condition: coverage >= 0.8
severity: blocking降级策略
yaml
# 降级策略
fallback:
# 输入缺失时
missing_input:
- input: code_path
fallback: 使用当前目录
# 执行失败时
execution_failure:
- error: file_too_large
fallback: 分块处理
- error: timeout
fallback: 返回部分结果并标记
# 工具不可用时
tool_unavailable:
- tool: 静态分析工具
fallback: 使用规则匹配references 目录设计
领域知识
markdown
# domain-knowledge.md
## 概述
[领域背景介绍]
## 核心概念
| 概念 | 定义 | 示例 |
| ------ | ------ | ------ |
| 概念 1 | 定义 1 | 示例 1 |
| 概念 2 | 定义 2 | 示例 2 |
## 常见问题
### 问题 1
描述...
解决方案...
## 参考资料
- [参考 1](链接)
- [参考 2](链接)
## 更新记录
- 2026-03-08: 初始版本检查清单
markdown
# checklists.md
## 前置检查
- [ ] 输入数据完整
- [ ] 环境配置正确
- [ ] 依赖工具可用
## 执行检查
- [ ] 步骤 1 完成
- [ ] 步骤 2 完成
- [ ] 步骤 3 完成
## 输出检查
- [ ] 输出格式正确
- [ ] 必需字段完整
- [ ] 无遗留问题
## 后置检查
- [ ] 资源已清理
- [ ] 日志已记录
- [ ] 状态已更新示例集合
markdown
# examples.md
## 成功示例 1
**输入：**
```json
{
"code_path": "src/auth.ts",
"check_depth": "standard"
}
```输出：
json
{
"summary": {
"total_issues": 2,
"critical": 0,
"high": 1,
"medium": 1,
"low": 0
}
}失败示例 1
输入：
json
{
"code_path": "nonexistent.ts"
}输出：
json
{
"error": "file_not_found",
"message": "指定的文件不存在"
}scripts 目录设计
脚本设计原则
yaml
原则:
- 单一职责：一个脚本解决一个动作
- 幂等性：可重复执行，结果一致
- 可观测：有清晰的日志输出
- 可恢复：失败时可以清理和重试
- 可测试：有对应的测试用例检查脚本示例
bash
#!/bin/bash
# run-check.sh - 执行检查
set -e
# 参数解析
CODE_PATH=${1:-.}
CHECK_DEPTH=${2:-standard}
OUTPUT_FILE=${3:-report.json}
# 日志函数
log_info() {
echo "[INFO] $1"
}
log_error() {
echo "[ERROR] $1" >&2
}
# 清理函数
cleanup() {
log_info "清理临时文件..."
rm -f /tmp/check-*.json
}
# 设置退出时清理
trap cleanup EXIT
# 主流程
main() {
log_info "开始检查: $CODE_PATH"
log_info "检查深度: $CHECK_DEPTH"
# 检查文件是否存在
if [ ! -e "$CODE_PATH" ]; then
log_error "路径不存在: $CODE_PATH"
exit 1
fi
# 执行检查
log_info "执行检查..."
npx ts-node scripts/validate.ts \
--path "$CODE_PATH" \
--depth "$CHECK_DEPTH" \
--output "$OUTPUT_FILE"
log_info "检查完成，结果保存到: $OUTPUT_FILE"
}
main "$@"验证脚本示例
typescript
// validate.ts - 输出验证
import { z } from 'zod'
// 定义输出 Schema
const OutputSchema = z.object({
summary: z.object({
total_issues: z.number(),
critical: z.number(),
high: z.number(),
medium: z.number(),
low: z.number(),
}),
findings: z.array(z.object({
severity: z.enum(['critical', 'high', 'medium', 'low']),
category: z.string(),
description: z.string(),
location: z.string(),
recommendation: z.string(),
})),
recommendations: z.array(z.string()),
})
export function validateOutput(output: unknown): boolean {
try {
OutputSchema.parse(output)
return true
}
catch (error) {
console.error('输出验证失败:', error)
return false
}
}
export function validateCompleteness(output: unknown): boolean {
const result = output as any
// 检查必需字段
if (!result.summary || !result.findings) {
return false
}
// 检查发现项完整性
for (const finding of result.findings) {
if (!finding.severity || !finding.description) {
return false
}
}
return true
}assets 目录设计
模板文件
markdown
<!-- templates/report.md -->
# 检查报告
## 概述
- 检查时间：{{timestamp}}
- 检查路径：{{code_path}}
- 检查深度：{{check_depth}}
## 问题统计
| 严重程度 | 数量 |
| -------- | ---------------------------- |
| Critical | {{summary.critical}} |
| High | {{summary.high}} |
| Medium | {{summary.medium}} |
| Low | {{summary.low}} |
| **总计** | **{{summary.total_issues}}** |
## 问题详情
{{#each findings}}
### {{severity}}: {{category}}
- **位置**：{{location}}
- **描述**：{{description}}
- **建议**：{{recommendation}}
{{/each}}
## 改进建议
{{#each recommendations}}
- {{this}}
{{/each}}tests 目录设计
测试用例
markdown
# test-cases.md
## 测试用例 1：正常检查
**输入：**
```json
{
"code_path": "test/fixtures/valid-code.ts",
"check_depth": "standard"
}
```期望输出：
- 输出格式正确
- 无严重问题
- 至少检查了所有文件
测试用例 2：文件不存在
输入：
json
{
"code_path": "nonexistent.ts"
}期望输出：
- 返回错误
- 错误信息清晰
- 退出码非零
测试用例 3：大文件处理
输入：
json
{
"code_path": "test/fixtures/large-file.ts",
"check_depth": "deep"
}期望输出：
- 处理成功
- 输出完整
- 无超时
常见坏味道
坏味道 1：SKILL.md 过长
yaml
问题: SKILL.md 过长但没有执行步骤
症状:
- 文件超过 500 行
- 大部分内容是背景知识
- 缺少 workflow 部分
解决:
- 将背景知识移到 references/
- 简化 SKILL.md 为入口和流程
- 保持 SKILL.md 在 200 行以内坏味道 2：references 混乱
yaml
问题: references 堆满资料，Agent 无法快速定位
症状:
- 文件数量过多
- 缺少索引
- 资料没有时效标注
解决:
- 只保留必需资料
- 添加索引文件
- 标注资料时效坏味道 3：scripts 不可重用
yaml
问题: scripts 不可在 CI 或本地重复运行
症状:
- 硬编码路径
- 缺少参数化
- 无错误处理
解决:
- 参数化所有配置
- 添加错误处理
- 支持 dry-run 模式坏味道 4：缺少测试
yaml
问题: 没有测试用例
症状:
- tests 目录不存在
- 修改后不知道是否破坏功能
- 无法验证输出正确性
解决:
- 添加测试目录
- 编写测试用例
- CI 中运行测试