agentleFS
haqalizhaqaliz/assay/.claude/skills/assay-worktrees/SKILL.md

assay-worktrees

Skill0 starsChanged 3 days agoApache-2.0View on GitHub

Isolate parallel work in the Assay repo using the Claude Code worktree layout. Use when starting a new bug/feature that should not collide with another running Claude session. Covers branch naming, worktree placement under .claude/worktrees, per-worktree uv setup, and cleanup.

  • Reads credentials

The file

We split this skill into the rules it gives an agent

4 rules. About 0 are common, 1 is distinctive, and 3 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈1

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 3

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    Don't use this for one-off file edits that finish in a single session.

    line 16
  2. Very specific:

    Verify ignore status any time: git check-ignore -v '.claude/worktrees/' (keep the trailing slash — a bare .claude/worktrees reports "not …

    line 29
  3. Very specific:

    Prefer origin/master (shared truth.

    line 47
  4. Very specific:

    No secrets/env files exist yet — the repo is docs-only.

    line 73

≈ “Common” is an estimate: at least 1 in 5 of the 372,429 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Assay Worktree Workflow

When to Use

  • Another Claude session is running on a different branch in Assay and you want to start a new bug/feature without colliding.
  • You want to run two branches side by side.
  • The primary checkout is dirty and switching branches would mix work.

Don't use this for one-off file edits that finish in a single session.

Layout — the official Claude Code pattern

Assay is a single repo. Worktrees live inside it at .claude/worktrees/<name>/. .claude/worktrees/ is already in .gitignore.

/Users/aliz/dev/at/assay/                                    ← primary (master)
/Users/aliz/dev/at/assay/.claude/worktrees/bug-12/           ← bug #12 worktree
/Users/aliz/dev/at/assay/.claude/worktrees/feat-skill-ingest/

Verify ignore status any time: git check-ignore -v '.claude/worktrees/' (keep the trailing slash — a bare .claude/worktrees reports "not ignored" when the directory doesn't exist yet, which is a false alarm, not a missing rule).

Branch naming convention

<type>/<id>/<owner> — owner is aliz. id is a GitHub issue number when there is one, otherwise a short descriptive slug.

  • bug/12/aliz
  • feat/skill-ingest/aliz
  • chore/pin-uv-version/aliz

Worktree dir name drops the slashes: <type>-<id> (e.g. bug-12, feat-skill-ingest).

The base branch is master

Assay's base branch is master. The remote is git@github.com:haqaliz/assay.git. Prefer origin/master (shared truth; the local ref may be stale), falling back to local master only if the remote ref isn't fetched:

git fetch origin master
git worktree add -b feat/skill-ingest/aliz .claude/worktrees/feat-skill-ingest origin/master

# fallback if the remote ref isn't fetched
git fetch origin master
git worktree add -b feat/skill-ingest/aliz .claude/worktrees/feat-skill-ingest origin/master

Creating a worktree

# from an existing branch you already pushed
git worktree add .claude/worktrees/feat-skill-ingest feat/skill-ingest/aliz

# via Claude Code's --worktree flag
claude --worktree feat-skill-ingest

The --worktree flag names the branch worktree-feat-skill-ingest, which won't match your issue/slug naming — create the branch first, then git worktree add with it.

Auto-copying gitignored config (.worktreeinclude)

No secrets/env files exist yet — the repo is docs-only. Once a .env exists for BYOK keys, create .worktreeinclude and list it, then copy manually for bare git worktree add (the include only runs via claude --worktree):

cp .env .claude/worktrees/feat-skill-ingest/   # only once such a file exists

Never copy captured sandbox traces, findings, or corpus cases between worktrees. They are run state tied to the run that produced them.

Per-worktree setup (Python core — uv)

cd .claude/worktrees/feat-skill-ingest
uv sync
uv run pytest
uv run assay --help

⚠️ Greenfield caveat: no pyproject.toml, no uv.lock, no src/ yet. uv sync fails until the Python core is scaffolded. If your work is the scaffolding, the failing test comes first. Skip this section for docs-only work.

Switching between worktrees

git -C /Users/aliz/dev/at/assay worktree list

Cleaning up

git -C /Users/aliz/dev/at/assay worktree remove .claude/worktrees/feat-skill-ingest
git -C /Users/aliz/dev/at/assay branch -d feat/skill-ingest/aliz

Common pitfalls

SymptomCauseFix
invalid reference: origin/masterRemote not fetched, or doesn't exist yetBranch from local master until a remote exists
Branching from masterAssay's base branch is masterUse master
Worktree contents appear untracked in primary.claude/worktrees/ not ignoredAlready in .gitignore; verify with trailing slash
uv sync fails: no pyproject.tomlCore not scaffolded (greenfield)Expected — scaffold it test-first, or skip for docs-only work
git worktree add fails: "already checked out"Branch checked out elsewheregit checkout master in the conflicting worktree, retry

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.