Role
You areExperimental Handoffthe executor of. When you need to try features/run tests midway through a project:isolate a sandbox(worktree/branch/copy), write a small experiment document and hand it off to the next agent/session, and once the experiment has a conclusion,merge the verified changes back into the main project or discard them, and clean up the sandbox.
Parallel to project-handoff(Project State Handoff): this skill only handlesa single experiment's isolation and reclamation,self-contained—it does not depend on other skills' scripts or files.
When to use (mounted · user manual only /experiment-handoff)
This skillis mounted(~/.agents/skills/experiment-handoff, the user can invoke it with /experiment-handoff ), but the agent must not trigger it autonomously—it only executes when the user explicitly invokes it:
- Trigger method: the user types
/experiment-handoff(or explicitly names the skill);manual only。 - Three manual steps: ① the user
/invokethis skill ② the user manually hands the session off to another agent ③ the user manually declares the experiment finished. - Everything else is automatic: detect VCS, choose an isolation strategy, create the isolation, write documents/index, record the baseline, merge back to main, clean up.
Hard constraints
- Isolation first—experimental changesmust not pollute the main working tree; always go into a sandbox first.
- Conclusion-driven merge—write
结论/反馈first, then decide the merge scope (full/partial/discard); do not merge first and add the conclusion later. - Rollback-capable—record the baseline (commit/snapshot hash) before merging; run verification after merging, and roll back if it fails.
- Must clean up—on wrap-up, always delete the sandbox (worktree/branch/copy) and temporary branches; leave no residue.
- Anti-bloat—experiment documents are small (≤~600 tokens); migrate on wrap-up
archive/; active experiments ≤10 (archive first if exceeded). - Desensitization—documents must not contain API Keys/passwords/PII.
Isolation strategy (agent chooses automatically)
| Project state | Strategy | Implementation |
|---|---|---|
git repo,git worktree available, main tree clean |
worktree (default) | sibling directory ../<proj>-exp-<slug> + branch exp/<slug>(not nested inside the main tree) |
| git repo, main tree has uncommitted changes | commit/stash first → worktree | worktree cannot seeuncommitted changes |
| git repo, small changes in place | branch(--mode branch) |
switch directly to exp/<slug> |
| no git / no commit (unborn HEAD) | copy | copy to ../<proj>-exp-<slug>, exclude node_modules/dist/.venv/target/.next/.git; record snapshot hash |
| sandbox on external drive/may be unmounted | git worktree lock |
prevent accidental prune |
worktree independent dependencies each(no node_modules)—install is required after creation (pnpm shared store can save this).
Handoff document
- Location:
<项目>/.experiments/<slug>.md(local private, automatically adds.gitignore); index.experiments/EXPERIMENTS.md(auto-generated, do not edit manually). - Fields (per spike template: Goal→Method→Evidence→Conclusions→Next Steps):
- 状态: open | running | concluded | promoted | discarded
- 日期 / 标题
- Goal: 一句话问题/假设
- Method: 方法
- 隔离: <worktree|branch|copy> · 位置: <path> · 分支: <exp/slug 或 ->
- 基线: <commit 短 hash 或 copy 快照 hash>
- Run: 命令
- 结论: <反馈——合并依据>
- Next Steps:
- 合并计划: 全量 | 部分(<paths>) | 丢弃
- 合并结果: <merge commit / patch 文件 / 未合并>
- 清理: <命令>
## Evidence(追加式:测试/指标/观察)
Workflow
【手动触发 1】开
- [ ] 1. 探测:git 仓?worktree 可用?主树干净?(无 git → copy)
- [ ] 2. 选隔离策略(见上表),建沙箱(worktree/branch/copy)
- [ ] 3. 写 .experiments/<slug>.md(含基线)+ 生成索引
- [ ] 4. (worktree)cd 沙箱 && install 依赖
【手动触发 2】续 / 交办
- [ ] 5. 读文档 → 若文档里的基线 commit 已前进,先确认是否需要重取基线 / 重新隔离
- [ ] 6. 进沙箱继续实验,Evidence 追加
【手动触发 3】收
- [ ] 7. 填 结论/反馈 → 定合并计划(全量/部分/丢弃)
- [ ] 8. 合并回主:git 系 `merge`/`cherry-pick`(部分用 `git checkout exp/<slug> -- <paths>`);copy 系生成补丁后应用
- [ ] 9. 合并后:跑测试 → 按项目交接约定留一行引用(`project-handoff`;不复制)
- [ ] 10. 清理沙箱 + 归档文档(状态 promoted/discarded)
Merge back to main project (feedback-driven)
| Isolation method | Merge method |
|---|---|
| worktree / branch | git merge --no-ff exp/<slug>(or cherry-pick); partial merge:git checkout exp/<slug> -- <paths> |
| copy (non-git) | generate patch (script uses diff -ruN or git diff --no-index) → after review git apply -p1 / patch -p1 |
- Granularity: full / partial (only verified files) / discard—determined by
结论. - Rollback: the hash of the baseline before merge is the rollback anchor (
git reset --hard <base>/git revert); for copy-based, the original copy still exists and can be redone. - Trace: after success, leave one line per project handoff convention reference(commit/patch path;
project-handoffmaintained), do not copy content.
Anti-bloat
- Closing means
mvto.experiments/archive/; the index automatically distinguishes active/archived. - Active experiments >10 →
listalert, archive/close old ones first. - Keep documents small; put large evidence into project docs (just reference it).
Bundled scripts
| Script | Platform | Description |
|---|---|---|
scripts/experiment.sh |
Linux / macOS / WSL / Git Bash | init(create isolation + docs) / close(merge + cleanup + archive) / list |
scripts/experiment.ps1 |
Windows PowerShell 5.1+(UTF-8 with BOM) | same behavior; parameters are positional (-File under --x will be treated as a parameter name) |
Zero python/node dependencies (bash uses coreutils+git+tar; PS uses built-ins + git/tar). Usage:
scripts/experiment.sh init <slug> [--title T] [--mode worktree|branch|copy] [--base REF]
scripts/experiment.sh close <slug> --keep|--discard [--paths p1,p2]
scripts/experiment.sh list
experiment.ps1 init <slug> [title] [mode] [base]
experiment.ps1 close <slug> keep|discard [paths]
experiment.ps1 list [write]
Anti-patterns
- Experiment changes go directly into the main working tree (no isolation) → pollutes the mainline
- Merge first, then add conclusions (no feedback basis)
- Do not record baseline before merge (cannot roll back)
- Closing does not clean up sandbox/branch (residual bloat)
- Experiment docs written as a giant encyclopedia (over budget, not archived)
- agent Autonomous invocationthis skill (should wait for user
/experiment-handoff) - Depends on scripts/files of other skills(this skill must be self-contained)
Completion criteria
- sandbox created and main tree not polluted (one of worktree/branch/copy)
- explicitly triggered by user
/experiment-handoff(not autonomously invoked by agent) -
.experiments/<slug>.mdexists (including Goal/Method/baseline/conclusions/merge plan/merge result/cleanup) - index
.experiments/EXPERIMENTS.mdgenerated - closing: merge or discard per conclusions; after merge, verify + reference one line per project handoff convention
- sandbox/branch cleaned up; docs migrated
archive/ - no sensitive information
Methodology sources (2026-09 research)
- Technical Spike template(Microsoft Engineering Playbook): Goal / Method / Evidence / Conclusions / Next Steps—source of this skill's document fields
- Git worktree best practices(GitWorktree.org): sibling directory layout,
<project>-<branch-slug>naming, after mergegit worktree remove+prune, each worktree has independent dependencies — source of the isolation strategy - Agent handoff pattern(Microsoft Agent Framework / AutoGen): explicitly hand over control — source of the manual three-stage trigger model