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 通常包含以下几个核心部分Skill 元信息包括技能名称、唯一标识符ID、版本、作者、描述和适用场景。这部分帮助快速定位和筛选技能。输入/输出规范明确定义该技能需要什么参数输入以及会返回什么结果输出。格式、类型、是否必需、示例值都需要清晰说明。这是减少歧义的关键。执行步骤与逻辑这是技能的核心。需要用清晰的步骤Step-by-Step描述完成任务的过程。好的步骤会融合决策点例如“如果文件不存在则执行 A 方案否则执行 B 方案”和原理说明“为什么这一步要这样做”。代码示例与模板在专门的代码块中提供可直接使用或修改的代码。通常需要多种语言版本如 Python, JavaScript或针对不同框架如 FastAPI, LangChain的示例。错误处理与边界情况列出执行过程中可能遇到的常见错误、异常并提供处理建议或回退方案。这是体现技能鲁棒性的部分。测试用例提供一组输入输出示例用于验证技能是否被正确实现或理解。相关技能与资源链接到其他相关的 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_pathNone, reference_docxNone): 将 Markdown 文件转换为 Word 文档。 # 1. 验证输入文件 if not os.path.exists(md_file_path): raise FileNotFoundError(fMarkdown 文件未找到: {md_file_path}) # 2. 读取 Markdown 内容 with open(md_file_path, r, encodingutf-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. 错误处理与边界情况问题现象可能原因解决方案报错FileNotFoundError输入的文件路径错误或文件不存在。检查路径拼写使用绝对路径或确认相对路径的当前工作目录。生成的 Word 文档无样式或样式混乱1. 未正确映射 HTML 标签到 Word 样式。2. 模板文件损坏或样式名不对。1. 调试样式映射代码确保paragraph.style doc.styles[StyleName]赋值成功。2. 在 Word 中打开模板文件查看其有效的样式名称。图片未插入图片路径是相对路径且相对于 Word 文档位置无法找到。将图片路径转换为绝对路径或在插入前将图片下载到临时目录。对于网络图片使用requests库下载。代码块失去高亮和等宽格式python-docx默认不识别代码高亮。为代码段落手动设置等宽字体如Consolas、背景色和缩进。可以考虑使用pygments生成带样式的 HTML 再插入但这更复杂。转换大型文件速度慢文档元素过多或图片下载耗时。对图片处理加入异步操作或缓存。对于纯文本性能瓶颈通常在BeautifulSoup解析可尝试优化遍历逻辑。5. 测试用例输入 (markdown_file_path)预期输出./simple.md(内容仅含# 标题和一段文字)生成simple.docx包含一个“标题1”样式的标题和正常段落。./with_table.md(内容包含 Markdown 表格)生成with_table.docx包含一个格式正确的 Word 表格。./with_image.md(内容包含)生成with_image.docx图片被成功嵌入文档中。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_typestructured-chat, verboseTrue) # 现在你可以用自然语言指挥Agent了“请把我的周报Markdown转换成Word。”通过这种方式Skill 从一个静态文档变成了 AI Agent 可以自主调用的一个可靠能力。description字段至关重要它需要精炼地概括技能功能以便 Agent 的 LLM 大脑能判断在什么情况下调用它。4.3 作为低代码平台如 Dify, Coze的工作流节点在 Dify 或 Coze 这类平台上你可以创建一个“代码节点”或“自定义工具节点”。将 Skill 文档中的核心代码逻辑如第3节的Python函数填入该节点。然后在平台的工作流画布上定义一个“输入”节点接收用户上传的 Markdown 文件或路径。连接到你创建的“Markdown转Word”代码节点。再连接一个“输出”节点将生成的 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文件里面用表格列出所有可用的 SkillSkill ID名称描述作者版本doc_convert_md_to_word_v1Markdown转Word转换MD文件为格式化的.docx文档yourname1.0.0data_fetch_api_v1通用API数据获取带错误重试和速率限制的HTTP GET请求yourname1.2.0text_summarize_llm_v1LLM文本摘要调用OpenAI/Claude API对长文本进行摘要yourname0.9.0更高级的做法是提供一个简单的索引文件如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 时总是因为环境依赖问题失败。排查这是集成中最常见的问题。不要假设运行环境和你本地开发环境一致。解决方案容器化将 Skill 及其依赖打包成 Docker 镜像。这是最彻底的解决方案确保环境一致性。显式声明在 Skill 文档最顶部用醒目的方式列出所有外部系统依赖如需要安装pandoc命令行工具和Python 库依赖requirements.txt。提供安装脚本附上一个setup.sh或install_deps.py脚本让调用者一键安装依赖。问题Skill 执行成功但结果不符合预期如 Word 样式错乱。排查这通常是“环境差异”或“边界情况”导致的。调试流程隔离测试创建一个最小化的、能复现问题的输入文件minimal.md在你的 Skill 代码中运行。增加日志在代码的关键节点如样式映射前后、文件保存前打印出中间状态如当前处理的元素类型、应用的样式名。对比验证手动用其他工具如pandoc处理同一个minimal.md对比输出结果看问题是出在你的逻辑上还是库的固有限制上。查阅依赖库的 Issue前往python-docx或markdown的 GitHub Issues 页面搜索类似问题很可能你遇到的坑别人已经踩过并有解决方案。6.3 性能与优化问题转换一个包含大量图片的 Markdown 文件时速度非常慢。分析瓶颈通常在于网络下载如果是网络图片或图片处理调整大小、格式转换。优化策略并行下载对于多张网络图片使用asyncio或concurrent.futures进行异步或并发下载。缓存机制如果同一张图片可能在多个 Skill 执行中被用到考虑在本地建立缓存避免重复下载。懒加载/占位符对于超大型文档可以考虑第一版转换时不处理图片只插入占位符和图片链接后续再单独处理图片插入。进度反馈对于耗时操作Skill 应该提供进度反馈机制例如向标准输出打印“正在处理第 X/ Y 张图片...”这对于被集成到交互式 AI 对话中时尤为重要。编写和维护 OpenCode Skills 是一个持续迭代的过程。从最初的一个简单想法和代码片段到一份结构清晰的文档再到一个能在各种 AI 环境中稳定运行的可靠工具每一步都需要细致的思考和大量的实践。 OpenCode Skills：用结构化文档教会AI执行编程任务
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 通常包含以下几个核心部分Skill 元信息包括技能名称、唯一标识符ID、版本、作者、描述和适用场景。这部分帮助快速定位和筛选技能。输入/输出规范明确定义该技能需要什么参数输入以及会返回什么结果输出。格式、类型、是否必需、示例值都需要清晰说明。这是减少歧义的关键。执行步骤与逻辑这是技能的核心。需要用清晰的步骤Step-by-Step描述完成任务的过程。好的步骤会融合决策点例如“如果文件不存在则执行 A 方案否则执行 B 方案”和原理说明“为什么这一步要这样做”。代码示例与模板在专门的代码块中提供可直接使用或修改的代码。通常需要多种语言版本如 Python, JavaScript或针对不同框架如 FastAPI, LangChain的示例。错误处理与边界情况列出执行过程中可能遇到的常见错误、异常并提供处理建议或回退方案。这是体现技能鲁棒性的部分。测试用例提供一组输入输出示例用于验证技能是否被正确实现或理解。相关技能与资源链接到其他相关的 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_pathNone, reference_docxNone): 将 Markdown 文件转换为 Word 文档。 # 1. 验证输入文件 if not os.path.exists(md_file_path): raise FileNotFoundError(fMarkdown 文件未找到: {md_file_path}) # 2. 读取 Markdown 内容 with open(md_file_path, r, encodingutf-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. 错误处理与边界情况问题现象可能原因解决方案报错FileNotFoundError输入的文件路径错误或文件不存在。检查路径拼写使用绝对路径或确认相对路径的当前工作目录。生成的 Word 文档无样式或样式混乱1. 未正确映射 HTML 标签到 Word 样式。2. 模板文件损坏或样式名不对。1. 调试样式映射代码确保paragraph.style doc.styles[StyleName]赋值成功。2. 在 Word 中打开模板文件查看其有效的样式名称。图片未插入图片路径是相对路径且相对于 Word 文档位置无法找到。将图片路径转换为绝对路径或在插入前将图片下载到临时目录。对于网络图片使用requests库下载。代码块失去高亮和等宽格式python-docx默认不识别代码高亮。为代码段落手动设置等宽字体如Consolas、背景色和缩进。可以考虑使用pygments生成带样式的 HTML 再插入但这更复杂。转换大型文件速度慢文档元素过多或图片下载耗时。对图片处理加入异步操作或缓存。对于纯文本性能瓶颈通常在BeautifulSoup解析可尝试优化遍历逻辑。5. 测试用例输入 (markdown_file_path)预期输出./simple.md(内容仅含# 标题和一段文字)生成simple.docx包含一个“标题1”样式的标题和正常段落。./with_table.md(内容包含 Markdown 表格)生成with_table.docx包含一个格式正确的 Word 表格。./with_image.md(内容包含)生成with_image.docx图片被成功嵌入文档中。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_typestructured-chat, verboseTrue) # 现在你可以用自然语言指挥Agent了“请把我的周报Markdown转换成Word。”通过这种方式Skill 从一个静态文档变成了 AI Agent 可以自主调用的一个可靠能力。description字段至关重要它需要精炼地概括技能功能以便 Agent 的 LLM 大脑能判断在什么情况下调用它。4.3 作为低代码平台如 Dify, Coze的工作流节点在 Dify 或 Coze 这类平台上你可以创建一个“代码节点”或“自定义工具节点”。将 Skill 文档中的核心代码逻辑如第3节的Python函数填入该节点。然后在平台的工作流画布上定义一个“输入”节点接收用户上传的 Markdown 文件或路径。连接到你创建的“Markdown转Word”代码节点。再连接一个“输出”节点将生成的 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文件里面用表格列出所有可用的 SkillSkill ID名称描述作者版本doc_convert_md_to_word_v1Markdown转Word转换MD文件为格式化的.docx文档yourname1.0.0data_fetch_api_v1通用API数据获取带错误重试和速率限制的HTTP GET请求yourname1.2.0text_summarize_llm_v1LLM文本摘要调用OpenAI/Claude API对长文本进行摘要yourname0.9.0更高级的做法是提供一个简单的索引文件如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 时总是因为环境依赖问题失败。排查这是集成中最常见的问题。不要假设运行环境和你本地开发环境一致。解决方案容器化将 Skill 及其依赖打包成 Docker 镜像。这是最彻底的解决方案确保环境一致性。显式声明在 Skill 文档最顶部用醒目的方式列出所有外部系统依赖如需要安装pandoc命令行工具和Python 库依赖requirements.txt。提供安装脚本附上一个setup.sh或install_deps.py脚本让调用者一键安装依赖。问题Skill 执行成功但结果不符合预期如 Word 样式错乱。排查这通常是“环境差异”或“边界情况”导致的。调试流程隔离测试创建一个最小化的、能复现问题的输入文件minimal.md在你的 Skill 代码中运行。增加日志在代码的关键节点如样式映射前后、文件保存前打印出中间状态如当前处理的元素类型、应用的样式名。对比验证手动用其他工具如pandoc处理同一个minimal.md对比输出结果看问题是出在你的逻辑上还是库的固有限制上。查阅依赖库的 Issue前往python-docx或markdown的 GitHub Issues 页面搜索类似问题很可能你遇到的坑别人已经踩过并有解决方案。6.3 性能与优化问题转换一个包含大量图片的 Markdown 文件时速度非常慢。分析瓶颈通常在于网络下载如果是网络图片或图片处理调整大小、格式转换。优化策略并行下载对于多张网络图片使用asyncio或concurrent.futures进行异步或并发下载。缓存机制如果同一张图片可能在多个 Skill 执行中被用到考虑在本地建立缓存避免重复下载。懒加载/占位符对于超大型文档可以考虑第一版转换时不处理图片只插入占位符和图片链接后续再单独处理图片插入。进度反馈对于耗时操作Skill 应该提供进度反馈机制例如向标准输出打印“正在处理第 X/ Y 张图片...”这对于被集成到交互式 AI 对话中时尤为重要。编写和维护 OpenCode Skills 是一个持续迭代的过程。从最初的一个简单想法和代码片段到一份结构清晰的文档再到一个能在各种 AI 环境中稳定运行的可靠工具每一步都需要细致的思考和大量的实践。