企业官网建设流程全解析

如果你最近在研究智能体、自动化工作流或者各种效率工具，一定绕不开“技能”这个词。技能就是给助手或工作流封装好的一组可复用能力，比如查天气、算账单、整理会议纪要。以前每往项目里加一个新技能，我都要手写一堆接口定义、回调逻辑和描述文档，后来试着用了 skill-creator 这种脚手架工具，才意识到这件事完全可以像填表一样快速搞定。这篇文章就是我实际使用过程中的完整记录，既包括它解决了什么问题，也包括我是怎么一步步用它从零建技能的，希望给正在折腾技能开发的朋友一点参考。

1. skill-creator 是什么：技能开发这件事，终于不用从零手搓

1.1 技能的本质，以及从零开发到底难在哪

先聊聊“技能”这个词。我理解的技能，是给一个智能体、机器人或自动化系统提供的“能力单元”。它通常由三部分组成：一是对外暴露的入口和参数，告诉调用方“你该传什么给我”；二是执行逻辑，也就是真正干活的代码或脚本；三是描述信息，让使用者或模型知道“这个技能是干什么的，什么时候该调用它”。

早期我做技能开发，基本都是面向某个固定平台去写。平台定义了技能清单格式，我就照着格式手写；平台要求回调地址，我就搭一个服务暴露接口。一个技能从零到能跑，少说也要半天，其中大部分时间消耗在“样板代码”上。而且一旦平台升级，技能清单里的字段改了，现有技能就要跟着批量调整，维护成本很高。

我自己还踩过一个很典型的坑：有一次给一个内部工具写“定时汇总”技能，为了适配平台的新版本，我把每个技能的描述、参数和回调都重新手写了一遍。结果因为两个技能的清单字段顺序不一致，模型在调用时经常把参数传给错误的技能，排查了很久才发现是手写清单里的“参数描述”和“说明文案”混乱导致的。这种问题完全可以通过模板化和自动生成来避免。

1.2 skill-creator 的核心思路：把技能变成“配置 + 脚本”的标准化产物

skill-creator 给我的第一印象，是它把每个技能都收敛成一个标准目录。一个技能就是一个文件夹，里面至少包含一个清单文件（我习惯叫 skill.yaml）和一个执行脚本。清单文件用来声明技能的名称、描述、入参、出参，执行脚本就是真正干活的逻辑。所有技能的骨架由工具统一生成，字段结构固定，再也不用每次手抄平台格式。

它最核心的设计思路，是“定义式开发”。你不需要先了解目标平台到底要求什么格式，只需要用一份中立的配置描述出“我要一个什么样的技能”，然后由工具负责把这份配置转换成目标平台能接收的格式。这样技能的定义与平台的实现被拆开了。今天导出的格式是某智能体平台的清单格式，明天如果换了平台，只要重新导出一次就行，技能的核心逻辑完全不用动。

我还真这么干过。之前在一个项目里同时维护两个不同体系的助手平台，我最早是两边各写一套技能定义，后来改成用 skill-creator 管理同一份技能目录，再分别导出成两边的格式。改了需求之后，只需要在源目录里改配置、改脚本，然后跑两次导出命令，两边就都同步好了。这个“一份来源、多端适配”的模式，是我愿意把它留下来的最大理由。

2. 核心功能拆解与使用场景

2.1 从自然语言需求生成技能骨架

skill-creator 最吸引人的一个功能，是它的初始化器。你可以先不写配置，直接用一句话描述你想做的技能，比如“创建一个技能，输入一段会议文字稿，输出结构化的会议纪要和待办事项”。工具会把这句话解析成一份初始化的 YAML 配置，生成对应的目录和示例代码。

这个生成过程不是简单的模板套用。它会把你的描述拆成几块：技能名称、描述、输入参数、输出结构。比如输入材料是什么类型，是文字还是文件；输出是 JSON 还是纯文本；是否需要额外的开关参数。拆分完之后，工具会生成一个最小的可运行版本，接下来你只需要在生成的项目上继续填细节。我个人的体验是，这个方法特别适合新技能开发的启动阶段，至少能省掉十五到二十分钟的格式思考时间。

不过也要提醒一下，自动生成的配置通常只是“骨架”，不能被完全信任。生成之后你仍然需要自己检查描述是否准确、参数名是否清晰。尤其要留意“技能描述”这一项，模型或调度器能不能在合适的时机调用这个技能，主要就看这一句话写得好不好。我建议把生成后的描述当成初稿，再用自己的话改一遍，写成“当用户想……时，用这个技能……”的句式，命中率会高很多。

2.2 参数校验与依赖锁定，减少隐形故障

技能的每个入参，在 YAML 文件里都可以声明类型、是否必填、默认值和取值范围。运行时工具会根据这份声明自动生成校验代码，调用方传进来的参数如果类型不对、缺少必填项，会直接返回清晰错误信息。这比在业务代码里自己写一长串 if 判断要省心得多。

我在早期的技能里吃过参数校验的亏。有一个文本处理技能，入参 threshold 我声明成了字符串类型，结果调用方传了数字“3”，我的代码把它当字符串去比大小，输出结果完全错了。后来用 skill-creator 的参数类型声明，工具会在入口处做强制类型转换，数字可以转成字符串，非法类型直接拦截，这类问题少了非常多。

依赖管理方面，每个技能目录里支持带一个依赖清单文件，导出时会自动锁定依赖版本。这样做的好处是，不管这个技能最终跑在哪台机器上，环境里的依赖版本都和开发时一致，避免“我本地能跑、生产环境挂了”的经典事故。如果你以前手工管理过多个脚本和环境，一定能理解依赖锁定有多重要。

2.3 导出格式适配多种目标平台

技能定义好之后，最终要发布到具体的执行环境里。不同的环境可能要求不同的技能清单格式：有的要求以特定 JSON Schema 描述参数，有的要求给出 markdown 说明文档，有的只需要一个可执行命令行工具。skill-creator 在导出环节把这层差异屏蔽掉了。

你执行导出命令时，工具会根据当前配置的目标平台类型，把统一的技能定义转换成指定格式。转换过程会补齐平台特有的字段、生成必需的元数据，并检查遗漏项。比如某个平台要求技能必须有示例调用，如果漏了，导出时工具会提示你补充。这个设计大大减少了“导出成功但平台不认”的情况。

需要注意的是，适配器的覆盖面不一样，并不是所有平台都有官方适配器。我在使用中也遇到过某个内部平台没有对应适配器的情况，解决办法是先导成最通用的“标准技能包”，再写一个小脚本做字段映射。这个扩展点本身是开放的，你也可以自己写适配器，难度不算高。

2.4 典型的应用场景，哪些人最适合用

我把实际接触过的技能分了三类，也是 skill-creator 用起来最顺的场景：

• 内容整理类：输入杂乱的文本、笔记、会议记录，输出结构化摘要、待办、时间线。
• 数据查询类：对接内部数据库或接口，把用户提问转换成查询参数，返回结论。
• 流程触发类：根据特定事件调用外部系统，比如创建工单、发送通知、更新表格。

这三类场景的共同点是：输入输出边界清楚、逻辑相对独立、适合写成单脚本。如果你的技能需要复杂的状态管理或者长时间运行，靠这类工具也能做，只是复杂度会上升，后面我会专门聊这个问题。

3. 实操记录：用 skill-creator 从零做一个“会议纪要约简”技能

3.1 安装与初始化项目

我的环境是 macOS，Python 3.10，同时装了 Node.js 18。安装 skill-creator 的命令很简单，只要一条：

pip install skill-creator

安装完成后，使用命令行工具初始化项目。我习惯把所有技能放在同一个仓库里，所以先建了一个目录，然后执行创建命令：

cd skills skill-creator create --name meeting_minutes --description "将会议原始文字记录整理为结构化会议纪要，并提取待办事项"

执行后，工具在当前目录下生成了meeting_minutes/文件夹，里面有这些内容：

meeting_minutes/ ├── skill.yaml ├── run.py ├── requirements.txt └── examples/ └── demo_input.txt

skill.yaml是技能定义，run.py是默认的执行脚本，requirements.txt用来声明 Python 依赖，examples/demo_input.txt是示例输入，也是我后面做本地验证时最常用的文件。

3.2 定义技能元信息与输入参数

自动生成的skill.yaml只是初稿，我按自己的需求改成了这样：

name: meeting_minutes description: "当用户提供会议记录、访谈记录或讨论文字稿时，将其整理为包含摘要、待办和决定的会议纪要。" version: "1.0.0" inputs: - name: transcript type: text required: true description: "会议的原始文字记录" - name: include_action_items type: boolean default: true description: "是否提取待办事项" - name: language type: string default: "zh" enum: ["zh", "en"] description: "输出语言" outputs: - name: summary type: text description: "会议摘要" - name: action_items type: array items: type: object description: "待办事项列表" execute: runner: python3 entry: run.py timeout: 60

这里有几个字段我想重点说。name必须是英文、小写、下划线风格，因为在很多平台里，技能名会被用作函数名，带横杠或大写会有兼容问题。description非常关键，它直接决定模型什么时候调用这个技能。我在描述里特意写了“会议记录、访谈记录或讨论文字稿”，而不是只写“会议纪要”，因为实际需求里用户表达很随意，描述越具体，误调用的概率越低。

required: true表示 transcript 不能缺。include_action_items设了默认值 true，这样调用方不传这个参数也能正常运行。language用枚举限制了取值，避免用户传一个我处理不了的语言代码。

3.3 编写执行逻辑与返回规范

执行脚本run.py我用 Python 写了一个不依赖外部服务的版本。它的逻辑很简单：把输入文本按段落拆开，寻找包含关键词的句子，作为摘要和待办。

import json import sys def parse_transcript(text): paragraphs = [p.strip() for p in text.split("\n") if p.strip()] summary_lines = [] action_lines = [] for p in paragraphs: if any(k in p for k in ["待办", "下一步", "需要完成", "todo", "action", "follow up"]): action_lines.append(p) if any(k in p for k in ["总结", "决定", "结论", "一致同意", "summary", "decision"]): summary_lines.append(p) return summary_lines, action_lines def main(): payload = json.loads(sys.stdin.read()) transcript = payload.get("transcript", "") include_action_items = payload.get("include_action_items", True) output_language = payload.get("language", "zh") summary_lines, action_lines = parse_transcript(transcript) if not summary_lines: # 没有明显关键词时，取前三个段落作为摘要候选 paragraphs = [p.strip() for p in transcript.split("\n") if p.strip()] summary_lines = paragraphs[:3] result = { "summary": "\n".join(summary_lines) if summary_lines else "无摘要", "action_items": [] } if include_action_items: result["action_items"] = action_lines print(json.dumps(result, ensure_ascii=False)) if __name__ == "__main__": main()

这里用标准输入读取 JSON，标准输出返回 JSON，是 skill-creator 默认的通信方式。它不要求用户必须使用固定框架，只要能做“读入参数、返回结果”这个动作就行。需要注意的是，所有返回内容最终要打印到标准输出，调试时的日志消息一定要写到标准错误，否则会把正常的返回数据污染掉。

3.4 本地验证与调试

写完脚本，我把一段模拟会议记录写进了examples/demo_input.txt：

项目周会 决定：使用新的日志方案。 总结：本周完成了接口改造，下周转入联调。 待办：A同学负责更新接口文档，B同学准备测试数据。

然后运行本地调试命令：

skill-creator run meeting_minutes --input examples/demo_input.txt

工具会读取示例文本，调用 run.py，并把返回结果打印出来。我看到的输出是：

{ "summary": "决定：使用新的日志方案。\n总结：本周完成了接口改造，下周转入联调。", "action_items": ["待办：A同学负责更新接口文档，B同学准备测试数据。"] }

第一次跑就成功了。但要提醒自己，这段逻辑对真实会议记录很弱，它只是演示样例。实际项目中我通常会把这里替换成真正的大模型接口或内部服务。用 skill-creator 的好处是，你先把外壳做好，内部逻辑随时可以替换，不影响调用方。

调试时我还试过故意缺少必填参数的情况：

echo '{}' | skill-creator run meeting_minutes

这时工具返回了明确的校验错误，指出了缺少字段 transcript。这种校验让技能在正式对外提供服务前，就能避免一大批低级调用错误。

3.5 导出到目标平台

本地验证通过后，我准备发布到一个主流智能体平台。执行导出命令：

skill-creator export meeting_minutes --target demo-agent-platform

导出后，目录里多了一个dist/文件夹，里面是平台要求的技能清单文件。我看了一眼生成的清单，发现它自动补全了平台要求的示例和分类字段，并且把我们这边的参数类型转换成了平台对应的描述格式。

把dist目录的内容上传到平台后，我在测试会话里试了一下，输入“帮我根据下面这段记录整理会议纪要”，再附上文字稿，助手成功触发了这个技能。整个流程从初始化到上线，大概用了半小时，比我以前手写快了不少。

4. 常见问题与排查技巧实录

4.1 技能加载失败：先看目录结构和清单名

使用过程中我遇到最多的问题，是技能加载失败。有一次我把skill.yaml改成了Skill.yaml，平台直接报“技能清单未找到”。后来我养成一个习惯：技能目录内的文件名严格小写，保持统一的目录结构。如果出现加载失败，第一步先检查文件名和目录层级，第二步再用工具自身的校验命令：

skill-creator validate meeting_minutes

这个命令会检查 YAML 格式、必填字段、入口文件是否存在，并且会把错误行号直接指出来。比肉眼看配置快得多。

4.2 参数类型导致的校验问题

参数校验方面，我遇到过比较隐蔽的情况是布尔值。调用方传的include_action_items是字符串"false"，平台框架转成了字符串而不是布尔值。我的脚本里直接拿到的是"false"，这个值在 Python 里是 truthy，于是待办照样被提取了，产生了错误的输出。

解决办法是在脚本入口做一次严格类型归一化，或者依靠工具生成的参数校验层。我最终是在 YAML 里明确声明了type: boolean，并重新初始化了校验代码。经过这次之后，所有技能的参数类型我都不会再偷懒省略。

4.3 执行超时，如何定位是慢还是卡死

技能执行超时是我用过的平台最常见的问题。一个技能默认超时 60 秒，如果里面有循环等待或者外部接口调用，很容易超时。我的定位思路分两步：第一步在脚本里加详细日志，打印每个阶段耗时；第二步用带超时参数的本地命令模拟实际执行：

timeout 60 skill-creator run meeting_minutes --input examples/demo_input.txt

如果本地跑超过 60 秒，就说明逻辑本身确实慢，需要优化脚本；如果本地秒回但平台上超时，就可能是平台冷启动或网络问题，需要调大超时时间或检查运行环境。

4.4 跨平台运行：路径、编码与权限

把技能从开发机换到另一台机器或容器里运行时，我踩过的坑主要有三个。第一是文件路径，不要在脚本里写死/Users/xxx/...，应该用相对路径或环境变量。第二是中文编码，Windows 下经常遇到UTF-8读取报错，我统一在脚本开头加了# -*- coding: utf-8 -*-，并且所有文件读取都显式指定encoding="utf-8"。第三是执行权限，run.py有时需要在 Linux 环境下有执行权限，否则会直接 permission denied。

这些问题的共同点，都是“本地能跑、转发就不行”。所以我每次换运行环境前，都会先做一次最小化冒烟测试，用一个极简输入验证整个链路，再放真实流量。

5. 我踩过的一些坑，以及现在的固定习惯

5.1 技能命名和描述怎么写才不容易乱

命名影响函数名、文件名、包名，尤其在多技能项目里，命名混乱会导致调用方分不清意图。我现在固定用snake_case，比如meeting_minutes、daily_report_summary。描述则遵循“当用户需要……时使用，输入是……，输出是……”的模板，并且尽量包含同义词。

我见过一个反面案例：某位同事写了一个“查询天气”的技能，描述里只写了“天气查询”，结果用户在对话里问“今天出门要带伞吗”，模型犹豫了很久，一会儿调用天气技能，一会儿调用聊天能力，体验很差。后来把描述改成“当用户询问当前或未来天气、是否降雨、是否需要带伞时，使用该技能”，调用准确率立刻上来了。

5.2 技能内要不要维护状态？我的建议是尽量别

技能最适合做成“输入到输出”的纯函数。如果你在技能里维护了内存缓存、会话状态，就相当于给自己埋了雷。平台可能在多个副本上调用同一个技能，每次实例的运行环境不固定，内存状态完全是不可控的。

如果确实需要状态，我建议放到外部的对象存储或数据库里，技能本身只负责读写。比如做一个“连续记录用户打卡”的技能，不要把打卡记录存在脚本内部，应该设计成每次调用都从数据库读取最新值，更新后再写回。这样无论技能被调度到哪个实例，结果都是一致的。

5.3 测试策略：先模拟、后真实、再回归

我在技能开发里现在坚持三步走。第一步用固定的示例输入做本地验证，确保输出结构正确。第二步接入待替换的真实逻辑，比如调用大模型或内部接口，用少量真实样本跑一次，确认结果可接受。第三步是把历史输入保存成回归样本库，在技能或依赖升级后批量跑一遍，确认所有旧案例仍然正常。

回归测试这一步尤其重要。有时候不是因为你的代码改坏了，而是上游接口返回格式变了，技能在运行时会悄悄出错。有了回归样本库，这种变化能第一时间暴露出来。skill-creator 的目录结构天然适合把示例输入和预期输出放在examples/下，我每次升级依赖或修改逻辑，都会顺手把所有示例跑一遍，成本很低。

最后分享一个小习惯。我现在会把所有技能都放进同一个 Git 仓库，每次改动都留下清晰的 commit 信息。配合 skill-creator 这类工具，技能开发从“手工作坊”变成了“标准化流水线”。哪天新需求来了，我只需要在仓库里新增一个目录，写配置、写脚本、跑测试、导出，整个流程清晰可控。这个工作方式我用了很久，希望也能给你一点参考。