1. 项目概述：OpenCode Skills 文档是什么？

最近在开发者社区里，OpenCode Skills 这个提法开始频繁出现，尤其是在讨论如何让大型语言模型（LLM）更好地理解和执行特定任务时。简单来说，OpenCode Skills 文档是一套用 Markdown 格式编写的、结构化的“技能说明书”。它的核心目标，是教会一个 AI 助手（比如 Claude、GPTs 或各类 AI Agent）如何正确地完成一项具体的编程或技术任务，而不仅仅是泛泛地回答一个问题。

你可以把它理解为一个超级详细的“菜谱”或者“标准作业程序（SOP）”。传统的代码片段或函数文档告诉你“这个工具怎么用”，而一个 Skill 文档则告诉 AI “为了达成某个目标，你应该遵循怎样的思考路径和操作步骤”。例如，一个“解析 JSON 配置文件并验证”的 Skill，不仅会给出代码，还会说明先读取文件、再校验结构、最后处理异常的逻辑链条，甚至包括常见的错误模式和回退方案。这背后的驱动力很明显：随着 LLM 被深度集成到 IDE（如 VS Code 的 Copilot）、自动化工作流（如 Dify、Coze）和各类 AI Agent 框架中，我们需要一种更精确、更可靠的方式来定义 AI 的能力边界和行为模式，减少其“幻觉”和随机性，OpenCode Skills 正是在这种需求下应运而生的一种实践方案。

2. 核心设计思路：为什么是 Markdown + 结构化？

2.1 选择 Markdown 作为载体

为什么 Skill 文档普遍采用 Markdown 格式？这并非偶然。首先，Markdown 具有极佳的可读性和可写性。开发者无需学习复杂的标记语言，用简单的#、-、``` 就能构建出层次清晰的文档，这大大降低了创作和维护 Skill 的门槛。其次，Markdown 是 LLM 的“母语”之一。在训练过程中，模型接触了大量的 GitHub README、技术博客和文档，它们很多都是 Markdown 格式。因此，LLM 对解析和理解 Markdown 的结构（如标题、列表、代码块）有着天然的优势，能更准确地提取其中的指令、步骤和代码示例。

最后，Markdown 兼具人机友好性。对人来说，它是一份清晰的指南；对机器（LLM）来说，它是一份结构化的提示词（Prompt）或上下文。这种双重属性使得 Skill 文档既能用于人工查阅学习，也能直接作为上下文注入到 LLM 的对话中，指导其行为。相比之下，JSON 或 YAML 等纯数据格式对人不够友好，而纯自然语言描述又对机器不够结构化。

2.2 Skill 文档的核心结构剖析

一个典型的、有效的 OpenCode Skill 文档，其结构远不止是随意写几点说明。它需要精心设计，以确保信息传递的准确性和完整性。根据社区常见的实践（如SKILL.md模板），一个完整的 Skill 通常包含以下几个核心部分：

1. Skill 元信息：包括技能名称、唯一标识符（ID）、版本、作者、描述和适用场景。这部分帮助快速定位和筛选技能。
2. 输入/输出规范：明确定义该技能需要什么参数（输入），以及会返回什么结果（输出）。格式、类型、是否必需、示例值都需要清晰说明。这是减少歧义的关键。
3. 执行步骤与逻辑：这是技能的核心。需要用清晰的步骤（Step-by-Step）描述完成任务的过程。好的步骤会融合决策点（例如：“如果文件不存在，则执行 A 方案；否则执行 B 方案”）和原理说明（“为什么这一步要这样做”）。
4. 代码示例与模板：在专门的代码块中提供可直接使用或修改的代码。通常需要多种语言版本（如 Python, JavaScript）或针对不同框架（如 FastAPI, LangChain）的示例。
5. 错误处理与边界情况：列出执行过程中可能遇到的常见错误、异常，并提供处理建议或回退方案。这是体现技能鲁棒性的部分。
6. 测试用例：提供一组输入输出示例，用于验证技能是否被正确实现或理解。
7. 相关技能与资源：链接到其他相关的 Skill 文档或外部参考资料，形成知识网络。

注意：不要将 Skill 文档写成 API 文档的翻版。API 文档侧重接口调用，而 Skill 文档侧重目标导向的任务流程。例如，一个“用户注册”的 Skill，会涵盖前端表单验证、后端 API 调用、数据库写入、发送欢迎邮件等一连串动作，而不仅仅是一个/api/register的端点说明。

3. 从零开始编写你的第一个 Skill 文档

理论说得再多，不如动手写一个。让我们以一个实用的技能为例：“将 Markdown 文件内容转换为格式规范的 Word 文档”。这个需求在撰写报告、交付文档时非常常见，我们将以此构建一个完整的 Skill。

3.1 定义技能蓝图

在动笔写 Markdown 之前，先花时间进行设计。明确以下几个问题：

• 核心目标：用户提供一个 Markdown 文件路径，最终得到一个排版美观的.docx文件。
• 用户是谁：可能是开发者、技术写作者或使用 AI 助手自动化文档流程的人。
• 主要挑战：Markdown 的简单语法（如#）如何对应到 Word 的复杂样式（标题1、字体、间距）？图片和表格如何处理？代码块如何保持高亮？

基于此，我们确定技能需要处理：文件读取、语法解析、样式映射、文档生成和错误处理。

3.2 撰写详细的 Skill 文档

下面是一个简化但结构完整的convert_markdown_to_word.md示例：

# Skill: Convert Markdown to Formatted Word Document **Skill ID:** `doc_convert_md_to_word_v1` **Author:** [Your Name] **Version:** 1.0.0 **Description:** 将指定的 Markdown 文件转换为格式规范、样式美观的 Microsoft Word (.docx) 文档。支持标题、列表、代码块、表格和图片等常见元素。 ## 1. 输入/输出规范 ### 输入 (Input) * `markdown_file_path`: (字符串, 必需) 待转换的 Markdown 文件的绝对或相对路径。 * 示例: `"./project_report.md"` * `output_docx_path`: (字符串, 可选) 生成的 Word 文档路径。若未提供，则在原 Markdown 文件同目录下生成同名 `.docx` 文件。 * 示例: `"./output/report.docx"` * `reference_docx`: (字符串, 可选) 作为样式参考的 Word 模板文件路径。用于继承特定的标题、正文等样式。 * 示例: `"./templates/corporate_template.docx"` ### 输出 (Output) * 主要输出：在指定路径成功生成 `.docx` 文件。 * 控制台输出：转换过程的成功或错误日志信息。 ## 2. 执行步骤与逻辑 ### 2.1 环境准备与依赖检查 1. **确认运行环境**：本技能主要适用于 Python 环境。确保环境中已安装 Python（建议 3.7+）。 2. **安装核心库**：本技能依赖于 `python-docx` 库来处理 Word 文档生成，以及 `markdown` 库进行基础解析。可通过 pip 安装： ```bash pip install python-docx markdown ``` 3. **可选库**：如果需要更高级的 Markdown 特性支持（如表格、代码高亮），可以考虑 `markdown-extensions` 或 `pygments`（用于代码高亮）。 ### 2.2 核心转换流程 1. **读取与验证**： * 读取 `markdown_file_path` 指定的文件。 * 检查文件是否存在、是否可读、扩展名是否为 `.md` 或 `.markdown`。如果失败，立即抛出清晰的文件错误。 2. **解析 Markdown**： * 使用 `markdown` 库将文件内容转换为 HTML。这是关键一步，因为 `python-docx` 无法直接理解 Markdown，但可以添加 HTML 格式的文本。 * 启用必要的扩展，例如 `extra`（用于表格）、`codehilite`（用于代码高亮）。 ```python import markdown html_content = markdown.markdown(md_text, extensions=['extra', 'codehilite']) ``` 3. **创建 Word 文档并应用样式**： * 初始化一个 `docx.Document` 对象。 * 如果提供了 `reference_docx`，则使用该模板初始化文档，以继承样式。 * 定义映射规则：将 HTML 标签映射到 Word 样式对象。例如： * `<h1>` -> `document.styles['Heading 1']` * `<p>` -> `document.styles['Normal']` * `<code>` -> 应用等宽字体和背景色。 4. **遍历与写入**： * 使用 `BeautifulSoup`（需额外安装 `bs4`）解析生成的 HTML，遍历每个元素。 * 根据元素类型（标题、段落、列表项、代码块、表格行），调用 `document.add_paragraph()` 或 `document.add_table()` 等方法，并应用上一步定义的样式。 * **处理图片**：提取 `<img>` 标签的 `src` 路径，使用 `document.add_picture()` 插入图片。注意处理相对路径和网络 URL（需要下载）。 5. **保存文档**： * 根据 `output_docx_path` 参数或默认规则生成输出路径。 * 调用 `document.save(output_path)`。 ## 3. 代码示例 以下是一个完整的 Python 函数示例，实现了上述核心流程： ```python import os import markdown from docx import Document from docx.shared import Pt, RGBColor from bs4 import BeautifulSoup import requests from urllib.parse import urlparse def convert_markdown_to_word(md_file_path, output_docx_path=None, reference_docx=None): """ 将 Markdown 文件转换为 Word 文档。 """ # 1. 验证输入文件 if not os.path.exists(md_file_path): raise FileNotFoundError(f"Markdown 文件未找到: {md_file_path}") # 2. 读取 Markdown 内容 with open(md_file_path, 'r', encoding='utf-8') as f: md_text = f.read() # 3. 转换为 HTML html_content = markdown.markdown(md_text, extensions=['extra', 'tables', 'codehilite']) # 4. 创建或基于模板创建 Word 文档 if reference_docx and os.path.exists(reference_docx): doc = Document(reference_docx) else: doc = Document() # 5. 解析 HTML 并添加到文档 soup = BeautifulSoup(html_content, 'html.parser') # ... (详细的遍历添加逻辑，因篇幅省略，需处理 h1-h6, p, ul/li, pre/code, table 等) # 核心是：根据 tag.name 判断类型，创建对应的 paragraph 并设置 style。 # 6. 确定输出路径并保存 if not output_docx_path: base_name = os.path.splitext(md_file_path)[0] output_docx_path = base_name + '.docx' doc.save(output_docx_path) print(f"转换成功！文档已保存至: {output_docx_path}") return output_docx_path # 使用示例 if __name__ == "__main__": convert_markdown_to_word("./README.md", "./output/README.docx")

4. 错误处理与边界情况

5. 测试用例

6. 相关技能与资源

• Skill: 从网页爬取内容并生成摘要-> 可与此技能串联，实现“爬取->整理为Markdown->输出为Word报告”的流水线。
• python-docx 官方文档: https://python-docx.readthedocs.io/
• Python-Markdown 扩展列表: https://python-markdown.github.io/extensions/

### 3.3 实操心得与关键细节 在编写和实现这类 Skill 时，有几个细节决定了成败： 1. **路径处理是万恶之源**：在 Skill 中，文件路径的处理必须格外小心。特别是当 Skill 被 AI Agent 在未知的当前工作目录下调用时。**最佳实践是，在 Skill 文档中明确要求输入“绝对路径”，或者在代码伊始使用 `os.path.abspath()` 进行标准化处理**。相对路径是很多“文件找不到”错误的根源。 2. **依赖管理要明确**：Skill 文档必须清晰列出所有外部依赖库及其安装命令（如 `pip install xyz`）。对于复杂的依赖，建议提供一个 `requirements.txt` 文件示例。这能帮助 AI 或用户在执行前准备好环境。 3. **样式映射的“黑盒”**：`python-docx` 的样式系统对于新手有些晦涩。一个实用的技巧是：先手动在 Word 里创建一个包含你理想中“标题1”、“代码块”等样式的文档，然后用 `python-docx` 打开它，打印出所有样式名 `[style.name for style in doc.styles]`，这样你就知道在代码里应该引用什么字符串了。 4. **为 AI 设计，而非为人**：记住，这份文档的最终读者很可能是一个 LLM。因此，描述要**极度结构化，避免歧义**。多使用编号列表、表格来呈现条件和选项。在代码示例中，关键步骤上方用注释 `# 关键步骤：验证文件是否存在` 比纯代码更能引导 AI 关注重点。 ## 4. 高级应用：在 AI Agent 与工作流中集成 Skill 写好 Skill 文档后，它的价值在于被调用和执行。现在，我们看看如何将它融入现代开发与自动化流程。 ### 4.1 在 AI 聊天助手（如 Claude、ChatGPT）中直接使用 对于支持长上下文和文件上传的 LLM（如 Claude 3， GPT-4），你可以直接将写好的 `SKILL.md` 文件作为对话背景上传。然后给出指令： > “请根据我提供的《Convert Markdown to Word》技能文档，帮我将 `~/projects/report.md` 这个文件转换成 Word 格式。如果遇到图片，请尝试下载并嵌入。” 一个能力足够的 LLM 能够阅读并理解整个 Skill 的步骤、输入输出和代码，然后模拟或直接生成执行该技能所需的代码或操作序列。这相当于你为 AI 临时加载了一个“插件”或“知识库”。 ### 4.2 集成到 AI Agent 框架（如 LangChain, LangGraph） 在更复杂的自动化场景中，Skill 可以封装成一个可复用的 **Tool** 或 **Agent**。以 LangChain 为例： ```python from langchain.tools import BaseTool from pydantic import BaseModel, Field import subprocess import sys class MarkdownToWordInput(BaseModel): """输入参数模型，严格对应Skill的Input规范。""" markdown_file_path: str = Field(..., description="待转换的Markdown文件路径") output_docx_path: str = Field(None, description="输出的Word文件路径，可选") class MarkdownToWordTool(BaseTool): name = "markdown_to_word_converter" description = "将Markdown文件转换为格式规范的Word文档。技能ID: doc_convert_md_to_word_v1" args_schema = MarkdownToWordInput def _run(self, markdown_file_path: str, output_docx_path: str = None): """执行技能的核心逻辑。这里可以调用我们之前写好的Python函数。""" # 这里可以封装第三节中的 convert_markdown_to_word 函数 try: result_path = convert_markdown_to_word(markdown_file_path, output_docx_path) return f"转换成功！文档已生成: {result_path}" except Exception as e: return f"转换失败: {str(e)}" async def _arun(self, *args, **kwargs): """异步版本（如果需要）。""" raise NotImplementedError("本工具暂不支持异步调用") # 将工具注入到Agent中 tools = [MarkdownToWordTool()] agent = initialize_agent(tools, llm, agent_type="structured-chat", verbose=True) # 现在，你可以用自然语言指挥Agent了：“请把我的周报Markdown转换成Word。”

通过这种方式，Skill 从一个静态文档，变成了 AI Agent 可以自主调用的一个可靠能力。description字段至关重要，它需要精炼地概括技能功能，以便 Agent 的 LLM 大脑能判断在什么情况下调用它。

4.3 作为低代码平台（如 Dify, Coze）的工作流节点

在 Dify 或 Coze 这类平台上，你可以创建一个“代码节点”或“自定义工具节点”。将 Skill 文档中的核心代码逻辑（如第3节的Python函数）填入该节点。然后，在平台的工作流画布上：

1. 定义一个“输入”节点，接收用户上传的 Markdown 文件或路径。
2. 连接到你创建的“Markdown转Word”代码节点。
3. 再连接一个“输出”节点，将生成的 Word 文件返回给用户。

这样，你就构建了一个可视化的、可重复使用的文档转换流水线。Skill 文档在这里起到了设计说明书和代码实现的双重作用。

避坑指南：在低代码平台集成时，最大的挑战是环境隔离。确保你的代码节点所运行的环境（如 Docker 容器）已经安装了python-docx,markdown等所有依赖。通常需要在节点配置中指定requirements.txt或使用预构建的包含依赖的镜像。

5. Skill 的维护、共享与生态构建

一个孤立的 Skill 价值有限，但当 Skill 能够被方便地发现、使用和组合时，就能产生巨大的网络效应。

5.1 版本控制与迭代

Skill 文档应该像代码一样被管理。使用 Git 进行版本控制是一个必然选择。

• 仓库结构：可以建立一个专门的skills仓库，每个 Skill 一个独立的目录，目录内包含SKILL.md（主文档）、example_input.md（示例输入）、test_skill.py（测试脚本）以及可选的requirements.txt。
• 版本号：在 Skill 元信息中遵循语义化版本控制（如v1.0.0）。当修复错误时递增修订号（v1.0.1），增加向后兼容的功能时递增次版本号（v1.1.0），发生不兼容的变更时递增主版本号（v2.0.0）。
• 变更日志：在 Skill 文档末尾或单独的CHANGELOG.md中记录每次重要的变更，说明更新内容和对用户的影响。

5.2 创建可发现的 Skill 仓库

为了让其他人能用到你的 Skill，你需要提供一个“技能目录”。这可以是一个简单的README.md文件，里面用表格列出所有可用的 Skill：

更高级的做法是提供一个简单的索引文件（如index.json），方便其他工具或平台自动爬取和集成。

5.3 组合技能：构建复杂工作流

Skill 的真正威力在于组合。单个 Skill 可能只做一件事，但多个 Skill 串联起来就能完成复杂项目。

• 顺序组合：Skill A的输出作为Skill B的输入。例如，抓取网页内容->提取正文并清洗->转换为Markdown->(使用本Skill)转换为Word->发送邮件。这可以在脚本中顺序调用，也可以在 LangGraph 或 Dify Workflow 中通过连线实现。
• 条件组合：根据Skill A的执行结果（成功/失败，或某种输出状态），决定下一步调用Skill B还是Skill C。这需要 Skill 有明确的成功/失败状态返回。
• 经验分享：在设计可组合的 Skill 时，输入输出接口的标准化至关重要。尽量使用简单、通用的数据类型（字符串、数字、列表、字典）。如果输出是复杂对象，考虑将其序列化为 JSON 字符串。这样，下游 Skill 才能更容易地解析和使用你的输出。

6. 常见问题与深度排查

在实际编写和使用 Skill 的过程中，你会遇到各种问题。以下是一些典型问题及其解决思路。

6.1 Skill 文档相关

问题：LLM 似乎没有完全理解或遵循我的 Skill 文档步骤。

• 排查：首先检查文档的结构清晰度。LLM 对模糊的、充满可能性的自然语言描述理解不佳。确保你的“执行步骤”部分使用了明确的编号列表（1. 2. 3.），并且每个步骤都是一个具体的、可执行的动作。避免使用“可以”、“可能”、“建议”这类词汇，改用“必须”、“将”、“然后”等指令性词汇。
• 技巧：在关键决策点，使用“如果...那么...否则...”的格式。例如：“如果文件扩展名不是.md，那么记录警告日志并尝试继续；否则，正常处理。” 这能极大提高 LLM 对逻辑分支的理解。

问题：Skill 文档太长，超出了 LLM 的上下文窗口。

• 排查：将超长 Skill 拆分为多个子 Skill。例如，一个“完整数据预处理” Skill 可以拆分为“数据清洗”、“特征编码”、“处理缺失值”等独立但关联的子 Skill。在主 Skill 文档中，只描述子 Skill 的调用逻辑和组合方式。
• 技巧：利用 LLM 的摘要能力。为长文档编写一个简短的“执行摘要”放在开头，概括核心目标、输入、输出和最关键的前3个步骤。这样即使上下文被截断，LLM 也能抓住重点。

6.2 代码实现与集成相关

问题：在 AI Agent 中调用 Skill 时，总是因为环境依赖问题失败。

• 排查：这是集成中最常见的问题。不要假设运行环境和你本地开发环境一致。
• 解决方案：
  1. 容器化：将 Skill 及其依赖打包成 Docker 镜像。这是最彻底的解决方案，确保环境一致性。
  2. 显式声明：在 Skill 文档最顶部，用醒目的方式列出所有外部系统依赖（如需要安装pandoc命令行工具）和Python 库依赖（requirements.txt）。
  3. 提供安装脚本：附上一个setup.sh或install_deps.py脚本，让调用者一键安装依赖。

问题：Skill 执行成功，但结果不符合预期（如 Word 样式错乱）。

• 排查：这通常是“环境差异”或“边界情况”导致的。
• 调试流程：
  1. 隔离测试：创建一个最小化的、能复现问题的输入文件（minimal.md），在你的 Skill 代码中运行。
  2. 增加日志：在代码的关键节点（如样式映射前后、文件保存前）打印出中间状态（如当前处理的元素类型、应用的样式名）。
  3. 对比验证：手动用其他工具（如pandoc）处理同一个minimal.md，对比输出结果，看问题是出在你的逻辑上，还是库的固有限制上。
  4. 查阅依赖库的 Issue：前往python-docx或markdown的 GitHub Issues 页面搜索类似问题，很可能你遇到的坑别人已经踩过并有解决方案。

6.3 性能与优化

问题：转换一个包含大量图片的 Markdown 文件时速度非常慢。

• 分析：瓶颈通常在于网络下载（如果是网络图片）或图片处理（调整大小、格式转换）。
• 优化策略：
  1. 并行下载：对于多张网络图片，使用asyncio或concurrent.futures进行异步或并发下载。
  2. 缓存机制：如果同一张图片可能在多个 Skill 执行中被用到，考虑在本地建立缓存，避免重复下载。
  3. 懒加载/占位符：对于超大型文档，可以考虑第一版转换时不处理图片，只插入占位符和图片链接，后续再单独处理图片插入。
  4. 进度反馈：对于耗时操作，Skill 应该提供进度反馈机制，例如向标准输出打印“正在处理第 X/ Y 张图片...”，这对于被集成到交互式 AI 对话中时尤为重要。

编写和维护 OpenCode Skills 是一个持续迭代的过程。从最初的一个简单想法和代码片段，到一份结构清晰的文档，再到一个能在各种 AI 环境中稳定运行的可靠工具，每一步都需要细致的思考和大量的实践。