企业官网建设流程全解析

OpenWork 工作区引导 Skill（workspace-guide）解析：用 Agent Skill 完成新用户 onboarding

【免费下载链接】openworkThe open-source alternative to Claude Cowork (powered by opencode)项目地址: https://gitcode.com/GitHub_Trending/ope/openwork

本文以 OpenWork 仓库中发布的workspace-guideAgent Skill 为绝对主体，逐层拆解这份SKILL.md的 frontmatter 契约、面向技术/非技术用户的双路径引导流程，以及 Skills、Plugins、MCP Servers、Config 四大扩展体系的配置入口；并结合仓库内的 Skill 作者契约与扩展清单源码，讲清楚“一份引导 Skill 在 OpenWork 里是如何被定义、索引与落地的”。读完你将掌握：如何读懂一个SKILL.md的完整结构、如何用分叉式提问做 onboarding、以及 OpenWork 中 Skill/Plugin/MCP/Config 各自的配置位置与适用人群。

这份文档是什么：一段服务于“人机协作上手指引”的 SKILL.md

在 ee/apps/landing/public/.well-known/agent-skills/workspace-guide/SKILL.md 中，存放着 OpenWork 面向新用户的第一份“见面礼”——一个名为workspace-guide的 Agent Skill。它的定位从 frontmatter 就能读出来：

--- name: workspace-guide description: Workspace guide to introduce OpenWork and onboard new users. ---

• name：Skill 的唯一标识，也是.well-known目录下挂载的文件名；
• description：面向 Agent/LLM 的触发描述，说明“何时使用这份 Skill”——当需要介绍 OpenWork、引导新用户上手时，Agent 应当读取并遵循它。

这份 Skill 并不孤立存在，它被发布系统登记在一个符合 agentskills.io 规范的索引中：ee/apps/landing/public/.well-known/agent-skills/index.json：

{ "$schema": "https://agentskills.io/schemas/v0.2.0/index.json", "skills": [ { "name": "workspace-guide", "type": "skill", "description": "Workspace guide to introduce OpenWork and onboard new users.", "url": "https://openworklabs.com/.well-known/agent-skills/workspace-guide/SKILL.md", "sha256": "3ac4a29e608decea652bed0aa0280b43d628f84cef6485bcb76de7cbfc655a69" } ] }

索引中给出了name、type、description、url与内容校验值sha256，相当于把 Skill 的“可发现性”与“完整性”都固化下来——这也是 OpenWork 面向 Agent 生态暴露自身能力的一个入口。与之配套的 ee/apps/landing/public/llms.txt 同样把该 Skill 标记为“首次运行 onboarding”的指定资源，而 ee/apps/landing/lib/agent-markdown.ts 中的下载页文案也写着：桌面应用启动后，使用 workspace-guide Skill 完成首次运行的定向引导。

引导的开场：用提问工具做“技术/非技术”分叉

SKILL.md 的正文以一个关键指令开场：

Hi, I'm Ben and this is OpenWork. It's an open-source alternative to Claude's cowork. It helps you work on your files with AI and automate the mundane tasks so you don't have to.

Before we start, use the question tool to ask: "Are you more technical or non-technical? I'll tailor the explanation."

这一设计体现了 Agent Skill 的核心实践：不要一上来就灌入全部信息，而是先用提问工具收集用户画像，再按分支输出定制化解释。这既是引导效率的优化，也是 Skill 内容组织方式的示范——同一份 SKILL.md 内部天然分成非技术用户与技术用户两条路径。

非技术用户路径：把 OpenWork 讲成“能碰文件的聊天应用”

对非技术用户，Skill 给出一个极易理解的比喻：

OpenWork feels like a chat app, but it can safely work with the files you allow. Put files in this workspace and I can summarize them, create new ones, or help organize them.

关键信息有三层：

1. 交互形态：OpenWork 用起来像聊天应用，学习成本低；
2. 权限边界：Agent 只能“安全地操作你允许它访问的文件”，文件由用户主动放入 workspace；
3. 能力范围：可以总结（summarize）、新建（create）、整理（organize）。

Skill 还提供了三条可直接照抄的引导话术，让新用户 30 秒内就能发起第一次真实协作：

• "Summarize the files in this workspace."—— 让 Agent 总结工作区文件；
• "Create a checklist for my week."—— 让 Agent 创建周清单；
• "Draft a short summary from this document."—— 让 Agent 从某份文档提炼摘要。

随后是一段极简的“Skills and plugins”科普：

Skills add new capabilities. Plugins add advanced features like scheduling or browser automation. We can add them later when you're ready.

即：Skill 负责“加能力”，Plugin 负责“加高级功能”（如定时任务、浏览器自动化），且节奏上先让用户用起来，扩展项“等准备好了再加”，避免新用户被术语淹没。

技术用户路径：OpenWork 是 OpenCode 的 GUI

对技术用户，SKILL.md 给出的定义非常干脆：

OpenWork is a GUI for OpenCode. Everything that works in OpenCode works here.

这句话在 ee/apps/landing/public/llms.txt 中有完整呼应：“Under the hood, OpenWork is a GUI for OpenCode — anything OpenCode supports works here.” 这意味着：OpenCode 支持的模型、Provider、Skill、Plugin、MCP Server 体系，在 OpenWork 中原样可用，两者共享同一套底座。

当前最可靠的安装路径（三步）

Skill 特别标注了“today”最可靠的组合：

1. 从 opencode.ai 安装 OpenCode；
2. 在 OpenCode 里配置 providers（模型与 API keys）；
3. 回到 OpenWork，开始一个 session。

这套顺序的用意在于：把“模型与密钥”这类最易出错的配置收敛在 OpenCode 的成熟配置流程中，OpenWork 侧只负责消费这些已就绪的 Provider。在 OpenWork 仓库中也能看到对 Provider 配置的消费侧实现，例如 apps/app/src/app/extensions.ts 中内置的ollama扩展 manifest，其resources同时声明了本地服务（http://localhost:11434）与provider资源（@ai-sdk/openai-compatible），enablement条件则是provider-connected——只有当对应 Provider 连接成功，扩展才被判定为“active”。

四大扩展体系：Skills / Plugins / MCP Servers / Config

技术路径的正文部分，把 OpenWork 的能力面概括为四个配置入口：

SKILL.md 为每一项都标注了 OpenCode 官方文档作为参考（Skills、Plugins、MCP Servers、Config 四份文档），正文中不再展开 URL，读者在 OpenWork 内即可通过标签页或opencode.json完成对应配置。

仓库内的 Skill 作者契约：SKILL.md 的“生产标准”

workspace-guide是“消费方”视角的 Skill，而 OpenWork 还内置了一份“生产方”视角的 Skill 作者指南：apps/app/src/app/data/skill-creator.md。两者对照，可以完整还原 OpenWork 的 Skill 体系：

• Skill 的物理形态：一个以SKILL.md为锚点的目录。本地 Skill 位于.opencode/skills/<skill-name>/或.claude/skills/<skill-name>/，推荐结构为：

.opencode/ skills/ my-skill/ SKILL.md README.md templates/ scripts/

• frontmatter 契约：name必须匹配目录名，description必须是“触发导向”的描述。skill-creator 明确要求 description 里包含 2-3 个带引号的具体触发短语，并给出校验规则：至少含一个带引号的短语、出现 “when” 或 “triggers”、长度超过约 50 字符。这与workspace-guide的description: Workspace guide to introduce OpenWork and onboard new users.的写法一脉相承——触发描述是 Agent 决定“何时启用这份 Skill”的唯一依据。

• 运行时指令：skill-creator 还提到“Follow the runtimeSkill creation:instruction”，并区分 Cloud（在 OpenWork Cloud 中创建/更新）与 Local（仅写一份.opencode/skills/<skill-name>/SKILL.md并回读）两条流程——这是 Skill 体系在本地与云端的一致性约束。

• 扩展清单中的 skill 资源类型：在 apps/app/src/app/extensions.ts 中，OpenWorkExtensionResourceType明确列出了"skill"这一资源类型，与agent、command、tool、mcp、opencode-plugin等并列；同时ReloadReason包含"skills"，说明安装/变更 Skill 会触发运行时重载。这从源码层面印证了 SKILL.md 中“Install from the Skills tab, or add them to this workspace”的两条落地路径。

收尾的设计：以两个可执行动作结束

SKILL.md 的结尾要求：

End with two friendly next actions to try in OpenWork.

这是 onboarding Skill 的又一个实用范式：引导结束时不抛知识清单，而是抛出两个友好的、立即可执行的下一步动作。结合前文内容，这些动作通常落在“启动一个会话 → 对工作区文件发起一个真实请求”或“从 Skills 标签页安装第一个 Skill”上，让用户在动手体验中完成从“被介绍”到“主动用”的转化。

小结：一份引导 Skill 的完整解剖

回顾workspace-guide，可以提炼出 OpenWork Agent Skill 的四条设计法则：

1. 先问再讲：用提问工具收集用户画像，按技术/非技术分叉输出，避免信息过载；
2. 一个底座，两套话术：底层统一是“OpenCode 的 GUI”，但对非技术用户用“安全的聊天应用”作类比，对技术用户直接给出三步安装与四项配置入口；
3. 扩展体系分层：Skill（加能力）→ Plugin（高级功能）→ MCP（外部工具）→ Config（总配置），按用户准备度渐进引入；
4. 以动作为收尾：结尾给出两个可执行的 next actions，让用户立即上手。

对想在 OpenWork 中自行编写或改进引导类 Skill 的开发者，建议同时阅读三份仓库文件作为对照：workspace-guide/SKILL.md（消费方范例）、skill-creator.md（作者契约与 frontmatter 模板）、extensions.ts（Skill 资源类型与重载机制），即可获得从“读懂”到“写出”一份合格 SKILL.md 的完整闭环。

【免费下载链接】openworkThe open-source alternative to Claude Cowork (powered by opencode)项目地址: https://gitcode.com/GitHub_Trending/ope/openwork