`but agent setup` writes 40+ lines of command recipes into the always-loaded rules file, duplicating the on-demand skill

[blastart]

Version

but 0.22.3 (CLI symlinked from GitButler.app, macOS .dmg install)

Operating System

macOS

Agent

Claude Code

Describe the issue

but agent setup does two things in one wizard: it installs the skill (~/.claude/skills/gitbutler/) and it writes a managed block (<!-- gitbutler-agent-setup:start/end -->) into the agent's always-loaded instruction file (~/.claude/rules/gitbutler.md for Claude Code; AGENTS.md / CLAUDE.md / copilot-instructions.md for the other formats).

The managed block here is 42 lines / ~3 KB, and it is in the context of every request, in every repository — including repositories that are not GitButler projects at all. Meanwhile SKILL.md (212 lines) plus references/*.md (~59 KB) are loaded on demand, and they already cover the same ground.

The overlap is not incidental — the block restates the skill:

• the but diff → but commit -b <branch> -m "msg" <ids> fast path (SKILL.md "Start Here" / "Commit selected files or hunks")
• "add --status-after only when the next step needs it; don't re-verify with status/diff" (SKILL.md "Non-Negotiable Rules" Basic Local Recording #2)
• amend-into-the-right-commit and split-unrelated-changes guidance (SKILL.md "Amend into existing commit" / "Split an existing commit")
• and one bullet that literally says "Use the installed GitButler skill for command recipes and syntax" — i.e. the block itself points at the place where all of this already lives.

Besides the per-request cost, the duplication can drift: the block and the skill are separate texts that must be kept in sync (cf. #15540, #14290).

Second, related friction: repositories that are not GitButler projects

The block opens with "Use GitButler (but) for version-control inspection and write operations" with no fallback clause. In a repo that was never onboarded, the agent follows that instruction, runs but diff, and only then gets Setup required: No GitButler project found at . - run 'but setup' to configure the project. From there the wrong move (running but setup unprompted, reconfiguring the user's repo) is the one the instructions nudge toward. This is the instruction-side counterpart of #13406, which fixed the stop-hook error but not the steering text.

Suggested fix

1. Keep in the managed block only what is genuinely user-specific and always relevant — the wizard's actual preferences (branch naming pattern, commit message convention, draft-PR / ship-it phrase, checkpoint-commit behaviour) — plus one pointer: "load the gitbutler skill before running but". That is a handful of lines instead of 42.
2. Move the command recipes out of the block entirely; they are already in the skill.
3. Add one sentence for non-GitButler repositories: "If but reports Setup required, use plain git and do not run but setup without asking the user."
4. Offer a way to install the skill without the steering block (e.g. but agent setup --skill-only), for users who want the on-demand capability but not the always-on context cost.

Workaround used meanwhile

Removed the managed block and replaced it with a ~15-line policy that points at the skill. A future but agent setup run would presumably write it back.