Claude Code Skills 设计规范

Skill 设计规范 v1.0

基于 software-manual 和 copyright-docs 两个成熟 Skill 的设计模式提炼

目录

  1. 设计理念
  2. 目录结构规范
  3. 核心组件定义
  4. SKILL.md 入口规范
  5. Phase 阶段设计规范
  6. Specs 规范文件设计
  7. Templates 模板设计
  8. Scripts 脚本规范
  9. Prompt 工程规范
  10. 质量控制规范
  11. 最佳实践清单
  12. 示例模板

1. 设计理念

1.1 核心原则

原则说明实践
阶段化执行复杂任务分解为有序阶段使用 phases/ 目录，数字前缀控制顺序
关注点分离逻辑、配置、视图分离phases/(逻辑) + specs/(配置) + templates/(视图)
简要返回Agent 返回路径+摘要，避免上下文溢出返回 JSON 简要信息，文件存储完整内容
配置驱动规范作为"配置文件"，易于调整行为修改 specs/ 无需触及 phases/
模板复用提取通用片段，确保一致性templates/ 存放可复用内容

1.2 架构模式

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
┌─────────────────────────────────────────────────────────────────┐
│  Context-Optimized Architecture                                  │
├─────────────────────────────────────────────────────────────────┤
│                                                                  │
│  SKILL.md (入口)  →  描述目标、定义阶段、链接资源                 │
│       ↓                                                          │
│  Phase 1: 收集    →  用户输入 + 自动检测 → config.json            │
│       ↓                                                          │
│  Phase 2: 分析    →  并行 Agent → sections/*.md                  │
│       ↓                                                          │
│  Phase N: 汇总    →  交叉检查 → summary.md                       │
│       ↓                                                          │
│  Phase N+1: 组装  →  合并文件 → 最终产物                          │
│       ↓                                                          │
│  Phase N+2: 迭代  →  用户反馈 → 优化                              │
│                                                                  │
└─────────────────────────────────────────────────────────────────┘

2. 目录结构规范

2.1 标准目录结构

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
[skill-name]/
├── SKILL.md                     # 【必需】技能入口：元数据 + 架构 + 执行流程
├── phases/                      # 【必需】执行阶段 Prompt
│   ├── 01-{first-step}.md       #   数字前缀定义顺序
│   ├── 02-{second-step}.md
│   ├── 02.5-{sub-step}.md       #   小数点用于插入子步骤
│   └── ...
├── specs/                       # 【必需】规范与约束
│   ├── {domain}-requirements.md #   领域特定要求
│   ├── quality-standards.md     #   质量标准
│   └── writing-style.md         #   写作风格（如适用）
├── templates/                   # 【推荐】可复用模板
│   ├── agent-base.md            #   Agent 基础 Prompt 模板
│   ├── output-shell.{ext}       #   输出外壳模板（html/md）
│   └── css/                     #   样式文件（如适用）
├── scripts/                     # 【可选】辅助脚本
│   ├── {tool}.py                #   Python 脚本
│   └── {tool}-runner.md         #   脚本使用说明
└── outputs/                     # 【运行时】执行产物（不纳入版本控制）

2.2 命名约定

类型规则示例
Skill 目录小写-连字符software-manual, copyright-docs
Phase 文件NN-{动作}.md01-metadata-collection.md
Spec 文件{领域}-{类型}.mdcpcc-requirements.md
Template 文件{用途}-{类型}.{ext}agent-base.md, tiddlywiki-shell.html
输出文件section-{N}-{名称}.mdsection-2-architecture.md

3. 核心组件定义

3.1 组件职责矩阵

组件职责内容类型修改频率
SKILL.md入口 + 编排元数据、架构图、执行流程低（结构稳定）
phases/*.md执行逻辑步骤说明、Prompt、代码示例中（优化迭代）
specs/*.md约束配置规则、标准、检查清单中（需求变更）
templates/*可复用片段Prompt 模板、输出格式低（通用稳定）
scripts/*自动化Python/JS 脚本高（功能增强）

3.2 组件依赖关系

image-20260123090700226

4. SKILL.md 入口规范

4.1 必需结构

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
---
name: {skill-name}
description: {一句话描述}. {触发关键词}. Triggers on "{关键词1}", "{关键词2}".
allowed-tools: Task, AskUserQuestion, Read, Bash, Glob, Grep, Write, {其他MCP工具}
---

# {Skill 标题}

{一段话描述 Skill 的用途和产出}

## Architecture Overview

{ASCII 或 Mermaid 架构图}

## Key Design Principles

1. **原则1**: 说明
2. **原则2**: 说明
...

## Execution Flow

{阶段执行流程图}

## Agent Configuration (如适用)

| Agent | Role | Output File | Focus Areas |
|-------|------|-------------|-------------|
| ... | ... | ... | ... |

## Directory Setup

{工作目录创建代码}

## Output Structure

{输出目录结构}

## Reference Documents

| Document | Purpose |
|----------|---------|
| [phases/01-xxx.md](phases/01-xxx.md) | ... |
| ... | ... |

4.2 Front Matter 规范

1
2
3
4
5
6
7
8
9
---
name: skill-name              # 必需：Skill 唯一标识
description: |                # 必需：描述 + 触发词
  Generate XXX documents. 
  Triggers on "keyword1", "keyword2".
allowed-tools: |              # 必需：允许使用的工具
  Task, AskUserQuestion, Read, Bash, 
  Glob, Grep, Write, mcp__chrome__*
---

5. Phase 阶段设计规范

5.1 Phase 文件结构

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
# Phase N: {阶段名称}

{一句话描述此阶段目标}

## Objective

{详细目标说明}
- 目标1
- 目标2

## Execution Steps

### Step 1: {步骤名称}

{代码或说明}

### Step 2: {步骤名称}

{代码或说明}

## Output

- **File**: `{输出文件名}`
- **Location**: `{输出路径}`
- **Format**: {JSON/Markdown/HTML}

## Next Phase

Proceed to [Phase N+1: xxx](0N+1-xxx.md) with the generated {产出}.

5.2 Phase 类型

类型特点示例
收集型用户交互 + 自动检测01-requirements-discovery.md
探索型代码分析 + 结构识别02-project-exploration.md
并行型多 Agent 并行执行03-parallel-analysis.md
汇总型交叉检查 + 质量验证03.5-consolidation.md
组装型合并产出 + 格式化04-document-assembly.md
迭代型用户反馈 + 优化05-iterative-refinement.md

5.3 Phase 编号规则

1
2
3
4
01-xxx.md      # 主阶段
02-xxx.md      # 主阶段
02.5-xxx.md    # 子阶段（插入 02 和 03 之间）
03-xxx.md      # 主阶段

6. Specs 规范文件设计

6.1 Specs 类型

类型用途示例
领域要求领域特定合规性cpcc-requirements.md
质量标准输出质量评估quality-standards.md
写作风格内容风格指南writing-style.md
模板规范输出格式定义html-template.md

6.2 Specs 结构模板

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
# {规范名称}

{规范用途说明}

## When to Use

| Phase | Usage | Section |
|-------|-------|---------|
| Phase N | {使用场景} | {引用章节} |
| ... | ... | ... |

---

## Requirements

### Category 1

- [ ] 检查项1
- [ ] 检查项2

### Category 2

| 项目 | 要求 | 检查方式 |
|------|------|----------|
| ... | ... | ... |

## Validation Function

{验证函数代码}

## Error Handling

| Error | Recovery |
|-------|----------|
| ... | ... |

6.3 质量标准示例结构

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
# Quality Standards

## Quality Dimensions

### 1. Completeness (25%)
{评分标准}

### 2. Consistency (25%)
{评分标准}

### 3. Depth (25%)
{评分标准}

### 4. Readability (25%)
{评分标准}

## Quality Gates

| Gate | Threshold | Action |
|------|-----------|--------|
| Pass | ≥ 80% | 继续执行 |
| Review | 60-79% | 处理警告后继续 |
| Fail | < 60% | 必须修复 |

## Issue Classification

### Errors (Must Fix)
- ...

### Warnings (Should Fix)
- ...

### Info (Nice to Have)
- ...

7. Templates 模板设计

7.1 Agent 基础模板

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
# Agent Base Template

## 通用提示词结构

[ROLE] 你是{角色}，专注于{职责}。

[TASK]
{任务描述}
- 输出: {output_path}
- 格式: {format}
- 范围: {scope}

[CONSTRAINTS]
- 约束1
- 约束2

[OUTPUT_FORMAT]
1. 直接写入文件
2. 返回 JSON 简要信息

[QUALITY_CHECKLIST]
- [ ] 检查项1
- [ ] 检查项2

## 变量说明

| 变量 | 来源 | 示例 |
|------|------|------|
| {output_dir} | Phase 1 | .workflow/.scratchpad/xxx |
| ... | ... | ... |

## Agent 配置映射

{AGENT_ROLES, AGENT_SECTIONS, AGENT_FILES, AGENT_FOCUS}

7.2 输出模板规范

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
<!-- output-shell.html 示例 -->
<!DOCTYPE html>
<html>
<head>
    <meta charset="UTF-8">
    <title>{{title}}</title>
    <style>
        /* 内嵌 CSS */
        {{styles}}
    </style>
</head>
<body>
    <div id="app">
        {{content}}
    </div>
    <script>
        /* 内嵌 JS */
        {{scripts}}
    </script>
</body>
</html>

7.3 占位符规范

占位符格式用途示例
{{variable}}简单变量替换{{title}}
${variable}JavaScript 模板字符串${workDir}
{placeholder}Prompt 占位{intro}, {diagram}

8. Scripts 脚本规范

8.1 脚本类型

类型用途命名
提取器从代码提取信息extract_*.py
组装器合并/转换文件assemble_*.py
验证器检查合规性validate_*.py
辅助器工具函数*_helper.py

8.2 脚本使用说明文件

每个脚本应有对应的 .md 说明文件：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
# {Script Name} Runner

## Purpose

{脚本用途}

## Usage

{命令行使用方式}

## Parameters

| 参数 | 说明 | 默认值 |
|------|------|--------|
| ... | ... | ... |

## Output

{输出说明}

## Example

{使用示例}

9. Prompt 工程规范

9.1 Prompt 结构标准

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
[ROLE] {角色定义}

[PROJECT CONTEXT]
项目类型: {type}
语言: {language}
名称: {name}

[TASK]
{任务描述}
输出: {output_path}

[INPUT]
- 配置: {config_path}
- 扫描路径: {scan_paths}

[CONTENT REQUIREMENTS]
- 标题层级: # ## ### (最多3级)
- 代码块: ```language ... ``` (必须标注语言)
- 表格: | col1 | col2 | 格式
- 列表: 有序 1. 2. 3. / 无序 - - -

[FOCUS]
{重点关注项}

[OUTPUT FORMAT]
{输出格式说明}

[RETURN JSON]
{返回结构}

9.2 效率优化原则

原则Before (冗余)After (精简)
角色简化“你是一个专业的系统架构师，具有丰富的软件设计经验…”[ROLE] 系统架构师，专注于分层设计和模块依赖
模板驱动“请按照以下格式输出: 首先写一个二级标题…”[TEMPLATE] ## 2. 标题 {content}
焦点明确“分析项目的各个方面，包括架构、模块、依赖等”[FOCUS] 1. 分层 2. 模块 3. 依赖 4. 数据流
返回简洁“请返回详细的分析结果，包括所有发现的问题…”[RETURN] {"status":"completed","output_file":"xxx.md","summary":"<50字"}

9.3 Agent 返回格式标准

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
interface AgentReturn {
  status: "completed" | "partial" | "failed";
  output_file: string;           // 输出文件路径
  summary: string;               // 最多 50 字摘要
  cross_module_notes?: string[]; // 跨模块备注
  stats?: {                      // 统计信息
    diagrams?: number;
    words?: number;
  };
  screenshots_needed?: Array<{   // 截图需求（如适用）
    id: string;
    url: string;
    description: string;
  }>;
}

10. 质量控制规范

10.1 质量维度

维度权重检查项
完整性25%所有必需章节存在且有实质内容
一致性25%术语、格式、风格统一
深度25%内容详尽、示例充分
可读性25%结构清晰、语言简洁

10.2 质量门控

1
2
3
4
5
const QUALITY_GATES = {
  pass: { threshold: 80, action: "继续执行" },
  review: { threshold: 60, action: "处理警告后继续" },
  fail: { threshold: 0, action: "必须修复后重试" }
};

10.3 问题分类

级别前缀含义处理方式
ErrorE阻塞性问题必须修复
WarningW影响质量建议修复
InfoI可改进项可选修复

10.4 自动化检查函数模板

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
function runQualityChecks(workDir) {
  const results = {
    completeness: checkCompleteness(workDir),
    consistency: checkConsistency(workDir),
    depth: checkDepth(workDir),
    readability: checkReadability(workDir)
  };

  results.overall = Object.values(results).reduce((a, b) => a + b) / 4;
  
  return {
    score: results.overall,
    gate: results.overall >= 80 ? 'pass' : 
          results.overall >= 60 ? 'review' : 'fail',
    details: results
  };
}

11. 最佳实践清单

11.1 Skill 设计

  • [ ] 单一职责: 每个 Skill 专注一个领域
  • [ ] 清晰入口: SKILL.md 完整描述目标和流程
  • [ ] 阶段分解: 复杂任务拆分为 3-7 个阶段
  • [ ] 顺序命名: 使用数字前缀控制执行顺序

11.2 Phase 设计

  • [ ] 明确目标: 每个 Phase 有清晰的输入输出
  • [ ] 独立可测: 每个 Phase 可单独调试
  • [ ] 链接下一步: 明确说明后续阶段

11.3 Prompt 设计

  • [ ] 角色明确: 使用 [ROLE] 定义 Agent 身份
  • [ ] 任务具体: 使用 [TASK] 明确执行目标
  • [ ] 约束清晰: 使用 [CONSTRAINTS] 定义边界
  • [ ] 返回简洁: Agent 返回路径+摘要，非完整内容

11.4 质量控制

  • [ ] 规范驱动: 使用 specs/ 定义可验证的标准
  • [ ] 汇总检查: 设置 Consolidation 阶段交叉验证
  • [ ] 问题分级: 区分 Error/Warning/Info
  • [ ] 迭代优化: 支持用户反馈循环

12. 示例模板

12.1 新 Skill 快速启动模板

1
2
3
4
5
6
7
8
# 创建 Skill 目录结构
mkdir -p my-skill/{phases,specs,templates,scripts}

# 创建核心文件
touch my-skill/SKILL.md
touch my-skill/phases/{01-collection,02-analysis,03-assembly}.md
touch my-skill/specs/{requirements,quality-standards}.md
touch my-skill/templates/agent-base.md

12.2 SKILL.md 最小模板

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
---
name: my-skill
description: Generate XXX. Triggers on "keyword1", "keyword2".
allowed-tools: Task, AskUserQuestion, Read, Bash, Glob, Grep, Write
---

# My Skill

Generate XXX through multi-phase analysis.

## Execution Flow

1. Phase 1: Collection → config.json
2. Phase 2: Analysis → sections/*.md
3. Phase 3: Assembly → output.md

## Reference Documents

| Document | Purpose |
|----------|---------|
| [phases/01-collection.md](phases/01-collection.md) | 信息收集 |
| [phases/02-analysis.md](phases/02-analysis.md) | 代码分析 |
| [phases/03-assembly.md](phases/03-assembly.md) | 文档组装 |

附录 A: 设计对比

设计点software-manualcopyright-docs
阶段数65
并行 Agent66
输出格式HTMLMarkdown
质量检查4 维度评分CPCC 合规检查
截图支持Chrome MCP无
迭代优化用户反馈循环合规验证循环

附录 B: 工具依赖

工具用途适用 Skill
Task启动子 Agent所有
AskUserQuestion用户交互所有
Read/Write/Glob/Grep文件操作所有
Bash脚本执行需要自动化
mcp__chrome__*浏览器截图UI 相关