Agent skill

Fork Design

by stello-agent in stello-agent/stello

Fork 机制完整说明。覆盖 ForkProfile 与 EngineForkOptions 的字段对齐、四层 fallback 合成链(sessionDefaults → parent → profile → forkOptions)、systemPrompt 合成三种模式、skills 三态语义、持久化边界(SerializableSessionConfig 只固化…

Apache-2.0Auto-check passed

Install Fork Design

skills CLI
$ npx skills add stello-agent/stello --skill fork-design -a claude-code

Project install by default; add -g for ~/.claude/skills/.

GitHub CLI
$ gh skill install stello-agent/stello fork-design --agent claude-code

Project scope by default; add --scope user for a personal install. Needs GitHub CLI 2.90.0 or later (public preview).

Manual copy
$ git clone --depth 1 https://github.com/stello-agent/stello.git skills-src && mkdir -p .claude/skills && cp -r skills-src/.agents/skills/fork-design .claude/skills/fork-design && rm -rf skills-src

Use ~/.claude/skills/ instead of .claude/skills for a personal install. The folder must contain SKILL.md.

Claude Code skills documentation · loads skills from .claude/skills/

Facts

Skill name
fork-design
GitHub stars
112
Token cost
~2k tokens
SKILL.md length
629 words
Files
1
Skills in repo
12
Repo updated
First seen
Licence
Apache-2.0

At a glance

Fork 机制完整说明。覆盖 ForkProfile 与 EngineForkOptions 的字段对齐、四层 fallback 合成链(sessionDefaults → parent → profile → forkOptions)、systemPrompt 合成三种模式、skills 三态语义、持久化边界(SerializableSessionConfig 只固化…

  • Works in 8 steps: 校验 profile 存在性 → SplitGuard 拦截(可选) → 读取 sourceSession 的固化配置 → …
  • SKILL.md covers 定位, 触发路径, 类型体系 and 四层 Fallback 合成链, plus 5 more sections
  • Instructions only: no scripts, shell commands, URLs or credentials in SKILL.md

What it does

Fork Design is an agent skill from stello-agent/stello. Fork 机制完整说明。覆盖 ForkProfile 与 EngineForkOptions 的字段对齐、四层 fallback 合成链(sessionDefaults → parent → profile → forkOptions)、systemPrompt 合成三种模式、skills 三态语义、持久化边界(SerializableSessionConfig 只固化 systemPrompt/skills)。任何涉及 fork / profile / stellocreatesession / 配置合成 的工作都应读这个。

Its SKILL.md is about 2k tokens, which your agent loads only when the skill is triggered. It is a single SKILL.md file with no bundled scripts.

The repository describes itself as: Conversations aren't linear — why should AI chats be? The first open-source conversation topology engine. Auto-branching session trees, inherited memory, star-map visualization… The licence is Apache-2.0.

Example prompts

  • “/fork-design”

Workflow steps

8 steps, taken from the first numbered list in SKILL.md.

  1. 校验 profile 存在性
  2. SplitGuard 拦截(可选)
  3. 读取 sourceSession 的固化配置
  4. 按四层链合成最终 SessionConfig
  5. 创建拓扑节点(topology-first,先拿 ID)
  6. 将可序列化子集固化入存储
  7. 调用 session.fork({ id, ... }) 创建 Session 实例
  8. 触发 onSessionFork 事件

What it can do on your machine

Read from SKILL.md and the folder at commit 3bc9493. It shows what the files ask for, not the result of running them.

  • Tool permissions

    Pre-approves nothing: there is no allowed-tools line, so your agent's usual permission prompts apply.

    From allowed-tools in the SKILL.md frontmatter.

  • Runs code

    No scripts in the folder and no shell commands in SKILL.md (its code samples are typescript).

    From the folder's file list and the shell code blocks in SKILL.md.

  • Network

    No URLs in SKILL.md.

    From URLs in SKILL.md, links to its own repository left out.

  • Credentials

    Names no API keys, tokens, secrets or passwords.

    From names ending in _API_KEY, _TOKEN, _SECRET, _KEY or _PASSWORD in SKILL.md.

Context cost

Fork Design loads about 2k tokens when it runs. Until then it costs about 70 tokens; SKILL.md has 629 words of instructions outside code blocks.

Always · name and description, kept in context so the agent knows when to use it
~70
When it runs · the whole SKILL.md, loaded when a task matches
~2k

Estimates: characters ÷ 4, the usual rule of thumb; real counts depend on the model's tokenizer. Scripts and assets cost tokens only if the agent reads them.

Safety

Auto-check passed

The automated check found no risky patterns in SKILL.md.

Automated static check — not a guarantee. Review scripts before installing. It scans the text of SKILL.md for risky patterns (piping downloads into a shell, reading credential files, hidden Unicode, destructive commands); files beside SKILL.md are not scanned.

SKILL.md

The full file from stello-agent/stello at commit 3bc9493, republished under its Apache-2.0 licence (© stello-agent). 629 words, ~1,968 tokens.

Download SKILL.mdSave it as .claude/skills/fork-design/SKILL.md (or your agent's skills folder).
name
fork-design
description
Fork 机制完整说明。覆盖 ForkProfile 与 EngineForkOptions 的字段对齐、四层 fallback 合成链(sessionDefaults → parent → profile → forkOptions)、systemPrompt 合成三种模式、skills 三态语义、持久化边界(SerializableSessionConfig 只固化 systemPrompt/skills)。任何涉及 fork / profile / stello_create_session / 配置合成 的工作都应读这个。

Fork — 子 Session 创建机制

定位

Fork 是 Stello 创建子 Session 的唯一路径。编排层(Engine)负责完整编排:

  1. 校验 profile 存在性
  2. SplitGuard 拦截(可选)
  3. 读取 sourceSession 的固化配置
  4. 按四层链合成最终 SessionConfig
  5. 创建拓扑节点(topology-first,先拿 ID)
  6. 将可序列化子集固化入存储
  7. 调用 session.fork({ id, ... }) 创建 Session 实例
  8. 触发 onSessionFork 事件

调用方不感知内部顺序。两条触发路径(LLM / 代码)共用这整套流程。


触发路径

触发者入口典型场景
LLM内置 tool stello_create_sessionLLM 判断当前任务需要拆分为子任务
应用层代码agent.forkSession(sourceId, options)代码驱动的主动编排(UI 按钮、策略脚本)

两条路径汇聚到同一个 forkSession(options: EngineForkOptions)。LLM 路径只是在前面加了一层 JSON Schema 校验 + tool args → EngineForkOptions 映射。


类型体系

三个类型层层叠加,共享同一个基座。

基座:SessionConfig(6 字段)

所有 Session 运行时可配置项。由 sessionDefaults、父 session 固化 config、ForkProfile、EngineForkOptions 共同描述,mergeSessionConfig 输出也是这个形状。

字段类型说明
systemPromptstringSession 的 system prompt
llmLLMAdapterLLM 适配器
toolsLLMCompleteOptions['tools']用户 tool 定义
skillsstring[]skill 白名单(三态语义见下文)
consolidateFnSessionCompatibleConsolidateFnL3→L2 提炼函数
compressFnSessionCompatibleCompressFn上下文压缩函数
ForkProfile extends SessionConfig

预注册的 fork 配置模板,注册期定义。在 6 个基座字段之上新增 4 个 fork 专属字段:

新增字段类型说明
systemPromptFn(vars) => string动态模板,优先于 systemPrompt 字段
systemPromptMode'preset' | 'prepend' | 'append'合成策略,默认 'prepend'
context'none' | 'inherit' | ForkContextFn上下文继承策略(默认值)
promptstringfork 后的开场消息(默认值)
EngineForkOptions extends SessionConfig

运行时每次 fork 传入的参数。在 6 个基座字段之上新增 6 个运行时字段:

新增字段类型说明
labelstring(必填)子 session 显示名
promptstringfork 后的开场消息
context'none' | 'inherit' | ForkContextFn上下文继承(覆盖 profile 默认值)
topologyParentIdstring显式指定拓扑父节点(不传 = 当前 sessionId)
profilestring引用预注册的 ForkProfile 名
profileVarsRecord<string, string>systemPromptFn 的模板变量
字段对齐矩阵
字段SessionConfigForkProfileEngineForkOptions
systemPrompt✓✓(静态)✓
llm / tools / skills✓✓✓
consolidateFn / compressFn✓✓✓
systemPromptFn—✓—
systemPromptMode—✓—
context—✓(默认)✓(覆盖)
prompt—✓(默认)✓(覆盖)
label——✓ 必填
topologyParentId——✓
profile / profileVars——✓

Profile 和 Options 的差异都是职责驱动的:profile 是模板(不能自引用 profile,不需要 label),options 是运行时参数(需要 label 每次给出,需要引用 profile 入口)。


四层 Fallback 合成链

所有 fork 最终都要合成一份完整的 SessionConfig 交给 session.fork()。合成输入有四层:

sessionDefaults → parent(固化 config) → profile → forkOptions
低优先级                                       高优先级

字段级覆盖规则:后层非 undefined 的字段覆盖前层;undefined 永不覆盖(保留前层值)。

普通字段(llm / tools / skills / consolidateFn / compressFn)

直接走 later-wins 链。每层独立决定某字段是否贡献。

systemPrompt 特殊合成

分有无 profile 两种情况:

情况 A — 有 profile:

  1. 先求 profile 的 promptSource:profile.systemPromptFn?.(profileVars) ?? profile.systemPrompt
  2. 按 profile.systemPromptMode(默认 'prepend')合成 promptSource 与 forkOptions.systemPrompt:
Mode结果
'preset'仅用 profilePrompt;forkOptions 的 systemPrompt 被忽略
'prepend'(默认){profilePrompt}\n\n{forkOptionsPrompt}
'append'{forkOptionsPrompt}\n\n{profilePrompt}
  1. 若 profile + forkOptions 都未贡献 prompt(如 preset 模式两者皆空),回落到 parent → defaults 的普通 later-wins 链。

情况 B — 无 profile:

走 [defaults, parent, forkOptions] 的普通 later-wins 链。

skills 三态语义

skills 不做合并,整数组替换。三种取值:

取值含义
undefined未配置,本层不贡献 — 继承下层值;若所有层皆 undefined,运行时继承全局 SkillRouter(无白名单)
[]显式禁用 — 该 session 的 activate_skill 看不到任何 skill,可覆盖下层非空值
['a', 'b']白名单 — 只允许这几个 skill 可见

显式 [] 覆盖下层 ['a','b'] 是标准行为("undefined 不覆盖"不阻止显式空数组生效)。

实战场景
场景合成链贡献
从 root session forkparent 层 = root 的 SerializableSessionConfig(root 是普通 session,正常参与合成链)
从非 root session forkparent 层 = 该 session 的 SerializableSessionConfig(只有 systemPrompt/skills)
无 profile 的普通 forkprofile 层 = undefined
Profile + options 都提供 llm结果取 options 的 llm
Profile 提供 llm,options 不提供结果取 profile 的 llm

Show full SKILL.md (245 more words)Show less

持久化边界

SerializableSessionConfig 只固化两个字段:systemPrompt、skills。

原因:其余四个字段(llm / tools / consolidateFn / compressFn)本质是运行时引用(函数、适配器、闭包),不可安全序列化。

持久化时机

forkSession() 完成合成后:

  1. 从合成结果挑 systemPrompt 和 skills 两字段打包为 SerializableSessionConfig
  2. 若两字段都是 undefined(空对象),跳过 putConfig 写入,避免给存储层制造噪声
  3. 否则写入 sessions.putConfig(childId, serializable)
运行时重建时的后果

Engine 重新装配某 session 的 runtime config 时:

  • systemPrompt / skills 从固化存储重放
  • llm / tools / consolidateFn / compressFn 不来自父 session 的持久化,而是每次 fork 时从 sessionDefaults → profile → forkOptions 现场合成

实际语义:嵌套 fork(子再 fork 孙)时,孙 session 的 llm 不会自动继承子 session 的 llm。孙 session 的 llm 来自 sessionDefaults(或孙 fork 时显式指定的 profile/options)。要让某条分支始终用特殊 llm,需在每次 fork 时显式传入、或通过 profile 固化。


Fork 专属行为

topologyParentId vs sourceSessionId

两者分离是编排层的关键设计:

概念含义来源
sourceSessionId上下文来源 session(系统提示词、历史继承的对象)总是 = 当前 session.id
topologyParentId拓扑父节点(星空图上挂靠位置)options 显式给出,默认 = sourceSessionId

不传 topologyParentId 时两者相等(默认树形拓扑:fork from X → 挂在 X 下)。调用方显式传入 topologyParentId 可让两者分离——例如想把节点挂到根或任意已有节点下,但上下文继承仍来自发起 fork 的 session(sourceSessionId = current)。

context 继承策略
值含义
'none'(默认)子 session 以空对话历史启动
'inherit'拷贝父 session 全部 L3 记录
ForkContextFn自定义函数,接收父消息数组返回继承子集

options.context 优先级高于 profile.context。

prompt 开场消息

Fork 后写入子 session 的首条 assistant 消息,用户进入子 session 时首先看到。options.prompt 优先于 profile.prompt。


LLM 侧暴露 — stello_create_session

Engine 构造时自动注入此内置 tool。参数 schema 随 ForkProfileRegistry 状态动态变化:

基础参数(始终存在):label(必填)、systemPrompt、prompt、context(enum: 'none' | 'inherit')

条件参数(仅当有 profile 注册时追加):

  • profile:enum,取值为所有已注册 profile 名
  • vars:object,键值对字符串,传给 systemPromptFn

LLM 调用后,Engine 把 tool args 映射为 EngineForkOptions,走和代码路径完全相同的 forkSession() 流程。


Profile 注册模式

固定角色(静态 prompt)
typescript
profiles.register('poet', {
  systemPrompt: '你是一位诗人,所有回复用诗歌形式。',
  systemPromptMode: 'preset',
})

preset 模式让 LLM 传入的 systemPrompt 被忽略,保证角色不被覆盖。

动态模板(基于变量)
typescript
profiles.register('region-expert', {
  systemPromptFn: (vars) => `你是${vars.region}地区的留学专家。`,
  systemPromptMode: 'preset',
  skills: ['search', 'summarize'],
})

调用方传 profileVars: { region: '北美' } 生成具体 prompt。

基础约束(允许追加)
typescript
profiles.register('researcher', {
  systemPrompt: '你是研究助手,善于深入分析。',
  systemPromptMode: 'prepend',   // 允许 fork options 追加具体研究主题
  context: 'inherit',
})

LLM 在 prepend 模式下可通过 systemPrompt 参数补充具体任务约束,合成结果为 {profile}\n\n{task-specific}。


设计不变量(不会改的决策)

  1. 三类型同根 — SessionConfig / ForkProfile / EngineForkOptions 共享 6 字段基座;职责驱动的差异字段独立声明
  2. 四层顺序固定 — defaults → parent → profile → forkOptions,不允许调换或插入新层
  3. undefined 不覆盖 — 保证"某层不传"等价于"使用下层值"的直觉
  4. skills 显式 [] 能生效 — 与 undefined 区分,让"禁用"成为可表达的意图
  5. 只固化 systemPrompt + skills — 可序列化字段有限,其余字段每次 fork 现场合成
  6. root 是普通 session — root 的固化 systemPrompt/skills 通过 parent 层正常进入子 session 的合成链,没有任何特殊豁免
  7. topologyParentId 与 sourceSessionId 分离 — 编排层的拓扑策略和上下文继承是两个独立维度

© stello-agent, Apache-2.0. Rendered from Markdown: HTML in the file is shown as text, images as links, and headings moved down two levels. Raw file

Files

Just SKILL.md in .agents/skills/fork-design of stello-agent/stello.

Open the folder on GitHubat commit 3bc9493

Compare with similar skills

Fork Design next to the 5 skills that share the most tags, products or categories with it. Stars are the repository's; “used in” counts other GitHub owners with a copy.

Fork Design compared with similar skills
SkillStarsUsed inTokensAuto-checkLicenceRepo updated
Fork Design this skillstello-agent/stello112—~2kAutomated safety check: PassApache-2.0
Forkalpha-omega-security/scrutineer231—~3.3kAutomated safety check: PassMIT
Forking Pathsbrycewang-stanford/Auto-Empirical-Research-Skills4.5k—~2.4kAutomated safety check: PassCustom licence
Refresh Forkmarin-community/marin3.9k—~4.1kAutomated safety check: PassApache-2.0
Session Source Forkmvschwarz/openrig5.9k—~2.2kAutomated safety check: PassApache-2.0
Release Latex Forkzly2006/zhihu-plus-plus4.2k—~1.8kAutomated safety check: PassAGPL-3.0

Similar skills

  • Fork

    alpha-omega-security/scrutineer

    Stage a scanned repository into a private repo in the configured GitHub organisation.

    231 GitHub stars~3.3k tokensUpdated today
    SecurityAuto-check passed
  • Forking Paths

    brycewang-stanford/Auto-Empirical-Research-Skills

    Map the garden of forking paths for a concrete econometric design and turn it into a machine-readable design card that the specification-search engine can walk.

    4.5k GitHub stars~2.4k tokensUpdated 2 days ago
    Research & ScienceAuto-check passed
  • Refresh Fork

    marin-community/marin

    Refresh a named Marin external fork pin onto a newer upstream base using its configured descriptor and required end-to-end test.

    3.9k GitHub stars~4.1k tokensUpdated today
    Testing & QAAuto-check passed
  • Session Source Fork

    mvschwarz/openrig

    A skill your agent uses when authoring a rig spec member or rig expand payload that needs to start a new managed seat from a prior runtime conversation source — sessionsource: { mode: fork, ref: {…

    5.9k GitHub stars~2.2k tokensUpdated today
    Agent WorkflowsAuto-check passed
  • Release Latex Fork

    zly2006/zhihu-plus-plus

    Release the LaTeX fork used by Zhihu++. An agent skill from zly2006/zhihu-plus-plus.

    4.2k GitHub stars~1.8k tokensUpdated yesterday
    Documents & OfficeAuto-check passed
  • Fork Fleet

    aeonfun/aeon

    Fork divergence monitor - tracks where the fleet's active forks diverge in CODE (unique commits, new/modified skills) and CONFIG (enable/var/model/schedule vs upstream), gated on real change.

    767 GitHub stars~7.9k tokensUpdated today
    Auto-check passed

More from stello-agent/stello

All 12 skills in this repo
  • LLM Call Sites

    stello-agent/stello

    Stello 框架内所有 LLM 调用位置的消息结构速查。覆盖 Session 对话、compress、consolidate;应用层 reflection 调用由 orchestrator 自行决定。

    112 GitHub stars~793 tokensUpdated 2 mo ago
    Auto-check passed
  • Session Usage

    stello-agent/stello

    Session 对话单元的设计理念、上下文组装规则、memory / insight 槽位语义、单一 Session 模型与跨 Session 通信模型。

    112 GitHub stars~763 tokensUpdated 2 mo ago
    Auto-check passed
  • Stello Agent Creation

    stello-agent/stello

    StelloAgent 创建配置教程。完整说明 createStelloAgent 的每个配置项,包含 sessionDefaults、storage、tools、skills、forkProfiles、session 层接入、orchestration 等。

    112 GitHub stars~3.2k tokensUpdated 2 mo ago
    Auto-check passed
  • Stello Agent Usage

    stello-agent/stello

    StelloAgent 运行时使用教程。覆盖 Session 生命周期、createSession、turn/stream 对话、fork 配置合成链、orchestrator-facing 数据 SDK、runtime 管理、热更新等运行时 API。

    112 GitHub stars~2.7k tokensUpdated 2 mo ago
    Auto-check passed
  • Stello Usage

    stello-agent/stello

    Stello 仓库总览入口。快速理解各包的关系、推荐入口、编排模型、单一 Session 模型. An agent skill from stello-agent/stello.

    112 GitHub stars~547 tokensUpdated 2 mo ago
    Auto-check passed
  • Storage Design

    stello-agent/stello

    存储接口的设计原则、SessionMeta 与 TopologyNode 解耦、上下文槽位、单一 SessionStorage 接口。触发条件:理解或实现 SessionStorage / SessionTree。

    112 GitHub stars~871 tokensUpdated 2 mo ago
    Auto-check passed

Questions about Fork Design

What does Fork Design do?

Fork 机制完整说明。覆盖 ForkProfile 与 EngineForkOptions 的字段对齐、四层 fallback 合成链(sessionDefaults → parent → profile → forkOptions)、systemPrompt 合成三种模式、skills 三态语义、持久化边界(SerializableSessionConfig 只固化…. Fork Design is an agent skill from stello-agent/stello.

How do I install Fork Design in Claude Code?

Run `npx skills add stello-agent/stello --skill fork-design -a claude-code`. Or copy the skill folder (.agents/skills/fork-design in stello-agent/stello) into .claude/skills/fork-design in your project. Claude Code loads it when a task matches its description.

How do I install Fork Design in Codex?

Run `npx skills add stello-agent/stello --skill fork-design -a codex`. Or copy the skill folder (.agents/skills/fork-design in stello-agent/stello) into .agents/skills/fork-design in your project. Codex loads it when a task matches its description.

Can I use Fork Design in Cursor, Gemini CLI or GitHub Copilot?

Cursor, Gemini CLI, GitHub Copilot and OpenCode also load SKILL.md folders. With the skills CLI, run `npx skills add stello-agent/stello --skill fork-design -a cursor` (or -a gemini-cli, github-copilot or opencode for the others). To copy it by hand, put the folder in .cursor/skills/fork-design, .gemini/skills/fork-design, .github/skills/fork-design and .opencode/skills/fork-design in your project.

What does Fork Design need to run?

SKILL.md names no scripts, command-line tools or credentials: Fork Design is instructions for the agent only.

Does Fork Design access the network?

SKILL.md contains no URLs. Any network use would come from the scripts or tools the agent runs. This is read from the text; nothing was executed.

Is Fork Design safe to install?

Our automated static check of SKILL.md found no risky patterns, such as piping downloads into a shell, reading credential files or hidden Unicode. It is not a guarantee. Review the folder before installing.

What licence does Fork Design use?

Fork Design is published under the Apache-2.0 licence (the repository's licence). It allows redistribution, so the full SKILL.md is shown on this page.

How many tokens does Fork Design use?

About 2k tokens (SKILL.md is roughly 7.9k characters). Agents keep only the skill's name and description in context until a task matches; then they load SKILL.md in full.

What are the alternatives to Fork Design?

Skills that share tags, products or a category with Fork Design: Fork (alpha-omega-security/scrutineer, 231 stars), Forking Paths (brycewang-stanford/Auto-Empirical-Research-Skills, 4.5k stars), Refresh Fork (marin-community/marin, 3.9k stars) and Session Source Fork (mvschwarz/openrig, 5.9k stars). The comparison table on this page puts their stars, adoption, token cost, safety result and licence side by side.

Who maintains Fork Design?

stello-agent (a GitHub organization) maintains it in stello-agent/stello, which has 112 GitHub stars. The repository holds 12 skills in this directory. The repository was last updated on July 24, 2026.

Source: stello-agent/stello on GitHub. Facts on this page come from the repository at the commit we read; the author's words are quoted as theirs.