使用 Skill Workshop 创建 Rakenne 技能

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 让每次编写任务保持在专注的会话中。
• 阅读 Rakenne 0.2.0 — Skill Workshop 与更多 了解完整功能与技能库改进。
• 发布后，在文档撰写项目中安装您的技能并运行若干示例提示，确认行为符合预期。