Claude-Code-Workflow/.claude/skills/_shared/SKILL-DESIGN-SPEC.md

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 架构模式

┌─────────────────────────────────────────────────────────────────┐
│  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 标准目录结构

[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-{动作}.md	01-metadata-collection.md
Spec 文件	{领域}-{类型}.md	cpcc-requirements.md
Template 文件	{用途}-{类型}.{ext}	agent-base.md, tiddlywiki-shell.html
输出文件	section-{N}-{名称}.md	section-2-architecture.md

---

3. 核心组件定义

3.1 组件职责矩阵

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

3.2 组件依赖关系

graph TD
    SKILL[SKILL.md] --> P1[phases/01-*]
    P1 --> P2[phases/02-*]
    P2 --> PN[phases/N-*]
    
    P1 -.->|引用| SPEC[specs/*]
    P2 -.->|引用| SPEC
    PN -.->|引用| SPEC
    
    P1 -.->|使用| TPL[templates/*]
    PN -.->|使用| TPL
    
    P2 -->|调用| SCR[scripts/*]
    
    style SKILL fill:#e1f5fe
    style SPEC fill:#fff3e0
    style TPL fill:#e8f5e9
    style SCR fill:#fce4ec

---

4. SKILL.md 入口规范

4.1 必需结构

---
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 规范

---
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 文件结构

# 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 编号规则

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 结构模板

# {规范名称}

{规范用途说明}

## When to Use

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

---

## Requirements

### Category 1

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

### Category 2

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

## Validation Function

{验证函数代码}

## Error Handling

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

6.3 质量标准示例结构

# 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 基础模板

# 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 输出模板规范

<!-- 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 说明文件：

# {Script Name} Runner

## Purpose

{脚本用途}

## Usage

{命令行使用方式}

## Parameters

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

## Output

{输出说明}

## Example

{使用示例}

---

9. Prompt 工程规范

9.1 Prompt 结构标准

[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 返回格式标准

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 质量门控

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

10.3 问题分类

级别	前缀	含义	处理方式
Error	E	阻塞性问题	必须修复
Warning	W	影响质量	建议修复
Info	I	可改进项	可选修复

10.4 自动化检查函数模板

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 快速启动模板

# 创建 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 最小模板

---
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-manual	copyright-docs
阶段数	6	5
并行 Agent	6	6
输出格式	HTML	Markdown
质量检查	4 维度评分	CPCC 合规检查
截图支持	Chrome MCP	无
迭代优化	用户反馈循环	合规验证循环

附录 B: 工具依赖

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

---

规范版本: 1.0
基于: software-manual, copyright-docs
最后更新: 2026-01-03