Skip to content

Add create-worktree skill and .worktrees isolation#67490

Open
javiercn wants to merge 1 commit into
mainfrom
javiercn/create-worktree-skill
Open

Add create-worktree skill and .worktrees isolation#67490
javiercn wants to merge 1 commit into
mainfrom
javiercn/create-worktree-skill

Conversation

@javiercn

Copy link
Copy Markdown
Member

Summary

Agents frequently create a git worktree to work in. Done naively in this repo, a nested worktree pollutes the main checkout's git status, fails to build (empty submodules, no SDK), or risks inheriting the top-level build configuration. This PR adds a committed, project-local worktree convention plus a Copilot skill that teaches agents how to use it.

What's in here

  • .worktrees/ committed isolation (the convention):

    • .worktrees/.gitignore ignores every worktree subdirectory, so worktrees created under it never show up in the parent's git status (no per-clone .git/info/exclude needed).
    • .worktrees/.editorconfig (root = true), Directory.Build.props/.targets (empty <Project />), and NuGet.config (<clear/>) form a traversal ceiling so nothing under .worktrees/ climbs into the repo-root MSBuild/NuGet/editorconfig configuration.
  • .github/skills/create-worktree/SKILL.md — a knowledge-only skill (no scripts) covering the three repo-specific things plain git worktree knowledge misses:

    1. Create the worktree under .worktrees/<name> (and copy the barrier files if it is placed elsewhere in the repo).
    2. Initialize the submodules a fresh worktree leaves empty (MessagePack-CSharp, googletest).
    3. Share the main checkout's already-provisioned .dotnet SDK via a junction/symlink when global.json sdk.version matches, instead of re-downloading gigabytes.
  • eng/skill-evals/create-worktree/eval.vally.yaml + eng/skill-evals/skill-vs-baseline.experiment.yaml — a Vally A/B eval (baseline vs skill), matching the move to Vally for skill evals.

Why a worktree under .worktrees/ is isolated

A worktree is a full checkout, so its own root Directory.Build.props/.targets, global.json, and .editorconfig (root = true) terminate MSBuild/SDK/editorconfig discovery before it reaches the repo root (these are stop-at-first-match). NuGet.config is the one that merges up the tree, but the repo's <clear/> makes the worktree's own sources win. The committed .worktrees/ barrier files harden this for any loose content placed directly under .worktrees/.

Eval results (Vally, runs=5, claude-opus-4.6)

Stimulus Baseline With skill
Create a worktree to work on a branch 0/5 5/5
Avoid re-downloading the SDK per worktree 3/5 5/5
In-repo worktree config isolation 5/5 5/5
Build fails: missing submodule sources 5/5 5/5

The skill activates in every skilled run and wins the two action scenarios (worktree placement, SDK sharing); it is neutral where the unaided agent is already strong.

Run it from an isolated empty directory (the stimuli ask the agent to create a worktree, so it acts on the cwd):

mkdir /tmp/cw-eval && cd /tmp/cw-eval
vally experiment run <repo>/eng/skill-evals/skill-vs-baseline.experiment.yaml --output-dir .
@javiercn javiercn marked this pull request as ready for review June 30, 2026 14:34
@javiercn javiercn requested review from a team and wtgodbe as code owners June 30, 2026 14:34
Copilot AI review requested due to automatic review settings June 30, 2026 14:34
@javiercn javiercn force-pushed the javiercn/create-worktree-skill branch from 8285c01 to bb0861b Compare June 30, 2026 14:34
Adds a Copilot skill that creates fully isolated git worktrees for this
repo under .worktrees/<name>, plus the committed isolation that keeps
them out of git and buildable.

- .github/skills/create-worktree/SKILL.md: knowledge-only skill (nest the
  worktree under .worktrees/, initialize submodules, share the parent
  .dotnet SDK; copy the barrier files if the worktree is placed elsewhere
  in the repo).
- .worktrees/: committed nested .gitignore (keeps worktree subdirs out of
  the parent git status) plus MSBuild/NuGet/editorconfig traversal-barrier
  files so worktrees never inherit the top-level build configuration.
- eng/skill-evals/create-worktree/eval.vally.yaml + skills-vs-baseline.experiment.yaml:
  Vally A/B eval (baseline vs skill); the experiment globs every skill's
  eval and loads .github/skills/<skill> via ${eval.parent}.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

This PR introduces a repository-local convention for creating isolated git worktrees under .worktrees/, and adds a Copilot skill plus Vally evals to teach and measure the correct worktree setup for this repo (submodules + SDK reuse + config isolation).

Changes:

  • Add committed isolation “ceiling” files under .worktrees/ (.gitignore, .editorconfig, Directory.Build.props/.targets, NuGet.config) to prevent nested worktrees from polluting git status and from inheriting outer-repo configuration.
  • Add a knowledge-only Copilot skill (.github/skills/create-worktree/SKILL.md) describing the repo-specific worktree workflow (placement, submodule init, .dotnet linking).
  • Add Vally A/B evaluation specs to compare baseline vs skill-assisted behavior.

Reviewed changes

Copilot reviewed 8 out of 8 changed files in this pull request and generated 1 comment.

Show a summary per file
File Description
eng/skill-evals/skill-vs-baseline.experiment.yaml Defines the baseline vs skilled A/B experiment varying /environment/skills.
eng/skill-evals/create-worktree/eval.vally.yaml Capability eval stimuli/rubrics for worktree placement, submodule init, SDK reuse, and isolation explanation.
.worktrees/.gitignore Ignores all worktree directories under .worktrees/ while keeping the isolation files tracked.
.worktrees/.editorconfig Stops EditorConfig traversal at .worktrees/ for content placed directly under it.
.worktrees/Directory.Build.props MSBuild traversal ceiling for content placed directly under .worktrees/.
.worktrees/Directory.Build.targets MSBuild traversal ceiling for content placed directly under .worktrees/.
.worktrees/NuGet.config NuGet traversal ceiling intended to prevent repo-root config merging under .worktrees/.
.github/skills/create-worktree/SKILL.md Documents the repo-specific “create an isolated worktree” procedure for agents/users.
Comment thread .worktrees/NuGet.config
Comment on lines +2 to +13
<!-- Traversal ceiling: clears every inherited section so repo-root package
sources never merge into content placed directly under .worktrees/. -->
<configuration>
<config>
<clear />
</config>
<packageSources>
<clear />
</packageSources>
<packageSourceMapping>
<clear />
</packageSourceMapping>
@javiercn javiercn force-pushed the javiercn/create-worktree-skill branch from bb0861b to cf4827e Compare June 30, 2026 14:38
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

2 participants