Skip to content

Commit dc7dd98

Browse files
fix(onboarding): smooth workspace guide flow (anomalyco#78)
1 parent c292aec commit dc7dd98

4 files changed

Lines changed: 91 additions & 15 deletions

File tree

Lines changed: 47 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,47 @@
1+
---
2+
name: opencode-primitives
3+
description: Reference OpenCode docs when implementing skills, plugins, MCPs, or config-driven behavior.
4+
---
5+
6+
## Purpose
7+
Use this skill whenever OpenWork behavior is implemented directly on top of OpenCode primitives (skills, plugins, MCP servers, opencode.json config, tools/permissions). It anchors decisions to the official OpenCode documentation and keeps terminology consistent in the UI.
8+
9+
## Doc Sources (Always cite when relevant)
10+
- Skills: https://opencode.ai/docs/skills
11+
- Plugins: https://opencode.ai/docs/plugins/
12+
- MCP servers: https://opencode.ai/docs/mcp-servers/
13+
- Config (opencode.json, locations, precedence): https://opencode.ai/docs/config/
14+
15+
## Key Facts To Apply
16+
### Skills
17+
- Skill files live in `.opencode/skills/<name>/SKILL.md` or global `~/.config/opencode/skills/<name>/SKILL.md`.
18+
- Skills are discovered by walking up to the git worktree and loading any matching `skills/*/SKILL.md` in `.opencode/` or `.claude/skills/`.
19+
- `SKILL.md` requires YAML frontmatter: `name` + `description`.
20+
- Name rules: lowercase alphanumeric with single hyphens (`^[a-z0-9]+(-[a-z0-9]+)*$`), length 1-64, must match directory name.
21+
- Description length: 1-1024 characters.
22+
- Access is governed by `opencode.json` permissions (`permission.skill` allow/deny/ask).
23+
24+
### Plugins
25+
- Local plugins live in `.opencode/plugins/` (project) or `~/.config/opencode/plugins/` (global).
26+
- npm plugins are listed in `opencode.json` under `plugin` and installed with Bun at startup.
27+
- Load order: global config, project config, global plugins dir, project plugins dir.
28+
29+
### MCP Servers
30+
- MCP servers are defined in `opencode.json` under `mcp` with unique names.
31+
- Local servers use `type: "local"` + `command` array; remote servers use `type: "remote"` + `url`.
32+
- Servers can be enabled/disabled via `enabled`.
33+
- MCP tools are managed via `tools` in config, including glob patterns.
34+
- OAuth is handled automatically for remote servers; can be pre-registered or disabled.
35+
36+
### Config (opencode.json)
37+
- Supports JSON and JSONC.
38+
- Precedence order: remote `.well-known/opencode` -> global `~/.config/opencode/opencode.json` -> custom path -> project `opencode.json` -> `.opencode/` directories -> inline env overrides.
39+
- `.opencode` subdirectories are plural by default (`agents/`, `commands/`, `plugins/`, `skills/`, `tools/`, `themes/`), with singular names supported for compatibility.
40+
41+
## When to Invoke
42+
- Adding or adjusting OpenWork flows that reference skills, plugins, MCP servers, or OpenCode config.
43+
- Designing onboarding guidance that mentions skill/plugin installation, config locations, or permission prompts.
44+
- Implementing UIs that surface OpenCode primitives (skills tab, plugin manager, MCP toggles).
45+
46+
## Usage
47+
Call `skill({ name: "opencode-primitives" })` before implementing or documenting any OpenWork behavior that maps to OpenCode primitives.

‎src-tauri/src/workspace/files.rs‎

Lines changed: 42 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -35,32 +35,61 @@ pub fn sanitize_template_id(raw: &str) -> Option<String> {
3535
}
3636

3737
fn seed_workspace_guide(skill_root: &PathBuf) -> Result<(), String> {
38-
let guide_dir = skill_root.join("workspace_guide");
38+
let guide_dir = skill_root.join("workspace-guide");
3939
if guide_dir.exists() {
4040
return Ok(());
4141
}
4242

4343
fs::create_dir_all(&guide_dir)
4444
.map_err(|e| format!("Failed to create {}: {e}", guide_dir.display()))?;
4545

46-
let doc = r#"# Workspace Guide
46+
let doc = r#"---
47+
name: workspace-guide
48+
description: Workspace guide to introduce OpenWork and onboard new users.
49+
---
4750
48-
This workspace is a real folder with local configuration.
51+
# Welcome to OpenWork
4952
50-
## What lives where
53+
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.
5154
52-
- Workspace plugins: `opencode.json`
53-
- Workspace skills: `.opencode/skill/*`
54-
- Workspace templates: `.openwork/templates/*.json`
55-
- OpenWork workspace metadata: `.opencode/openwork.json`
55+
Before we start, use the question tool to ask:
56+
"Are you more technical or non-technical? I\'ll tailor the explanation."
5657
57-
## What to try
58+
## If the person is non-technical
59+
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.
5860
59-
- Run the template **Understand this workspace**
60-
- Install a skill from the Skills tab
61-
- Add a plugin in the Plugins tab
61+
Try:
62+
- "Summarize the files in this workspace."
63+
- "Create a checklist for my week."
64+
- "Draft a short summary from this document."
6265
63-
Be concise and practical."#;
66+
## Skills and plugins (simple)
67+
Skills add new capabilities. Plugins add advanced features like scheduling or browser automation. We can add them later when you\'re ready.
68+
69+
## If the person is technical
70+
OpenWork is a GUI for OpenCode. Everything that works in OpenCode works here.
71+
72+
Most reliable setup today:
73+
1) Install OpenCode from opencode.ai
74+
2) Configure providers there (models and API keys)
75+
3) Come back to OpenWork and start a session
76+
77+
Skills:
78+
- Install from the Skills tab, or add them to this workspace.
79+
- Docs: https://opencode.ai/docs/skills
80+
81+
Plugins:
82+
- Configure in opencode.json or use the Plugins tab.
83+
- Docs: https://opencode.ai/docs/plugins/
84+
85+
MCP servers:
86+
- Add external tools via opencode.json.
87+
- Docs: https://opencode.ai/docs/mcp-servers/
88+
89+
Config reference:
90+
- Docs: https://opencode.ai/docs/config/
91+
92+
End with two friendly next actions to try in OpenWork."#;
6493

6594
fs::write(guide_dir.join("SKILL.md"), doc)
6695
.map_err(|e| format!("Failed to write SKILL.md: {e}"))?;

‎src/app/extensions.ts‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -39,7 +39,7 @@ export function createExtensionsStore(options: {
3939
const [packageSearch, setPackageSearch] = createSignal("");
4040

4141
const skillDocFallbacks: Record<string, string> = {
42-
workspace_guide: "Starter workspace guide. Explains what lives in this workspace and what to try next.",
42+
"workspace-guide": "Workspace guide that introduces OpenWork and suggests first steps.",
4343
};
4444
const failedSkillDocs = new Set<string>();
4545
const skillDocKey = (root: string, name: string) => `${root}::${name}`;

‎src/app/workspace.ts‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -263,7 +263,7 @@ export function createWorkspaceStore(options: {
263263
{
264264
type: "text",
265265
text:
266-
"Load the `workspace_guide` skill from this workspace and give a short, welcoming overview of what lives here (skills, plugins, templates) versus what's global. Avoid CLI language or raw file paths. Then suggest two friendly next actions to try inside OpenWork.",
266+
"Give a short, welcoming overview of this workspace and how to use OpenWork. If a workspace guide skill is available, use it. Avoid CLI language or raw file paths. End with two friendly next actions to try inside OpenWork.",
267267
},
268268
],
269269
});

0 commit comments

Comments
 (0)