# 附录
 #### Skill代码包文件要求
一个标准的Skill是一个文件夹，其结构和命名需要遵循特定的规范。
#### Skill文件夹结构与命名规范
```
skill-name/
├── SKILL.md (必需)
│   ├── YAML frontmatter 元数据 (必需)
│   │   ├── name: (必需)
│   │   └── description: (必需)
│   └── Markdown 指令正文 (必需)
└── 捆绑资源 (可选)
    ├── scripts/          - 可执行脚本 (Python/Bash 等)
    ├── references/       - 按需加载的参考文档
    └── assets/           - 输出用文件 (模板、图标、字体等)
```
![](https://support.huaweicloud.com/usermanual-officeace/public_sys-resources/note_3.0-zh-cn.png)
1. SKILL.md是**必需**的唯一入口文件，区分大小写，必须全大写SKILL.md，不接受skill.md或SKILL.MD等变体。
2. 捆绑资源目录scripts/、references/、assets/均为**可选**，仅在确有内容时才创建，不要创建占位/示例文件或空目录。
3. 不应包含README.md、INSTALLATION_GUIDE.md、CHANGELOG.md等辅助文档，Skill只应包含AI agent完成任务所需的必要文件。
4. 文件夹命名规则
   - 必须使用短横线命名法，例如：notion-project-setup。
   
   - 禁止使用空格，反例：Notion Project Setup。
   
   - 禁止使用下划线，反例：notion_project_setup。
   
   - 禁止使用大写字母，反例：NotionProjectSetup。
    
 
#### SKILL.md格式要求
SKILL.md文件是Skill的核心，它由两部分组成：顶部的YAML Frontmatter（元数据） 和下方的 Markdown正文（指令）。
- **YAML Frontmatter（必需）**
  ```
  ---
  name: skill-name                          # 【必需】skill 标识符（小写、连字符）
  description: "描述何时触发、做什么"        # 【必需】触发条件 + 功能说明
  homepage: https://example.com             # 【可选】主页
  license: MIT                              # 【可选】许可证
  metadata:                                 # 【可选】元数据
    openclaw:
      emoji: ""
      requires: { "bins": ["python"] }
  ---
  ```
  **关键点：**
  - name: 小写字母 + 连字符，如pdf、skill-creator
  
  - description: 这是**触发机制** 。请描述清晰明确，确保用户意图能够精准匹配。包含：
    - 这个skill做什么
    
    - 什么情况下应该使用
    
    - 什么情况下**不**应该使用
     
   
- **Markdown正文**
  正文是给AI的操作指南，建议结构：
  ```
  # Skill Title
  简短介绍这个 skill 的用途。
  ## When to Use
    **USE this skill when:**
  - 用户说 "..."
  - 涉及 xxx 操作
  ## When NOT to Use
     **DON'T use this skill when:**
  - 需要 xxx → 用其他 skill
  ## How to Use
  具体操作步骤...
  ## Examples
  示例代码或命令...
  ## Notes
  注意事项...
  ```
  
 
#### 示例1：单文件Skill（todo-manager）
```
todo-manager/
└── SKILL.md    ← 唯一文件
```
- **功能：** 待办事项管理
  - 添加/查看/完成/删除待办
  
  - 数据存储在memory/todos.json
   
- SKILL.md文件内容
  ```
  ---
  name: todo-manager
  description: "管理待办事项清单。当用户说添加待办、查看待办、完成待办、待办列表、todo、任务清单时使用此 skill。支持添加、查看、标记完成、删除待办事项。"
  ---
  # 待办事项管理 Skill
  一个简单的待办事项管理工具，帮助用户追踪日常任务。
  ## 何时使用
    **使用场景：**
  - 帮我记一个待办：明天开会
  - 查看我的待办列表
  - 完成第一个待办
  - 删除某个任务
  - 我有什么事没做？
    **不适用场景：**
  - 项目管理（用专业工具如 Notion）
  - 团队协作任务（用飞书/钉钉）
  - 复杂的甘特图/时间线
  ## 数据存储
  待办数据存储在 memory/todos.json
  ## 操作命令
  ### 添加待办
  1. 读取 memory/todos.json
  2. 生成新 ID
  3. 添加新条目
  4. 保存文件
  ### 查看待办
  1. 读取 memory/todos.json
  2. 按完成状态分组显示
  ### 标记完成
  1. 找到对应条目
  2. 设置 completed = true
  3. 保存
  ### 删除待办
  1. 找到并删除对应条目
  2. 保存
  ```
  
 
#### 示例2：文件夹形式Skill（daily-report）
```
daily-report/
├── SKILL.md              ← 核心定义
├── scripts/              ← 脚本目录
│   └── generate_report.py
└── references/           ← 参考文档目录
    └── config.md
```
- **功能：** 工作日报生成
  - 收集今日工作内容
  
  - 按模板生成日报
  
  - 支持多种输出格式
   
- **SKILL.md** 文件内容
  ```
  ---
  name: daily-report
  description: "生成工作日报。当用户说写日报、生成日报、今日工作总结、daily report时使用。自动汇总今日完成的任务、遇到的问题、明日计划。"
  ---
  # 日报生成器 Skill
  自动生成结构化的工作日报，支持多种输出格式。
  ## 何时使用
    **使用场景：**
  - 帮我写个日报
  - 生成今日工作总结
  - 写个 daily report
  - 汇总今天的工作
    **不适用场景：**
  - 周报/月报（用专门的报告 skill）
  - 项目进度报告（用项目管理工具）
  ## 日报模板
  生成的日报包含以下部分：
  - 今日完成
  - 进行中
  - 遇到的问题
  - 明日计划
  ## 使用流程
  ### Step 1: 收集信息
  询问用户今日工作内容
  ### Step 2: 生成日报
  根据用户输入，按模板格式生成日报
  ### Step 3: 保存输出
  将日报保存到 reports/daily/YYYY-MM-DD.md
  ### Step 4: 可选格式转换
  询问用户是否需要其他格式：
  - Word 文档
  - 发送飞书
  ## 快捷命令
  如果用户说快速日报，直接生成简化版
  ```
  
- **generate_report.py** 示例代码
  ```
  #!/usr/bin/env python3
  """生成日报脚本"""
  import os
  from datetime import datetime
  def generate_report(data):
      today = datetime.now().strftime("%Y-%m-%d")
      report = f"# 工作日报\n\n**日期：** {today}\n\n---\n\n## 今日完成\n"
      for i, item in enumerate(data.get("completed", []), 1):
          report += f"{i}. {item}\n"
      return report
  if __name__ == "__main__":
      print("日报生成器")
  ```
  
- **config.md** 文件内容
  ```
  # 日报配置
  ## 模板设置
  | 配置项 | 默认值 | 说明 |
  |---|---|---|
  | template | standard | 日报模板样式 |
  | output_dir | reports/daily | 输出目录 |
  ```