OpenCode Skills：用结构化文档提升LLM代码生成效率的工程实践-平芜编程栈

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

最近在开发者社区里，一个叫“OpenCode Skills”的概念开始被频繁提及。乍一看，它像是一个新的工具或框架，但深入了解后你会发现，它更像是一种约定，一种旨在提升大型语言模型（LLM）与代码协同工作效率的“元方法”。简单来说，OpenCode Skills 文档的核心，就是一份用特定格式（通常是 Markdown）编写的、结构化的“技能说明书”。

想象一下，你有一个能力超强的AI助手，它精通编程，但你需要告诉它：“嘿，请帮我写一个函数，它要能解析特定格式的日志文件，提取错误码和时间戳，并按照严重程度排序。” 如果你只是口头描述，AI可能因为理解偏差而写出不符合你预期的代码。而 OpenCode Skills 的思路是，将这个需求封装成一个标准的、可复用的“技能”。你为这个技能编写一份详细的文档，描述它的功能、输入参数、输出格式、使用示例，甚至包括边界情况和错误处理。这份文档本身是机器可读的（Markdown 易于解析），同时也是人可读的（便于开发者理解和维护）。

那么，它具体解决了什么问题？在 LLM 编程辅助、AI Agent 开发乃至低代码平台中，我们常常面临“提示词工程”的困境：每次都要重新描述复杂任务，上下文窗口有限导致长对话后AI忘记早期约定，团队间难以共享和复用最佳实践。OpenCode Skills 文档通过将任务标准化、模块化，旨在实现“一次定义，处处调用”。它适合所有希望通过结构化方式提升与AI协作效率的开发者，无论是想为自己构建一个私人代码助手库的独立开发者，还是希望团队能统一、高效地使用AI进行代码生成的工程团队。

2. 核心设计理念与价值拆解

2.1 从“临时对话”到“持久化技能库”的范式转变

传统的 LLM 代码生成模式是线性的、临时的。你提出一个问题，AI 生成一段代码，对话结束，这个“知识”就消失了。下次遇到类似问题，你需要重新组织语言，甚至可能因为描述不同而得到质量参差不齐的结果。OpenCode Skills 倡导的是一种根本性的转变：将离散的、临时的提示词（Prompt），升级为结构化的、可版本控制的、可组合的“技能”（Skill）。

这种转变带来了几个核心价值：

可复用性：一个定义良好的“数据验证”技能，可以在前端表单验证、后端API入参校验、数据库写入前检查等多个场景中被同一个AI或不同的AI调用，无需重复描述规则。
可维护性：当业务逻辑变更时，你只需要更新中心化的 Skill 文档，所有引用该技能的AI交互行为会自动同步更新，避免了“散弹式修改”的问题。
可测试性：一个标准的 Skill 文档天然包含了输入输出描述和示例，这为编写针对AI生成代码的单元测试或集成测试提供了清晰的依据。
可协作性：Skill 文档作为文本文件（如SKILL.md），可以轻松地通过 Git 进行版本管理、代码审查和团队共享，促进了最佳实践的沉淀和传播。

2.2 与现有技术生态的融合：Markdown, LLM 与工作流

OpenCode Skills 文档并非要创造一个全新的技术栈，而是巧妙地利用了现有成熟生态：

Markdown 作为载体：选择 Markdown 是极具智慧的。它足够简单，任何开发者都能立刻上手编写；它结构清晰，通过标题、列表、代码块等元素能很好地组织信息；它既是给人看的文档，也因其纯文本和一定结构性，易于被程序（包括LLM自身）解析和提取关键信息。网络上热传的skill.md模板正是社区探索这种结构化约定的体现。
LLM 作为执行引擎：无论是 OpenAI GPT, Claude, 还是开源的 Llama、DeepSeek Coder，它们都是技能的“执行者”。一份编写良好的 Skill 文档，本质上是一份超级详细的“系统提示词”（System Prompt），它指导 LLM 在特定上下文中如何思考、如何行动。这与ai agent skill llm等概念高度契合，Skill 就是 Agent 可以调用的标准化工具。
集成到开发工作流：Skill 文档可以集成到 IDE（如 VSCode 通过插件）、CI/CD 管道、或者像dify workflow,langchain这样的 LLM 应用框架中。例如，在dify中，你可以设计一个工作流，其中一个节点就是“调用‘生成API文档’技能”，将LLM的输出（Markdown格式）通过另一个节点“保存到一个word文档中”，实现自动化。

注意：不要将 OpenCode Skills 与某个特定的叫“OpenCode”的软件混淆。根据网络上的讨论，opencode可能是一个具体的工具名或命令行工具，有时会遇到“无法将‘opencode’项识别为 cmdlet...”这样的错误。但“OpenCode Skills”更偏向于一种方法论或规范。你可以用任何你喜欢的工具（如 VS Code 配合 Markdown 插件）来创建和管理这些 Skill 文档。

3. 如何编写一份高质量的 OpenCode Skills 文档

一份有效的 Skill 文档，其结构需要兼顾人类读者的理解效率和机器（LLM）的解析效率。虽然没有绝对统一的官方标准，但社区实践已经形成了一些最佳实践模板。下面我将拆解一个通用且高效的SKILL.md模板，并解释每个部分为何重要。

3.1 文档结构详解与核心字段说明

一个完整的 Skill 文档通常包含以下部分，你可以根据技能的复杂程度进行增减：

# 技能名称：[清晰、动词开头的名称，如 `Parse_Structured_Log`] **技能ID**: `unique_skill_id` (可选，用于程序化调用时索引) **版本**: v1.0.0 **维护者**: [你的名字/团队] **最后更新**: 2023-10-27 ## 1. 技能描述 用一两句话清晰说明这个技能是做什么的。这是给人类和AI的第一印象。 *例如：本技能用于解析符合特定格式的应用程序日志字符串，提取关键字段（时间戳、日志级别、错误码、消息），并返回结构化的JSON对象。* ## 2. 核心功能 - 功能点1：例如，支持多种时间戳格式（ISO 8601, Unix timestamp）。 - 功能点2：例如，内置常见日志级别（INFO, WARN, ERROR, DEBUG）的映射和过滤。 - 功能点3：例如，能处理多行日志消息（以缩进或特定前缀延续的日志行）。 ## 3. 输入/输出规范 这是文档的核心，必须明确无歧义。 ### 3.1 输入 * **参数1**: `log_string` * **类型**: `string` * **描述**: 原始日志行字符串。 * **约束**: 不能为空。 * **参数2**: `log_format` (可选) * **类型**: `string` * **描述**: 日志格式模板，默认为 `“%timestamp% [%level%] %code%: %message%”`。 * **示例值**: `“%Y-%m-%d %H:%M:%S | %level% | %message%”` ### 3.2 输出 * **成功时返回**: ```json { "success": true, "data": { "timestamp": "2023-10-27T14:30:00Z", "level": "ERROR", "code": "ERR-1001", "message": "Database connection failed.", "raw": "原始日志字符串" } } ``` * **失败/错误时返回**: ```json { "success": false, "error": { "code": "INVALID_FORMAT", "message": "提供的日志字符串不符合预期的格式。" } } ``` ## 4. 使用示例 提供2-3个典型场景的调用示例，这是LLM学习如何应用该技能的关键。 ### 4.1 示例1：解析标准错误日志 **输入**:

log_string: “2023-10-27T14:30:00Z [ERROR] ERR-1001: Database connection failed.”

**预期输出**: (见上方成功返回的JSON) ### 4.2 示例2：处理自定义格式日志 **输入**:

log_string: “2023-10-27 14:30:00 | CRITICAL | 主服务进程意外退出。” log_format: “%Y-%m-%d %H:%M:%S | %level% | %message%”

**预期输出**: ```json { "success": true, "data": { "timestamp": "2023-10-27T14:30:00Z", "level": "CRITICAL", "message": “主服务进程意外退出。”, "raw": “...” } }

5. 实现逻辑与算法（可选但推荐）

简要描述技能背后的关键逻辑。这能帮助高级用户或LLM在需要适配或调试时理解内部机制。例如：

首先，尝试使用log_format参数（如果提供）作为正则表达式模板进行匹配。
如果未提供log_format，则依次尝试一组预定义的正则表达式模式。
时间戳解析使用宽松的日期时间库，支持多种格式。
日志级别从字符串映射到标准枚举值（INFO, WARN, ERROR, DEBUG, CRITICAL）。

6. 边界情况与错误处理

列出已知的特殊情况和处理方式。

情况1: 日志字符串中包含未转义的特殊字符（如[或]）。
- 处理: 在正则匹配前进行基本的转义处理，或明确说明不支持。
情况2: 时间戳格式无法识别。
- 处理: 在输出中将timestamp字段设为null，并在返回中添加一个warnings数组说明情况。
情况3: 输入为空字符串或null。
- 处理: 返回错误码为EMPTY_INPUT的失败响应。

7. 依赖与前置条件

外部库: 无（纯正则表达式实现），或列出如dateutil（Python）。
环境要求: 无特殊要求。
其他技能依赖: 无，或依赖Common_Time_Parser技能。

8. 变更历史

v1.0.0 (2023-10-27): 初始版本发布。
v0.2.0 (2023-10-20): 增加了对自定义log_format的支持。

### 3.2 编写时的核心原则与避坑指南 在编写这类文档时，有几点经验之谈至关重要： 1. **原子性**：一个技能应该只做一件事，并把它做好。不要编写一个叫“处理用户数据”的庞大技能，而应该拆分成“验证邮箱格式”、“哈希密码”、“生成用户ID”等多个原子技能。这样复用性更高，也更容易测试和维护。 2. **明确性高于灵活性**：在输入输出定义上，宁可一开始限制得严格一些，也不要为了“灵活”而留下模糊空间。例如，与其说“返回一个时间对象”，不如明确说“返回ISO 8601格式的字符串”。模糊的定义会导致LLM调用时产生不确定的结果。 3. **示例即测试**：你提供的使用示例，不仅是给人看的说明书，也应该是LLM学习的“训练数据”，甚至可以转化为该技能的自动化测试用例。确保示例覆盖典型场景和主要边界情况。 4. **为“机器阅读”优化**：虽然用Markdown写，但要想象LLM会如何解析它。使用一致的标题层级（`##`, `###`），规范的列表和代码块标记。避免使用过于复杂的表格或图片（除非必要），因为LLM对纯文本结构的理解最可靠。 > **实操心得**：我习惯在团队仓库中建立一个 `skills/` 目录，每个技能一个子目录，里面包含 `SKILL.md` 和一个可选的 `examples.jsonl` 文件（用于存储更多的调用示例对）。这样，既可以通过阅读文档来理解技能，也可以通过示例文件来微调或评估专门用于调用技能的LLM。 ## 4. 在LLM应用框架中集成与调用Skills 定义了技能文档之后，下一步就是让LLM能够理解和调用它们。这通常需要在你的LLM应用框架中构建一个“技能调度器”或“工具调用”层。 ### 4.1 基于提示词工程的集成方法 对于简单的场景，你可以直接将技能描述和示例格式化后，作为“系统提示词”的一部分注入给LLM。例如，在使用OpenAI API时： ```python import openai def build_system_prompt_with_skills(skills_list): """ skills_list: 一个包含多个技能文档（字符串）的列表 """ prompt = """你是一个专业的编程助手，除了通用编程知识，你还掌握以下特定技能。当用户请求符合某个技能描述时，你必须严格按该技能的规范来执行。 """ for skill in skills_list: prompt += skill + "\n\n---\n\n" prompt += "在回应时，请直接输出技能规定的JSON格式结果，无需额外解释。" return prompt # 假设你已经从文件中读取了 parse_log_skill_md 的内容 system_message = build_system_prompt_with_skills([parse_log_skill_md]) response = openai.ChatCompletion.create( model="gpt-4", messages=[ {"role": "system", "content": system_message}, {"role": "user", "content": “请解析这条日志：'2023-10-27T14:30:00Z [ERROR] ERR-1001: Database connection failed.'”} ] )

这种方法直观，但缺点也很明显：当技能很多时，提示词会非常长，消耗大量上下文窗口，且LLM可能无法从众多技能中准确选择。

4.2 构建技能路由与执行引擎

更成熟的方案是构建一个两层架构：

技能路由：用一个专门的LLM调用或规则引擎，分析用户请求，判断其意图并匹配到最合适的技能ID。
技能执行：根据技能ID，加载对应的SKILL.md，将其中的描述、示例和当前用户输入组合成一个精准的提示词，发送给LLM执行，并解析返回结果。

这类似于langchain或dify中的Tool概念。你可以自己实现一个简单的版本：

import json import re class SkillRegistry: def __init__(self, skills_dir): self.skills = {} self.load_skills(skills_dir) def load_skills(self, dir_path): # 遍历目录，加载所有 SKILL.md 文件并解析 for skill_file in Path(dir_path).glob(‘*/SKILL.md’): skill_id = skill_file.parent.name content = skill_file.read_text() # 简单解析，提取描述、输入输出示例等（这里可以用更复杂的Markdown解析器） desc = re.search(r‘## 1\. 技能描述\n\n(.+?)\n##’, content, re.DOTALL) # ... 解析其他部分存入 self.skills[skill_id] def route(self, user_query): # 简单基于关键词的路由，实际可用一个轻量级LLM来做意图识别 for skill_id, skill_info in self.skills.items(): if skill_info[‘keyword’] in user_query: return skill_id return None def execute(self, skill_id, user_input): skill = self.skills[skill_id] # 构建技能专属提示词 prompt = f“”" 你正在执行技能 `{skill_id}`。 技能描述：{skill[‘description’]} 输入规范：{skill[‘input_spec’]} 输出格式必须严格遵循：{skill[‘output_spec’]} 参考示例：{skill[‘examples’]} 现在，请处理以下输入： {user_input} “”" # 调用LLM llm_response = call_llm(prompt) # 尝试从响应中提取JSON try: # 使用正则提取代码块中的JSON json_match = re.search(r‘```json\n(.+?)\n```’, llm_response, re.DOTALL) if json_match: result = json.loads(json_match.group(1)) else: # 尝试直接解析整个响应 result = json.loads(llm_response) return result except json.JSONDecodeError: return {“success”: False, “error”: {“code”: “INVALID_LLM_OUTPUT”, “message”: llm_response}}

4.3 与现有框架（LangChain, Dify）结合

如果你在使用成熟的框架，集成会更方便。以 LangChain 为例，你可以将每个 Skill 封装成一个自定义的Tool：

from langchain.tools import BaseTool from pydantic import BaseModel, Field class ParseLogInput(BaseModel): log_string: str = Field(description=“原始日志字符串”) log_format: str = Field(default=None, description=“可选的自定义日志格式模板”) class ParseLogSkillTool(BaseTool): name = “Parse_Structured_Log” description = “解析结构化日志字符串，提取时间戳、级别、错误码和消息。输入应为包含‘log_string’和可选‘log_format’的JSON对象。” args_schema = ParseLogInput def _run(self, log_string: str, log_format: str = None): # 这里可以封装上述 execute 逻辑，或者直接调用一个已经实现好的函数 # 关键是工具的 description 和 args_schema 直接来源于你的 SKILL.md return execute_parse_log_skill(log_string, log_format) async def _arun(self, log_string: str, log_format: str = None): raise NotImplementedError(“Async not supported”)

然后，将这个 Tool 提供给你的 Agent。这样，当用户说“帮我分析一下这段日志”，Agent 就能自动选择并使用这个工具，输出格式化的结果。

5. 高级实践：技能的测试、组合与版本管理

5.1 为技能建立自动化测试套件

既然技能有明确的输入输出规范，为其编写测试就非常自然。这能保证技能定义的质量，并在迭代更新时防止回归。

import pytest from your_skill_engine import execute_skill def test_parse_log_skill_standard(): """测试标准日志解析""" input_data = {“log_string”: “2023-10-27T14:30:00Z [ERROR] ERR-1001: DB fail”} result = execute_skill(“Parse_Structured_Log”, input_data) assert result[“success”] is True assert result[“data”][“level”] == “ERROR” assert result[“data”][“code”] == “ERR-1001” def test_parse_log_skill_invalid(): """测试无效输入""" input_data = {“log_string”: “This is not a valid log”} result = execute_skill(“Parse_Structured_Log”, input_data) assert result[“success”] is False assert result[“error”][“code”] == “INVALID_FORMAT” # 可以使用pytest参数化来运行技能文档中的所有示例

你可以将测试用例直接放在技能目录下的test_skill.py中，并集成到CI/CD流程。每次更新SKILL.md后，跑一遍测试，确保修改没有破坏现有功能。

5.2 技能的编排与组合：构建复杂工作流

原子技能的强大之处在于它们可以像乐高积木一样组合起来，形成更复杂的工作流。例如，一个“处理用户提交”的工作流可能依次调用以下技能：

Validate_Email_Format
Sanitize_Input_String
Hash_Password_With_Salt
Generate_User_Database_Record
Send_Welcome_Email

在dify或langgraph这类可视化工作流工具中，你可以通过拖拽将这些技能节点连接起来，定义数据流。在代码中，你也可以简单地编排：

def handle_user_signup(user_data): results = {} # 技能1：验证邮箱 email_result = execute_skill(“Validate_Email_Format”, {“email”: user_data[‘email’]}) if not email_result[‘success’]: return email_result results[‘email_valid’] = True # 技能2：清理用户名 sanitize_result = execute_skill(“Sanitize_Input_String”, {“input”: user_data[‘username’]}) user_data[‘username’] = sanitize_result[‘data’][‘sanitized_string’] # 技能3：哈希密码 hash_result = execute_skill(“Hash_Password_With_Salt”, {“password”: user_data[‘password’]}) user_data[‘password_hash’] = hash_result[‘data’][‘hash’] # ... 后续技能 return {“success”: True, “data”: {“user_id”: generated_id}}

5.3 技能库的版本管理与团队协作

将技能文档视为代码的一部分进行管理至关重要。

使用Git：每个技能在skills/目录下有自己的文件夹，包含SKILL.md、test_skill.py和examples.jsonl。
语义化版本：在SKILL.md头部明确版本号（如v1.2.0）。遵循语义化版本规范：主版本号（不兼容的修改）、次版本号（向下兼容的功能新增）、修订号（向下兼容的问题修正）。
变更日志：在文档中维护变更历史章节，清晰记录每次修改的内容、原因和影响。
代码审查：对SKILL.md的修改发起 Pull Request，团队成员可以审查技能的描述是否清晰、接口设计是否合理、示例是否充分。
中央注册表：对于大型团队，可以建立一个简单的技能索引文件（如skills/index.json），列出所有可用技能及其ID、描述、版本和路径，方便动态发现和加载。

6. 常见问题、挑战与优化策略

在实际推行 OpenCode Skills 方法的过程中，你可能会遇到一些典型问题。

6.1 技能匹配不准：LLM无法正确选择技能

问题：用户请求是“检查这个邮箱对不对”，但LLM可能没有触发Validate_Email_Format技能，而是自己生成了一段解释文本。排查与解决：

优化技能描述：确保技能描述（description）包含尽可能多的同义词和常见用户表达方式。例如，不仅写“验证邮箱格式”，还可以加上“检查邮箱地址是否有效”、“判断邮箱是否正确”、“校验email格式”。
引入意图分类器：对于复杂的技能库，不要完全依赖LLM的零样本（zero-shot）选择。可以训练一个轻量级的文本分类模型（或使用一个小型LLM），专门负责将用户查询分类到具体的技能ID。这比让大模型从长上下文中选择更精准、更经济。
提供少量示例：在给LLM的系统提示词中，除了技能描述，再提供几个“用户查询 -> 应调用技能”的示例，进行少样本（few-shot）学习。

6.2 输出格式不稳定：LLM不遵守指定的JSON格式

问题：LLM的回复可能夹杂解释性文字，或者JSON格式有细微错误，导致后续程序无法解析。排查与解决：

强化指令：在提示词中非常强硬地规定输出格式。例如：“你必须且只能输出一个JSON对象，不要有任何额外的markdown标记、解释或前言后语。你的输出将直接被程序解析，任何非JSON内容都会导致错误。”
使用结构化输出功能：如果LLM API支持（如OpenAI的JSON Mode，或Anthropic Claude的XML工具调用），务必启用。这能极大提高输出格式的稳定性。
后处理与重试：在execute函数中实现健壮的解析逻辑。如果第一次返回无法解析，可以尝试提取JSON部分，或者向LLM发送一个简化的修正请求（如“你刚才的回复不是有效的JSON，请严格按以下格式重试：...”）。

6.3 技能文档的维护成本

问题：随着技能增多，维护大量SKILL.md文档变得繁琐，容易与实际实现代码不同步。排查与解决：

DRY（Don‘t Repeat Yourself）原则：考虑从代码（如函数的docstring或类型定义）中自动生成技能文档的骨架。例如，用Python的pydantic定义输入输出模型，用工具提取生成Markdown中的“输入/输出规范”部分。
契约测试：建立技能文档与实现代码之间的“契约”。测试用例同时验证文档中的示例和代码的实际运行结果，确保二者一致。
简化文档：对于非常简单的技能，可以考虑使用更简洁的定义格式，如YAML或JSON Schema，而不是完整的Markdown。但需权衡可读性和机器可读性。

6.4 性能与成本考量

问题：每次调用技能都涉及一次LLM API调用，对于简单任务（如字符串格式化）可能成本过高、延迟过大。排查与解决：

技能分级：并非所有“技能”都需要LLM实现。将技能分为两类：
- LLM技能：需要理解、推理、生成自然语言或复杂逻辑的任务。
- 确定性函数技能：有明确算法、规则简单的任务（如格式转换、计算）。
实现混合执行：你的技能执行引擎应该能判断。如果技能描述中指明了“实现逻辑”是确定性的，或者技能ID映射到了一个本地函数，就直接调用本地函数，完全绕过LLM。只有真正需要创造力的任务才调用LLM。这样，Validate_Email_Format可能只是一个正则表达式函数，而Generate_Poetic_Error_Message才需要GPT-4。

通过以上这些策略，你可以将 OpenCode Skills 这套方法论从一个小巧的实践，逐步扩展成一个稳健的、支撑团队高效使用LLM的基础设施。它的本质是将人与AI协作的“接口”标准化、文档化、工程化，这正是当前LLM应用从玩具走向生产系统的关键一步。