structure-design-skill

- v1.0.0 (2026-01-19): åå§çæ¬

maxoreric 0 Updated 7mo ago

Resources

GitHub

Install

npx skillscat add maxoreric/sop-engine/skills-structure-design-skill

Install via the SkillsCat registry.

About this skill

This skill generates standardized directory structures for AI systems based on input plans specifying agents, workflows, and data needs. It enforces consistent organization using predefined templates to improve maintainability and scalability. Developers should use it when building complex multi-agent systems requiring clear separation of configuration, data, and output components.

SKILL.md

structure-design-skill

用途: 设计系统的目录结构

输入: 计划（plan）包含系统需求、功能模块等

输出: 完整的目录结构定义

核心原则

遵循 sop-engine 标准 - 所有系统都应遵循标准目录结构
按功能分层 - .claude/ 存配置，data/ 存数据，outputs/ 存产出
可扩展 - 预留扩展空间
清晰命名 - 目录和文件名要自解释

标准目录结构模板

<system-name>/
├── .claude/                    # Claude Code 配置
│   ├── agents/                 # Subagents
│   ├── skills/                 # Skills
│   ├── commands/               # Slash commands（可选）
│   └── hooks/                  # Hooks（可选）
├── .sop-engine/                # sop-engine 运行时
│   ├── skills/                 # Skill 运行数据
│   ├── workflows/              # Workflow 定义
│   └── running/                # 运行中的实例
├── agents/                     # Agent 工作空间
│   └── <agent-name>/
│       ├── knowledge/          # 知识库
│       └── handoff/            # 交接记录
├── data/                       # 系统数据
│   ├── <domain-specific>/      # 领域特定数据
│   └── ...
├── outputs/                    # 产出
│   └── <output-type>/
├── README.md                   # 使用说明
└── DESIGN.md                   # 设计文档

输入格式

plan:
  system_name: string           # 系统名称
  domain: string                # 领域（health, finance, learning...）
  agents:                       # Agent 列表
    - name: string
      responsibilities: array
  skills:                       # Skill 列表
    - name: string
      purpose: string
  workflows:                    # Workflow 列表
    - name: string
      steps: array
  data_requirements:            # 数据需求
    - type: string              # 数据类型
      structure: string         # 存储方式
  outputs:                      # 产出类型
    - type: string              # 报告、图表等

输出格式

structure:
  root: string                  # 根目录名
  directories:                  # 目录列表
    - path: string              # 相对路径
      purpose: string           # 用途说明
      required: boolean         # 是否必需
      examples: array           # 示例文件
  
  files:                        # 必需的文件
    - path: string
      purpose: string
      template: string          # 模板内容（可选）
  
  data_structure:               # 数据结构说明
    - category: string
      location: string
      format: string

执行逻辑

1. 分析需求

从 plan 中提取：

系统类型（health / finance / learning / ...）
Agent 数量
Skill 数量
Workflow 数量
数据类型
产出类型

2. 确定目录

基于标准模板 + 领域特定需求：

def design_structure(plan):
    structure = {
        "root": plan.system_name,
        "directories": [],
        "files": []
    }
    
    # 标准目录（必需）
    structure["directories"].extend([
        {"path": ".claude/agents/", "required": True},
        {"path": ".claude/skills/", "required": True},
        {"path": ".sop-engine/workflows/", "required": True},
        {"path": "data/", "required": True},
        {"path": "outputs/", "required": True}
    ])
    
    # 领域特定目录
    if plan.domain == "health":
        structure["directories"].extend([
            {"path": "data/profile/", "purpose": "用户健康档案"},
            {"path": "data/indicators/", "purpose": "健康指标记录"},
            {"path": "data/checkups/", "purpose": "体检报告"},
            {"path": "outputs/reports/", "purpose": "健康报告"}
        ])
    
    elif plan.domain == "finance":
        structure["directories"].extend([
            {"path": "data/accounts/", "purpose": "账户信息"},
            {"path": "data/transactions/", "purpose": "交易记录"},
            {"path": "outputs/analysis/", "purpose": "财务分析"}
        ])
    
    # ... 更多领域
    
    return structure

3. 添加必需文件

files:
  - path: README.md
    purpose: 系统使用说明
    template: |
      # {system_name}
      
      ## 概述
      
      ## 快速开始
      
      ## 功能说明
  
  - path: DESIGN.md
    purpose: 设计文档
    template: |
      # {system_name} 设计文档
      
      ## 系统目标
      
      ## 架构设计
      
      ## 数据流
  
  - path: data/.gitkeep
    purpose: 保留空目录

4. 生成数据结构说明

data_structure:
  - category: 个人档案
    location: data/profile/profile.json
    format: |
      {
        "name": "string",
        "age": "number",
        "health_history": []
      }
  
  - category: 健康指标
    location: data/indicators/{date}.json
    format: |
      {
        "date": "YYYY-MM-DD",
        "weight": "number",
        "blood_pressure": "string",
        ...
      }

示例

输入: 健康管理系统

plan:
  system_name: health-system
  domain: health
  focus: disease_prevention
  
  agents:
    - name: health-advisor
      responsibilities:
        - 分析体检报告
        - 评估健康风险
        - 提供建议
  
  skills:
    - name: checkup-analysis-skill
      purpose: 分析体检报告
    - name: health-indicators-skill
      purpose: 追踪健康指标
    - name: risk-assessment-skill
      purpose: 评估风险
    # ... 更多
  
  workflows:
    - name: daily-check
      trigger: "21:00"
    - name: weekly-report
      trigger: "Sunday 20:00"
    - name: checkup-analysis
      trigger: "file_upload"
  
  data_requirements:
    - type: profile
      structure: JSON
    - type: indicators
      structure: daily JSON files
    - type: checkups
      structure: PDF + parsed JSON
  
  outputs:
    - type: reports
      format: Markdown

输出: 目录结构

structure:
  root: health-system
  
  directories:
    # 标准目录
    - path: .claude/agents/
      purpose: Agent 定义
      required: true
      examples:
        - health-advisor.md
    
    - path: .claude/skills/
      purpose: Skill 定义
      required: true
      examples:
        - checkup-analysis/
        - health-indicators/
        - risk-assessment/
    
    - path: .sop-engine/workflows/
      purpose: Workflow 定义
      required: true
      examples:
        - daily-check.yaml
        - weekly-report.yaml
        - checkup-analysis.yaml
    
    - path: .sop-engine/running/
      purpose: 运行中的 Workflow 实例
      required: true
    
    - path: agents/health-advisor/
      purpose: health-advisor 的工作空间
      required: true
    
    - path: agents/health-advisor/knowledge/
      purpose: 积累的健康知识
      required: true
    
    - path: agents/health-advisor/handoff/
      purpose: 任务交接记录
      required: true
    
    # 领域特定目录
    - path: data/profile/
      purpose: 用户健康档案
      required: true
      examples:
        - profile.json
    
    - path: data/indicators/
      purpose: 每日健康指标
      required: true
      examples:
        - 2026-01-19.json
        - 2026-01-20.json
    
    - path: data/checkups/
      purpose: 体检报告（原始 + 解析后）
      required: true
      examples:
        - raw/2025-annual-checkup.pdf
        - parsed/2025-annual-checkup.json
    
    - path: outputs/reports/
      purpose: 生成的健康报告
      required: true
      examples:
        - daily/2026-01-19-daily.md
        - weekly/2026-W03-weekly.md
  
  files:
    - path: README.md
      purpose: 系统使用说明
      template: |
        # health-system
        
        健康管理系统 - 预防疾病、追踪指标、评估风险
        
        ## 快速开始
        
        1. 填写个人档案: `data/profile/profile.json`
        2. 记录今日数据: `data/indicators/{今天日期}.json`
        3. 触发每日检查: "执行每日健康检查"
        
        ## 核心功能
        
        - 每日健康检查（21:00 自动触发）
        - 每周健康报告（周日 20:00 自动触发）
        - 体检报告分析（上传文件后触发）
    
    - path: DESIGN.md
      purpose: 设计文档
    
    - path: data/profile/profile.json
      purpose: 个人健康档案（示例）
      template: |
        {
          "name": "张三",
          "age": 35,
          "gender": "male",
          "height": 175,
          "health_history": [
            "无重大疾病史"
          ],
          "allergies": [],
          "medications": []
        }
    
    - path: data/indicators/2026-01-19.json
      purpose: 健康指标示例
      template: |
        {
          "date": "2026-01-19",
          "weight": 70.5,
          "blood_pressure": "120/80",
          "heart_rate": 72,
          "sleep_hours": 7.5,
          "exercise_minutes": 30,
          "water_intake_ml": 2000,
          "notes": "感觉良好"
        }
  
  data_structure:
    - category: 个人档案
      location: data/profile/profile.json
      format: |
        {
          "name": "string",
          "age": "number",
          "gender": "male | female",
          "height": "number (cm)",
          "health_history": ["string"],
          "allergies": ["string"],
          "medications": ["string"]
        }
    
    - category: 每日指标
      location: data/indicators/{YYYY-MM-DD}.json
      format: |
        {
          "date": "YYYY-MM-DD",
          "weight": "number (kg)",
          "blood_pressure": "string (120/80)",
          "heart_rate": "number (bpm)",
          "sleep_hours": "number",
          "exercise_minutes": "number",
          "water_intake_ml": "number",
          "notes": "string"
        }
    
    - category: 体检报告
      location: data/checkups/parsed/{name}.json
      format: |
        {
          "date": "YYYY-MM-DD",
          "source": "string (医院名)",
          "indicators": {
            "血常规": {...},
            "肝功能": {...},
            "肾功能": {...}
          },
          "abnormal_items": ["string"],
          "risk_factors": ["string"]
        }

领域模板库

health（健康管理）

directories:
  - data/profile/           # 健康档案
  - data/indicators/        # 每日指标
  - data/checkups/          # 体检报告
  - data/medications/       # 用药记录（如果是慢病管理）
  - data/diet/              # 饮食记录（如果需要）
  - data/exercise/          # 运动记录（如果需要）
  - outputs/reports/daily/  # 每日报告
  - outputs/reports/weekly/ # 每周报告

finance（财务管理）

directories:
  - data/accounts/          # 账户信息
  - data/transactions/      # 交易记录
  - data/budgets/           # 预算
  - data/investments/       # 投资
  - outputs/analysis/       # 财务分析
  - outputs/tax/            # 税务文档

learning（学习管理）

directories:
  - data/goals/             # 学习目标
  - data/progress/          # 学习进度
  - data/notes/             # 笔记
  - data/resources/         # 学习资源
  - outputs/summaries/      # 总结
  - outputs/plans/          # 学习计划

评价标准

见 criteria.md

版本历史

v1.0.0 (2026-01-19): 初始版本

structure-design-skill

Resources

Install

structure-design-skill

核心原则

标准目录结构模板

输入格式

输出格式

执行逻辑

1. 分析需求

2. 确定目录

3. 添加必需文件

4. 生成数据结构说明

示例

输入: 健康管理系统

输出: 目录结构

领域模板库

health（健康管理）

finance（财务管理）

learning（学习管理）

评价标准

版本历史

Categories

Install

Recommended Skills