Workflow skill
Dev Worktree Skill
Set up or resume the right workspace before feature work.
On this page
Install command
AI DevKit installs its built-in skills as one curated set. Run this once to install dev-worktree with the rest of the built-in workflow skills.
npx ai-devkit@latest skill add --built-inWhat it does
Use dev-worktree when starting, resuming, or switching feature work. It keeps workspace setup separate from implementation so agents begin from the correct branch, worktree, and repository context.
When to use it
- Start feature work in the right workspace
- Resume an existing lifecycle task
- Avoid mixing unrelated repository changes
Supported agents
- Claude Code
- Codex
- Cursor
- opencode
The SKILL.md file
This is what your agent reads when the skill runs. View it on GitHub (opens in a new tab)
Set up or resume the correct workspace before feature work. Keep this skill focused on repository context, worktree isolation, and dependency bootstrap. Do not perform requirements, design, planning, implementation, testing, or review work here.
Phase Contract#
- Propose the exact workspace plan before changing branch or worktree state.
- Confirm the target branch/worktree with the user before switching contexts.
- Use
feature-<name>for branch and worktree names, where<name>is normalized kebab-case without the prefix. - Prefer a project-local worktree at
<project-root>/.worktrees/feature-<name>. - Use no-worktree mode only when the user explicitly requests it.
- Run all follow-up commands in the verified target context.
Start Feature Workspace#
Use for a new feature start.
- Normalize feature name to kebab-case
<name>. - Determine the project root, the directory containing
.git. - If the user explicitly requests no worktree:
- Continue in the current repository and branch.
- Call out that branch/workspace isolation is reduced.
- Skip to dependency bootstrap.
- Otherwise use branch/worktree name
feature-<name>. - Ensure
.worktreesis listed in the project.gitignore; if not, add it. - If branch does not exist, run
git worktree add -b feature-<name> .worktrees/feature-<name>. - If branch exists and the target worktree does not, run
git worktree add .worktrees/feature-<name> feature-<name>. - If the target worktree already exists, reuse it after verifying it is clean enough for the requested work.
- Verify worktree context with
git -C .worktrees/feature-<name> branch --show-current; it must equalfeature-<name>. - Return the active workdir path for the next phase.
Resume Feature Workspace#
Use when continuing an existing feature.
- Check current branch with
git branch --show-current. - Check available worktrees with
git worktree list. - Prefer
<project-root>/.worktrees/feature-<name>when it exists. - Otherwise use branch
feature-<name>in the current repository. - Include the selected target in the plan and wait for approval before switching.
- After approval, run future phase commands in the selected context.
Dependency Bootstrap#
After selecting the target context:
- Detect ecosystem from lockfiles, manifests, and tooling configs.
- Prefer deterministic lockfile-based installs.
- Use the repository-native command:
- JavaScript/TypeScript:
npm ci,pnpm install --frozen-lockfile,yarn install --frozen-lockfile, orbun install --frozen-lockfile. - Python:
uv sync,poetry install --no-interaction,pipenv sync, orpip install -r requirements.txt. - Ruby:
bundle install. - Rust:
cargo fetch, orcargo buildwhen fetch-only is insufficient. - Go:
go mod download. - Java/Kotlin:
./gradlew dependencies,./gradlew build, or Maven equivalent.
- JavaScript/TypeScript:
- For workspaces whose packages resolve against built artifacts (for example
dist/output consumed via workspace aliases), run the repository build (for examplenpm run build) after install. Full-suite validation and commit hooks fail on stale or missing artifacts with errors that look like code regressions. State when the build was skipped and why. - If no dependency manager is clearly detectable, continue and state what was checked.
Output#
End with:
- Active workdir.
- Branch name.
- Whether worktree or no-worktree mode is active.
- Dependency bootstrap command run, or why it was skipped.
- Workspace build command run (when applicable), or why it was skipped.
- Any workspace risks or blockers.