synkos-skill

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

SynkOS Skill

SynkOS 技能

You are running inside SynkOS — a multi-agent orchestration platform. Each Claude session is a visible pane in a workspace grid. You can spawn more panes, delegate work to them, run multiple models in parallel, and orchestrate squad runs.

This file covers the decision tree and must-know patterns. For depth, read the relevant reference file:

references/tools.md — full API for the SynkOS orchestration tools, parameter shapes, return values
references/recipes.md — worked end-to-end examples (code review squad, parallel doc+impl, multi-perspective brainstorm, long migration)
references/providers.md — which provider/model to reach for, with cost & latency tradeoffs
references/squads.md — SynkOS squad templates and multi-pane orchestration patterns

Read these only when needed. SKILL.md alone is enough for most decisions.

你正在SynkOS中运行——这是一个多Agent编排平台。每个Claude会话都是工作区网格中的一个可见面板（pane）。你可以生成更多面板、将工作委派给它们、并行运行多个模型，以及编排团队执行任务。

本文档涵盖决策树和必须掌握的模式。如需深入了解，请阅读相关参考文档：

references/tools.md — SynkOS编排工具的完整API、参数格式、返回值
references/recipes.md — 完整的端到端示例（代码审查团队、并行文档+实现、多视角头脑风暴、长期迁移）
references/providers.md — 不同场景下应选择的提供商/模型，以及成本与延迟的权衡
references/squads.md — SynkOS团队模板和多面板编排模式

仅在需要时阅读这些文档。大多数决策仅靠SKILL.md就足够。

The first decision: do anything special at all?

第一个决策：是否需要执行特殊操作？

Most user requests don't need orchestration. Default to handling things inline. Reach for SynkOS tools only when the task genuinely benefits from one of these signals:

Is the work parallelizable?           → spawn panes
Does it need a different model?        → spawn pane with that model
Does it have 3+ distinct milestones?   → todo_manager
Will it block this pane for >5 min?    → spawn pane, return to user immediately
Does the user say "in parallel"?       → spawn panes, no further deliberation
None of the above?                     → just do the task. Don't perform orchestration.

Spawning a pane has cost: setup time (~5-10s), separate context (sub-pane has zero memory of this conversation), and you have to brief it well. If a task takes you 2 min inline, delegating is slower, not faster.

大多数用户请求不需要编排。默认情况下直接在当前会话内处理任务。只有当任务确实符合以下任一特征时，才使用SynkOS工具：

Is the work parallelizable?           → spawn panes
Does it need a different model?        → spawn pane with that model
Does it have 3+ distinct milestones?   → todo_manager
Will it block this pane for >5 min?    → spawn pane, return to user immediately
Does the user say "in parallel"?       → spawn panes, no further deliberation
None of the above?                     → just do the task. Don't perform orchestration.

生成面板存在成本：设置时间（约5-10秒）、独立上下文（子面板无当前对话的记忆），且你需要清晰地向其说明任务。如果任务在当前会话内只需2分钟完成，委派反而更慢。

The 7 tools at a glance

7个工具概览

Tool	Purpose	When to call
`pane_list`	Discover existing panes	Before spawning — reuse idle panes when possible
`pane_list_providers`	List configured LLMs	Before spawning with a non-default provider
`pane_spawn`	Open new pane	Got a parallelizable subtask
`pane_write`	Send prompt to pane	After spawn (or to existing pane)
`pane_wait_idle`	Block until pane done	Before reading — never read a running pane
`pane_read`	Get pane output	After wait_idle
`pane_set_identity`	Register skill/role on a pane	When spawning a pane for a specific role
`pane_kill`	Kill a pane process	Cleanup when a pane is stuck or no longer needed
`pane_open_browser`	Open a browser pane	When the task needs web interaction
`pane_open_terminal`	Spawn terminal pane	For shell commands or long-running processes
`todo_manager`	Visible task list	Projects with 3+ milestones

Full signatures, return shapes, and edge cases live in

references/tools.md

工具	用途	调用时机
`pane_list`	发现现有面板	生成面板前——尽可能复用空闲面板
`pane_list_providers`	列出已配置的LLM	使用非默认提供商生成面板前
`pane_spawn`	打开新面板	存在可并行化的子任务时
`pane_write`	向面板发送提示词	生成面板后（或向现有面板发送）
`pane_wait_idle`	阻塞直到面板完成任务	读取面板前——绝不要读取正在运行的面板
`pane_read`	获取面板输出	调用wait_idle后
`pane_set_identity`	在面板上注册技能/角色	为特定角色生成面板时
`pane_kill`	终止面板进程	面板卡住或不再需要时进行清理
`pane_open_browser`	打开浏览器面板	任务需要网页交互时
`pane_open_terminal`	生成终端面板	用于执行Shell命令或长时间运行的进程
`todo_manager`	可视化任务列表	包含3个及以上里程碑的项目

完整的签名、返回格式和边缘情况请查看

references/tools.md

。

The three must-know patterns

三个必须掌握的模式

Pattern A: delegate to the worker pane (most common)

模式A：委派给工作面板（最常见）

You always have a worker pane available — its ID is at the top of your system prompt under "squad orchestrator worker". Default

T06AfShP

. Use it for execution work that would block this pane.

pane_write(paneId: <worker-id>, text: "<self-contained task>")
pane_wait_idle(paneId: <worker-id>, timeoutMs: 300000)   # 5 min for non-trivial
pane_read(paneId: <worker-id>, lastN: 200)

The worker has no memory of this conversation. Brief it like a colleague who just walked in: goal, files involved, expected output, where to save it.

你始终有一个可用的工作面板——其ID位于系统提示顶部的“squad orchestrator worker”下，默认值为

T06AfShP

。将可能阻塞当前面板的执行工作委派给它。

pane_write(paneId: <worker-id>, text: "<self-contained task>")
pane_wait_idle(paneId: <worker-id>, timeoutMs: 300000)   # 5 min for non-trivial
pane_read(paneId: <worker-id>, lastN: 200)

工作面板无当前对话的记忆。向它说明任务时要像对刚加入的同事一样：明确目标、涉及的文件、预期输出以及保存路径。

Pattern B: parallel fan-out

模式B：并行分发

Work splits into N independent subtasks. Spawn N panes, write to all in one message turn, then collect.

undefined

工作拆分为N个独立子任务。生成N个面板，在同一消息轮次中向所有面板发送任务，然后收集结果。

undefined

Turn 1 — spawn + write together (concurrent execution)

a = pane_spawn(model: "claude-sonnet-4-6") b = pane_spawn(model: "claude-sonnet-4-6") pane_write(a, "<task A>") pane_write(b, "<task B>")

Turn 2 — wait

pane_wait_idle(a) pane_wait_idle(b)

Turn 3 — read

pane_read(a); pane_read(b)


If you spawn-write-wait-read sequentially per pane, you've lost the parallelism. The whole point is concurrent execution.

pane_read(a); pane_read(b)


如果按顺序逐个面板执行生成-写入-等待-读取操作，就失去了并行性。并行的核心是并发执行。

Pattern C: multi-model squad

模式C：多模型团队

Different models for different cognitive jobs in the same task. Always call
pane_list_providers()
first — provider IDs are machine-specific and unknown IDs are rejected.

opus    = pane_spawn(model: "claude-opus-4-7")              # architecture / hard reasoning
gemini  = pane_spawn(providerId: "gemini-cli", model: "...") # web search / fast iteration
mimo    = pane_spawn(providerId: "mimo-FxzXvc", model: "...") # cheap bulk work

See

references/providers.md

for which model to reach for in which situation.

同一任务中不同认知工作使用不同模型。务必先调用
pane_list_providers()
——提供商ID是机器特定的，未知ID会被拒绝。

opus    = pane_spawn(model: "claude-opus-4-7")              # architecture / hard reasoning
gemini  = pane_spawn(providerId: "gemini-cli", model: "...") # web search / fast iteration
mimo    = pane_spawn(providerId: "mimo-FxzXvc", model: "...") # cheap bulk work

请查看

references/providers.md

了解不同场景下应选择的模型。

todo_manager: when, how, and why

todo_manager：使用时机、方法及原因

Use when the project has 3+ distinct, milestone-level tasks ("Build auth", "Add database", "Create dashboard"). Skip for single-page builds, trivial requests, or conversational questions.

todo_manager(action: "set_tasks", tasks: [...])    # max 7 — first becomes in_progress
todo_manager(action: "move_to_task", moveToTask: "Add database")  # call as soon as a task completes
todo_manager(action: "mark_all_done")              # at the end

Why milestone-level only: micro-steps create noise, the user scans for progress at a glance. "Wire up signup form" reads as progress; "Add import statement" reads as filler.

Call

move_to_task

immediately when each milestone completes — don't batch. Live progress is the feature.

当项目包含3个及以上不同的里程碑级任务（如“构建认证系统”、“添加数据库”、“创建仪表盘”）时使用。单页面构建、简单请求或对话式问题无需使用。

todo_manager(action: "set_tasks", tasks: [...])    # max 7 — first becomes in_progress
todo_manager(action: "move_to_task", moveToTask: "Add database")  # call as soon as a task completes
todo_manager(action: "mark_all_done")              # at the end

为什么只用于里程碑级任务：微步骤会产生噪音，用户只需快速浏览进度。“连接注册表单”能体现进度；“添加导入语句”则显得多余。

每个里程碑完成后立即调用

move_to_task

——不要批量更新。实时进度是该工具的核心特性。

When NOT to invoke this skill

何时不应调用本技能

"What is X?" / "explain Y" — pure knowledge questions, no orchestration involved
Bug fixes, refactors, single-file edits — inline work, no parallelism
Anything where the user is mid-conversation about an unrelated topic and just mentions "open" or "pane" or "agent" in passing

The skill triggers when there's actual orchestration work. If in doubt, just do the task.

"What is X?" / "explain Y" — pure knowledge questions, no orchestration involved
Bug fixes, refactors, single-file edits — inline work, no parallelism
Anything where the user is mid-conversation about an unrelated topic and just mentions "open" or "pane" or "agent" in passing

The skill triggers when there's actual orchestration work. If in doubt, just do the task.

Common mistakes

Reading before waiting —
```
pane_read
```
on a running pane returns partial output. Always
```
pane_wait_idle
```
first.
Sequential when parallel was possible — multiple
```
pane_write
```
s belong in one turn, not one per turn.
Vague briefs to sub-panes — they have zero context. Spell out files, goals, output format, save path.
Spawning when worker exists — call
```
pane_list()
```
first, reuse the idle worker.
Non-default provider without listing first — IDs vary per machine; unknown IDs error out.
Micro-step todos — todo_manager is for 3-7 milestones, not every action.
Using todo_manager for single-task work — it's overhead for trivial requests.
Forgetting
move_to_task
— the user can't see live progress if you batch updates.
Forgetting
pane_set_identity
— always register the role/skill on spawned worker panes so tools can route properly.

Reading before waiting —
```
pane_read
```
on a running pane returns partial output. Always
```
pane_wait_idle
```
first.
Sequential when parallel was possible — multiple
```
pane_write
```
s belong in one turn, not one per turn.
Vague briefs to sub-panes — they have zero context. Spell out files, goals, output format, save path.
Spawning when worker exists — call
```
pane_list()
```
first, reuse the idle worker.
Non-default provider without listing first — IDs vary per machine; unknown IDs error out.
Micro-step todos — todo_manager is for 3-7 milestones, not every action.
Using todo_manager for single-task work — it's overhead for trivial requests.
Forgetting
move_to_task
— the user can't see live progress if you batch updates.
Forgetting
pane_set_identity
— always register the role/skill on spawned worker panes so tools can route properly.

Worker-pane caveat

You may be the orchestrator, but you may also be a worker pane that another orchestrator is delegating to. If your initial prompt looks like a self-contained task with no system framing about being an orchestrator, you're a worker — execute the task directly, don't try to spawn more panes for it.