OpenMesh/Skills撰写规范.md

OpenMesh Skills 撰写规范

本文档定义了 OpenMesh Skills 的撰写标准，确保模型能够正确理解和使用技能。

---

一、文件结构规范

必需文件

每个 Skill 必须包含以下文件：

文件	用途
SKILL.md	技能的入口文档，包含元数据、使用说明、依赖、示例
LICENSE.txt	许可证文件（参考现有技能使用 Proprietary 许可证）
scripts/	脚本目录，包含所有可执行脚本
scripts/*.py	Python 脚本
scripts/*.js 或 *.cjs	Node.js 脚本（可选）

可选文件

文件	用途
reference.md	高级功能或详细 API 参考
forms.md	表单处理等特定功能的专门指南
pptxgenjs.md	PPT 创建的专门指南
editing.md	编辑操作的专门指南

---

二、SKILL.md 必填结构

2.1 YAML 前言（必须）

---
name: <skill-name>           # 技能名称，模型用此名称调用
description: "<触发描述>"     # 触发条件描述，模型据此决定何时使用此技能
license: Proprietary. LICENSE.txt has complete terms
metadata:
  builtin_skill_version: "1.0"  # 版本号
---

2.2 工具说明（必须）

必须放在 YAML 前言之后、第一个标题之前：

> **重要：** 所有 `scripts/` 路径均相对于此技能目录。
> 运行方式：使用 `run_shell` 工具执行命令，例如：
> ```bash
> cd {skill_dir} && python scripts/example.py arg1 arg2
> ```
> `run_shell` 不支持 `cwd` 参数，必须使用 `cd` 命令切换目录。

禁止使用以下不存在的工具名称：

• ❌ execute_shell_command
• ❌ run_shell_command
• ❌ execute_shell
• ❌ 任何未在 OpenMesh 中注册的工具名

禁止使用以下不存在的参数：

• ❌ cwd — run_shell 不支持此参数，必须用 cd 命令切换目录
• ✅ command — 命令字符串（必填）
• ✅ description — 简短描述（可选）
• ✅ timeout_seconds — 超时秒数（可选，默认 120 秒）
• ✅ run_in_background — 后台运行（可选）

2.3 前置依赖说明

列出所有依赖，并注明：

• 依赖是否已在打包环境中可用
• 如何检测依赖是否存在
• 缺失时的处理方式

## 前置依赖

- **pypdf**：PDF 读写（打包环境中已包含）
- **pptxgenjs**（`npm`）：从零创建 PPT（打包环境中已包含）
- **LibreOffice**（`soffice`）：PDF 转换（打包环境中已包含）
- **pandoc**：文档格式转换（打包环境中已包含）

如果某依赖缺失，请报告依赖问题并停止（不要反复重试）。

2.4 快速参考

提供表格形式的快速命令索引：

## 快速参考

| 任务 | 方法 |
|------|------|
| 读取文件 | `python scripts/read.py file.ext` |
| 编辑文件 | 解压 → 编辑 → 打包（见下方详细流程） |
| 验证输出 | `python scripts/validate.py output.ext` |

2.5 详细使用说明

按功能模块组织，每个模块包含：

• 用途说明
• 输入/输出
• 命令示例
• 注意事项

2.6 常见错误与解决方案

列出常见问题和解决方法：

## 常见问题

### 问题 1：XXX 错误
**原因：** ...
**解决：** ...

---

三、脚本规范

3.1 Python 脚本

命名

• 使用小写下划线命名：create_document.py、parse_content.py
• 避免使用大写或驼峰命名

入口模式

• 首选：接受命令行参数

  import argparse
  
  parser = argparse.ArgumentParser()
  parser.add_argument("input_file", help="输入文件路径")
  parser.add_argument("-o", "--output", default="output.ext", help="输出文件路径")
  args = parser.parse_args()
  

• 备选：接受 stdin 或配置文件

错误处理

• 脚本失败时返回非零退出码
• 错误信息输出到 stderr
• 包含 Python 回溯但不暴露敏感信息

依赖声明

• 仅使用标准库和 SKILL.md 中声明的依赖
• 不要隐式依赖未声明的库

3.2 Node.js 脚本

入口模式

// 接受命令行参数
const args = process.argv.slice(2);
// 或使用 yargs 等工具库

依赖

• 所有 npm 依赖必须在 package.json 中声明
• 优先使用打包环境中已包含的包：
  • docx
  • pptxgenjs
  • jszip

3.3 Shell 脚本（可选）

• 优先使用 Python 或 Node.js 脚本
• Shell 脚本仅用于简单包装或命令串联

---

四、文档编写规范

4.1 代码块

必须指定语言：

# ✅ 正确
```bash
python script.py --input file.pdf

# ✅ 正确
```python
from pypdf import PdfReader

避免无语言代码块：

<!-- ❌ 错误 -->
```
python script.py
```

4.2 命令示例

所有命令行示例必须：

• 使用完整路径或相对于 {skill_dir} 的路径
• 包含输入输出参数说明
• 示例输出（如果有助于理解）

4.3 绝对路径 vs 相对路径

场景	写法
SKILL.md 中描述脚本位置	{skill_dir}/scripts/example.py
模型实际执行命令	cd {skill_dir} && python scripts/example.py
用户文件（不确定位置）	使用传入的参数，示例用 ./input.ext

4.4 链接

引用同技能的其他文档：

详细说明请参阅 [editing.md](editing.md)。

引用外部资源：

PptxGenJS 文档：https://github.com/gitbrent/PptxGenJS

---

五、模型执行指引

5.1 正确的工具调用方式

# 读取帮助信息
> run_shell
> command=python --help

# 执行脚本
> run_shell
> command=cd {skill_dir} && python scripts/example.py --input ./document.ext

5.2 常见任务执行流程

流程 1：读取并分析

1. 使用 `read_file` 工具读取输入文件
2. 使用 `run_shell` 执行分析脚本
3. 根据分析结果规划处理步骤

流程 2：创建新文件

1. 规划文件结构和内容
2. 编写生成脚本（Python 或 Node.js）
3. 使用 `write_file` 保存脚本
4. 使用 `run_shell` 执行脚本
5. 使用 `run_shell` 验证输出

流程 3：编辑现有文件

1. 解包文件（如需要）
2. 使用 `read_file` 读取待编辑部分
3. 使用 `Edit` 工具修改内容
4. 重新打包（如需要）
5. 验证结果

5.3 工作目录处理

重要： run_shell 工具在 Windows 上默认使用 PowerShell，在 POSIX 上使用 bash。

# Windows 路径
cd D:\project\workspace && python script.py

# 使用绝对路径
python D:\project\workspace\scripts\script.py --input "D:\project\workspace\file.ext"

---

六、质量检查清单

完成技能编写后，检查以下各项：

文档检查

• YAML 前言完整（name、description、license、metadata）
• 工具说明正确（使用 run_shell，无错误工具名）
• 前置依赖已列出
• 快速参考表格完整
• 代码块指定了语言
• 命令示例可执行
• 链接指向正确文件

脚本检查

• 所有脚本有入口参数说明
• 脚本在命令行可独立运行
• 错误处理完善
• 依赖已在 SKILL.md 中声明

可用性检查

• 模型能正确识别何时使用此技能
• 模型能正确调用 run_shell 执行命令
• 模型能正确解析脚本输出
• 模型能正确处理错误情况

---

七、常见错误

错误 1：使用不存在的工具名

<!-- ❌ 错误 -->
> 或使用 `execute_shell_command` 的 `cwd` 参数。

<!-- ✅ 正确 -->
> 运行方式：使用 `run_shell` 工具执行命令，例如：
> ```bash
> cd {skill_dir} && python scripts/example.py
> ```

错误 2：命令示例缺少上下文

<!-- ❌ 错误 -->
```bash
python script.py

cd {skill_dir} && python scripts/script.py --input ./document.ext

### 错误 3：依赖声明不完整

```markdown
<!-- ❌ 错误 -->
## 前置依赖
- Python 库（已包含）

<!-- ✅ 正确 -->
## 前置依赖
- **pypdf**：PDF 读写（打包环境中已包含）
- **pandas**：数据分析（打包环境中已包含）
- **openpyxl**：Excel 操作（打包环境中已包含）

错误 4：文档引用错误的文件

<!-- ❌ 错误 -->
详细说明请参阅 [advanced.md](advanced.md)。  <!-- 文件不存在 -->

<!-- ✅ 正确 -->
详细说明请参阅 [reference.md](reference.md)。

---

八、版本规范

版本号格式

使用语义化版本：major.minor.patch

• 1.0.0 - 初始版本
• 1.1.0 - 新增功能
• 1.1.1 - Bug 修复

版本更新记录

在 SKILL.md 末尾添加：

---

## 版本历史

### 1.1.0 (2024-01-15)
- 新增 XXX 功能
- 修复 YYY 问题

### 1.0.0 (2024-01-01)
- 初始版本