# 使用 Skill Workshop 创建 Rakenne 技能

> 使用 Skill Workshop 项目类型编写自定义文档撰写技能的分步指南。

Author: map[bio:Founder linkedin:https://www.linkedin.com/in/ricardocabral/ name:Ricardo Cabral]
Published: 2026-02-12

URL: https://rakenne.app/zh-cn/learn/tutorials/creating-skills-with-skill-workshop/index.md


Rakenne **技能**是智能体在用户描述任务时可执行的文档撰写工作流。**Skill Workshop** 是专用于通过与智能体对话创建并发布自有技能的项目类型 — 无需编写代码。本教程将带您走完整个流程：从创建 Workshop 项目到将技能发布到您组织的技能库。

## 您需要准备

- 能创建项目的 Rakenne 实例访问权限。
- 对要转化为技能的领域工作流有清晰想法（例如：「根据转录整理会议纪要」「按我们的 playbook 审查合同」「根据法规 X 生成合规检查清单」）。

## 步骤 1：创建 Skill Workshop 项目

1. 在 Rakenne 中点击 **创建项目**（或您界面中的对应入口）。
2. 选择项目类型时选择 **Skill Workshop**。
3. 为项目命名（例如「我的技能编写」）并创建。

工作区将预置：

- **skill-creator 技能** — 位于 `.pi/skills/skill-creator/` 的内置技能，用于引导编写流程。
- **AGENTS.md** — 告知智能体这是技能编写工作区，技能应放在 `output/`。
- **output/** — 空目录，您编写的每个技能将放在其中（每个技能一个子目录）。

您使用的是您已熟悉的工作区：与智能体对话、浏览文件树、预览文档。唯一区别是模板与目标：产出的是技能而非单一文档。

## 步骤 2：开始编写对话

打开项目，在聊天中说明您想构建的内容。例如：

- *「我想创建一个技能，把会议转录整理成带决策和待办事项的结构化笔记。」*
- *「我们需要一个技能，用我们内部模板和 PIPEDA 帮助撰写隐私影响评估。」*

智能体会使用 **skill-creator** 技能，在理解您的工作流之前**不会**创建任何文件。它会以结构化方式向您提问（**Elicit** 阶段）。

## 步骤 3：回答 elicitation 问题

智能体会询问：

1. **工作流用途** — 领域与任务（如会议笔记、合同审查、合规）。
2. **触发条件** — 用户何时会使用该技能（如「当用户有转录并希望得到结构化笔记时」）。
3. **包含的步骤** — 顺序（如：接收输入 → 提取决策与行动 → 确认歧义 → 产出文档）。
4. **输出形式** — 文档类型、章节、格式（如执行摘要、决策记录、待办事项）。
5. **领域知识** — 智能体应使用的法规、标准、模板或参考资料。

用自然语言回答即可。智能体会把您的回答整理成结构化技能；您不需要会 Markdown 或 YAML。若有模板或参考文档，可稍后添加或口头描述，智能体会在技能中引用占位符。

## 步骤 4：让智能体搭建并撰写技能

当智能体掌握足够信息后，它会：

1. **选择 slug** — 一个 kebab-case 标识符（如 `meeting-notes`、`contract-review-playbook`）。
2. **调用 `scaffold_skill`** — 在 `output/{slug}/` 下创建 `SKILL.md` 模板及可选的 `references/`、`assets/` 目录。
3. **编辑 `SKILL.md`** — 填写工作流步骤、引用文件链接，并在描述中加入触发语，便于智能体判断何时使用该技能。
4. **添加 reference 与 asset 文件** — 领域知识放在 `references/`；输出模板或示例放在 `assets/`。

以上都在聊天中完成；您可以在文件树中查看并打开文件审阅。技能**仅**会写入 `output/` 下。

## 步骤 5：校验与精修

在将技能视为完成前，智能体会执行 **`validate_skill`**。校验包括：

- **SKILL.md** 存在且具有有效 YAML frontmatter（`name`、`description`）。
- **描述质量** — 描述包含触发语（如「Use when…」「Use for…」）。
- **正文长度** — SKILL.md 正文不超过 500 行（过长内容应放在 `references/`）。
- **引用完整性** — SKILL.md 中的链接指向存在的文件；无失效链接。
- **metadata.json** — 存在且有效（若缺失会提示；下一步会补充）。

若有未通过项，智能体会建议修改（如补充触发语、修正路径、将内容移到引用文件）。您可在对话中精修并重新校验，直到全部通过。

## 步骤 6：为技能库准备元数据

当您对技能内容满意后，智能体会**准备发布**：

1. **运行 `preview_metadata`** — 显示该技能在技能库中的展示效果。若不存在 `metadata.json`，会从 SKILL.md 的 frontmatter 生成草稿。
2. **编辑 `metadata.json`** — 与智能体一起设置 **title**（技能库中的可读名称）、**description**（简短摘要）、**tags**（面向领域的英文通用词，如 "Productivity"、"Meetings"、"Legal"、"Compliance"）和 **examples**（两三个示例提示）。
3. **再次校验** — 最后一次 `validate_skill` 确保元数据与结构完整。

此后智能体会告知您技能已可发布。

## 步骤 7：发布到您的技能库

1. 在**项目工作区工具栏**中点击 **Publish Skill**。
2. 对话框中会列出您 `output/` 目录下的技能（每个包含 `SKILL.md` 的文件夹）。选择要发布的技能。
3. 确认。前端会调用发布 API；技能将被复制到您组织的技能库并登记到目录。
4. 您会看到成功提示（如「技能已发布到库」）。该技能在您租户内任意项目安装技能时可用。对同一 slug 再次发布会原地更新已有技能。

## Rakenne 技能结构概览

`output/{slug}/` 下的最小技能包含：

- **SKILL.md** — 必填。YAML frontmatter 含 `name`（slug）和 `description`（含触发语）。正文：工作流步骤、规则及对 references 的链接。
- **metadata.json** — 发布必填。`title`、`description`、`tags`（数组）、`examples`（示例提示数组）。供技能库界面使用。
- **references/** — 可选。存放领域知识的 Markdown（或其他）文件；从 SKILL.md 链接，供智能体在工作流中读取。
- **assets/** — 可选。智能体产出输出时使用的模板或静态资源（如 `meeting_notes_template.md`）。

skill-creator 流程会保持 SKILL.md 简洁，将详细内容放在 `references/`，使智能体既有清晰可扫读的工作流，又在需要时获得丰富上下文。

## 提示

- **一个工作流对应一个技能** — 若有多个不同工作流，请为每个工作流创建一个技能；同一 Workshop 项目中可以编写多个技能（各自在 `output/{slug}/` 下）。
- **触发语很重要** — 智能体根据技能的 `description` 决定何时激活。诸如「Use when the user wants to…」「Use for drafting…」或「Use to generate…」的表述有助于匹配用户意图。
- **在 Workshop 中迭代** — 可随时重新打开项目，编辑文件或与智能体对话修改技能，重新校验后再次 **Publish Skill** 以更新库中副本。
- **领域技能无需 extension.ts** — Skill Workshop 面向基于 Markdown 的技能（SKILL.md + references + assets）。TypeScript 扩展不在引导流程范围内；skill-creator 不会创建或编辑 `extension.ts`。

## 下一步

- 使用 [Session Management and Context Hygiene](/learn/tutorials/session-management/) 让每次编写任务保持在专注的会话中。
- 阅读 [Rakenne 0.2.0 — Skill Workshop 与更多](/learn/releases/rakenne-0-2-0/) 了解完整功能与技能库改进。
- 发布后，在文档撰写项目中安装您的技能并运行若干示例提示，确认行为符合预期。


---

Back to [教程](https://rakenne.app/zh-cn/learn/tutorials/index.md)