diff --git a/apps/desktop/src/components/settings/AgentSetupModalContent.svelte b/apps/desktop/src/components/settings/AgentSetupModalContent.svelte
new file mode 100644
index 00000000000..295835a9b81
--- /dev/null
+++ b/apps/desktop/src/components/settings/AgentSetupModalContent.svelte
@@ -0,0 +1,236 @@
+<script lang="ts">
+	import CliInstallCard from "$components/settings/CliInstallCard.svelte";
+	import { AGENTS_SERVICE } from "$lib/agents/agentsService";
+	import { CLI_MANAGER } from "$lib/config/cli";
+	import { SETTINGS_SERVICE } from "$lib/settings/appSettings";
+	import { inject } from "@gitbutler/core/context";
+	import { Button, Checkbox, ModalFooter, ModalHeader, chipToasts } from "@gitbutler/ui";
+	import type { AgentSetupModalState } from "$lib/state/uiState.svelte";
+	import type { AgentFramework, SkillScope } from "@gitbutler/but-sdk";
+
+	type Props = {
+		data: AgentSetupModalState;
+		close: () => void;
+	};
+
+	const { data, close }: Props = $props();
+
+	const agentsService = inject(AGENTS_SERVICE);
+	const settingsService = inject(SETTINGS_SERVICE);
+	const cliManager = inject(CLI_MANAGER);
+
+	const cliState = cliManager.state();
+	const status = $derived(agentsService.status({ projectId: data.projectId }));
+	const [installSkill, installing] = agentsService.installSkill;
+
+	type Step = "cli" | "agents" | "scope" | "review";
+
+	let step = $state<Step>("cli");
+	let selectedIds = $state<string[]>([]);
+	let scope = $state<SkillScope>("global");
+	let seeded = false;
+
+	const cliReady = $derived(!!cliState.response?.installed || !!cliState.response?.blockedReason);
+	const frameworks = $derived(status.response?.frameworks ?? []);
+
+	// Pre-select the agents we can see the user already works with, matching
+	// what `but agent setup` does. Seeded once so a background refetch cannot
+	// undo the user's own ticks.
+	$effect(() => {
+		if (seeded || frameworks.length === 0) return;
+		seeded = true;
+		selectedIds = frameworks
+			.filter((framework: AgentFramework) => framework.detectedGlobally || framework.detectedInRepo)
+			.map((framework: AgentFramework) => framework.id);
+		if (cliReady && step === "cli") step = "agents";
+	});
+
+	const eligible = $derived(
+		frameworks.filter((framework: AgentFramework) =>
+			framework.scopes.some((entry) => entry.scope === scope),
+		),
+	);
+	const chosen = $derived(
+		eligible.filter((framework: AgentFramework) => selectedIds.includes(framework.id)),
+	);
+
+	function toggle(id: string) {
+		selectedIds = selectedIds.includes(id)
+			? selectedIds.filter((entry) => entry !== id)
+			: [...selectedIds, id];
+	}
+
+	async function apply() {
+		for (const framework of chosen) {
+			await installSkill({ frameworkId: framework.id, scope, projectId: data.projectId });
+		}
+		// Completing setup answers the prompt, so it should not be asked again
+		// even if the user only set up one scope.
+		await settingsService.updateAgents({ skillsPromptDismissed: true });
+		chipToasts.success(
+			`Installed the GitButler skill for ${chosen.length} agent${chosen.length === 1 ? "" : "s"}`,
+		);
+		close();
+	}
+</script>
+
+<ModalHeader>Set up GitButler for your coding agents</ModalHeader>
+
+<div class="wizard">
+	<div class="step-section">
+		<div class="step-line" class:step-line-default={step !== "cli"}></div>
+		<div class="step-section__content">
+			<h4 class="text-14 text-semibold">1. Install the <code>but</code> CLI</h4>
+			<p class="text-12 clr-text-2">
+				Your agent runs <code>but</code> to branch, commit, and open pull requests.
+			</p>
+			{#if step === "cli"}
+				<CliInstallCard />
+				<div class="flex justify-end m-t-8">
+					<Button kind="outline" onclick={() => (step = "agents")}>
+						{cliReady ? "Continue" : "Skip for now"}
+					</Button>
+				</div>
+			{/if}
+		</div>
+	</div>
+
+	{#if step !== "cli"}
+		<div class="step-section">
+			<div class="step-line" class:step-line-default={step !== "agents"}></div>
+			<div class="step-section__content">
+				<h4 class="text-14 text-semibold">2. Choose your agents</h4>
+				{#if step === "agents"}
+					<p class="text-12 clr-text-2">Detected agents are already ticked.</p>
+					<div class="flex flex-col gap-8 m-t-8">
+						{#each frameworks as framework (framework.id)}
+							<div class="flex gap-8 items-center">
+								<Checkbox
+									id="agent-{framework.id}"
+									checked={selectedIds.includes(framework.id)}
+									onchange={() => toggle(framework.id)}
+								/>
+								<label for="agent-{framework.id}" class="text-13">
+									{framework.name}
+									{#if framework.detectedGlobally || framework.detectedInRepo}
+										<span class="clr-text-2">— detected</span>
+									{/if}
+								</label>
+							</div>
+						{/each}
+					</div>
+					<div class="flex justify-end gap-8 m-t-8">
+						<Button kind="outline" onclick={() => (step = "cli")}>Back</Button>
+						<Button
+							style="pop"
+							disabled={selectedIds.length === 0}
+							onclick={() => (step = data.projectId ? "scope" : "review")}>Continue</Button
+						>
+					</div>
+				{/if}
+			</div>
+		</div>
+	{/if}
+
+	{#if data.projectId && (step === "scope" || step === "review")}
+		<div class="step-section">
+			<div class="step-line" class:step-line-default={step !== "scope"}></div>
+			<div class="step-section__content">
+				<h4 class="text-14 text-semibold">3. Where should this apply?</h4>
+				{#if step === "scope"}
+					<div class="flex flex-col gap-8 m-t-8">
+						<label class="text-13 flex gap-8 items-center">
+							<input type="radio" bind:group={scope} value="global" />
+							All my projects
+						</label>
+						<label class="text-13 flex gap-8 items-center">
+							<input type="radio" bind:group={scope} value="repository" />
+							Just this project
+						</label>
+					</div>
+					<div class="flex justify-end gap-8 m-t-8">
+						<Button kind="outline" onclick={() => (step = "agents")}>Back</Button>
+						<Button style="pop" onclick={() => (step = "review")}>Continue</Button>
+					</div>
+				{/if}
+			</div>
+		</div>
+	{/if}
+
+	{#if step === "review"}
+		<div class="step-section">
+			<div class="step-line step-line-last"></div>
+			<div class="step-section__content">
+				<h4 class="text-14 text-semibold">Review</h4>
+				<p class="text-12 clr-text-2">These files will be written:</p>
+				<ul class="paths">
+					{#each chosen as framework (framework.id)}
+						{@const entry = framework.scopes.find((item) => item.scope === scope)}
+						{#if entry}
+							<li><code class="code-string">{entry.skillPath}</code></li>
+						{/if}
+					{/each}
+				</ul>
+				{#if chosen.length === 0}
+					<p class="text-12 clr-text-2">None of the agents you picked can install at this scope.</p>
+				{/if}
+			</div>
+		</div>
+	{/if}
+</div>
+
+<ModalFooter>
+	<Button kind="outline" onclick={close}>Cancel</Button>
+	{#if step === "review"}
+		<Button
+			style="pop"
+			disabled={chosen.length === 0}
+			loading={installing.current.isLoading}
+			onclick={apply}>Set up</Button
+		>
+	{/if}
+</ModalFooter>
+
+<style lang="postcss">
+	.wizard {
+		display: flex;
+		flex-direction: column;
+		padding: 16px;
+		gap: 4px;
+	}
+
+	.step-section {
+		display: flex;
+		position: relative;
+		gap: 12px;
+	}
+
+	.step-line {
+		width: 2px;
+		border-radius: 1px;
+		background-color: var(--clr-border-3);
+	}
+
+	.step-line-default {
+		background-color: var(--clr-theme-pop-element);
+	}
+
+	.step-line-last {
+		background-color: var(--clr-theme-pop-element);
+	}
+
+	.step-section__content {
+		display: flex;
+		flex: 1;
+		flex-direction: column;
+		padding-bottom: 16px;
+		gap: 4px;
+	}
+
+	.paths {
+		display: flex;
+		flex-direction: column;
+		margin-top: 4px;
+		gap: 4px;
+	}
+</style>
diff --git a/apps/desktop/src/components/settings/AgentSetupPrompt.svelte b/apps/desktop/src/components/settings/AgentSetupPrompt.svelte
new file mode 100644
index 00000000000..12d96a3b728
--- /dev/null
+++ b/apps/desktop/src/components/settings/AgentSetupPrompt.svelte
@@ -0,0 +1,66 @@
+<script lang="ts">
+	import { AGENTS_SERVICE } from "$lib/agents/agentsService";
+	import { markAgentPromptEvaluated } from "$lib/agents/setupPrompt";
+	import { BACKEND } from "$lib/backend";
+	import { CLI_MANAGER } from "$lib/config/cli";
+	import { showToast } from "$lib/notifications/toasts";
+	import { SETTINGS_SERVICE } from "$lib/settings/appSettings";
+	import { UI_STATE } from "$lib/state/uiState.svelte";
+	import { inject } from "@gitbutler/core/context";
+	import { onMount } from "svelte";
+	import type { AgentFramework } from "@gitbutler/but-sdk";
+
+	// Injection must happen during component init, not inside onMount.
+	const backend = inject(BACKEND);
+	const settingsService = inject(SETTINGS_SERVICE);
+	const cliManager = inject(CLI_MANAGER);
+	const agentsService = inject(AGENTS_SERVICE);
+	const uiState = inject(UI_STATE);
+
+	onMount(async () => {
+		if (!markAgentPromptEvaluated()) return;
+		if (backend.platformName === "web") return;
+
+		try {
+			const settings = await settingsService.fetchAppSettings();
+			// Don't interrupt first-run onboarding, and never re-ask.
+			if (!settings.onboardingComplete) return;
+			if (settings.agents?.skillsPromptDismissed) return;
+
+			// Promise-based reads, not useQuery: this component renders nothing,
+			// so a subscription would never be released and an effect would fire
+			// once while still loading and again with data.
+			const [cli, status] = await Promise.all([
+				cliManager.fetchState(),
+				agentsService.fetchStatus({}),
+			]);
+
+			const cliMissing = !cli.installed && !cli.blockedReason;
+			const noSkills = status.frameworks.every((framework: AgentFramework) =>
+				framework.scopes.every((entry) => !entry.installed),
+			);
+			if (!cliMissing && !noSkills) return;
+
+			showToast({
+				style: "info",
+				title: "Set up GitButler for your coding agent",
+				message:
+					"Install the `but` CLI and the GitButler skill so your agent can branch, commit, and open pull requests the way you want.",
+				dismissLabel: "Don't ask again",
+				extraAction: {
+					label: "Enable agent skills",
+					onClick: (dismiss) => {
+						uiState.global.modal.set({ type: "agent-setup" });
+						dismiss();
+					},
+				},
+				onDismiss: async () => {
+					await settingsService.updateAgents({ skillsPromptDismissed: true });
+				},
+			});
+		} catch (err: unknown) {
+			// A nudge is never worth blocking startup over.
+			console.error("Agent setup prompt check failed", err);
+		}
+	});
+</script>
diff --git a/apps/desktop/src/components/settings/AgentSkillList.svelte b/apps/desktop/src/components/settings/AgentSkillList.svelte
new file mode 100644
index 00000000000..fd3e16563e2
--- /dev/null
+++ b/apps/desktop/src/components/settings/AgentSkillList.svelte
@@ -0,0 +1,122 @@
+<script lang="ts">
+	import AgentSkillRow from "$components/settings/AgentSkillRow.svelte";
+	import { AGENTS_SERVICE } from "$lib/agents/agentsService";
+	import { inject } from "@gitbutler/core/context";
+	import { Button, CardGroup } from "@gitbutler/ui";
+	import type { AgentFramework, FrameworkScopeState, SkillScope } from "@gitbutler/but-sdk";
+
+	type Props = {
+		scope: SkillScope;
+		projectId?: string;
+	};
+
+	const { scope, projectId }: Props = $props();
+
+	const agentsService = inject(AGENTS_SERVICE);
+	const status = $derived(agentsService.status({ projectId }));
+
+	const [updateSkills, updatingAll] = agentsService.updateSkills;
+
+	let showAll = $state(false);
+
+	/** Only frameworks that can install at this scope; some agents are global-only. */
+	const available = $derived(
+		(status.response?.frameworks ?? []).filter((framework: AgentFramework) =>
+			framework.scopes.some((entry: FrameworkScopeState) => entry.scope === scope),
+		),
+	);
+
+	const detected = $derived(
+		available.filter((framework: AgentFramework) =>
+			scope === "global" ? framework.detectedGlobally : framework.detectedInRepo,
+		),
+	);
+
+	/**
+	 * An installed skill keeps its row visible even when the agent is no longer
+	 * detected, so a skill can always be uninstalled from where it was installed.
+	 */
+	const installedButUndetected = $derived(
+		available.filter(
+			(framework: AgentFramework) =>
+				!detected.includes(framework) &&
+				framework.scopes.some(
+					(entry: FrameworkScopeState) => entry.scope === scope && entry.installed,
+				),
+		),
+	);
+
+	const alwaysShown = $derived([...detected, ...installedButUndetected]);
+	const rest = $derived(
+		available.filter((framework: AgentFramework) => !alwaysShown.includes(framework)),
+	);
+	const shown = $derived(showAll ? [...alwaysShown, ...rest] : alwaysShown);
+
+	/**
+	 * Counted across every framework, not just the visible ones, so a skill
+	 * hidden behind "Show all" is still covered by "Update all".
+	 */
+	const outdatedCount = $derived(
+		available.filter((framework: AgentFramework) =>
+			framework.scopes.some(
+				(entry: FrameworkScopeState) =>
+					entry.scope === scope && entry.installed && !entry.installed.upToDate,
+			),
+		).length,
+	);
+</script>
+
+{#if outdatedCount > 0}
+	<div class="update-all">
+		<span class="text-12 clr-text-2">
+			{outdatedCount}
+			{outdatedCount === 1 ? "skill is" : "skills are"} out of date.
+		</span>
+		<Button
+			style="pop"
+			icon="refresh"
+			loading={updatingAll.current.isLoading}
+			onclick={() => updateSkills({ scope, projectId })}
+		>
+			Update all
+		</Button>
+	</div>
+{/if}
+
+<CardGroup>
+	{#if status.response && alwaysShown.length === 0 && !showAll}
+		<CardGroup.Item>
+			{#snippet title()}No coding agents detected{/snippet}
+			{#snippet caption()}
+				GitButler looks for each agent's config to decide what to show here. Choose "Show all
+				agents" to install a skill anyway.
+			{/snippet}
+		</CardGroup.Item>
+	{/if}
+
+	{#each shown as framework (framework.id)}
+		<AgentSkillRow {framework} {scope} {projectId} />
+	{/each}
+</CardGroup>
+
+{#if rest.length > 0}
+	<div class="flex justify-center m-t-12">
+		<Button kind="ghost" onclick={() => (showAll = !showAll)}>
+			{showAll ? "Show detected agents only" : `Show all agents (${rest.length} more)`}
+		</Button>
+	</div>
+{/if}
+
+<style lang="postcss">
+	.update-all {
+		display: flex;
+		align-items: center;
+		justify-content: space-between;
+		margin-bottom: 12px;
+		padding: 10px 12px;
+		gap: 12px;
+		border: 1px solid var(--clr-border-2);
+		border-radius: var(--radius-m);
+		background-color: var(--clr-bg-2);
+	}
+</style>
diff --git a/apps/desktop/src/components/settings/AgentSkillRow.svelte b/apps/desktop/src/components/settings/AgentSkillRow.svelte
new file mode 100644
index 00000000000..3618b586374
--- /dev/null
+++ b/apps/desktop/src/components/settings/AgentSkillRow.svelte
@@ -0,0 +1,124 @@
+<script lang="ts">
+	import AgentWorkflowPolicyModal from "$components/settings/AgentWorkflowPolicyModal.svelte";
+	import { AGENTS_SERVICE } from "$lib/agents/agentsService";
+	import { inject } from "@gitbutler/core/context";
+	import { Badge, Button, CardGroup, Tooltip } from "@gitbutler/ui";
+	import type { AgentFramework, FrameworkScopeState, SkillScope } from "@gitbutler/but-sdk";
+
+	type Props = {
+		framework: AgentFramework;
+		scope: SkillScope;
+		projectId?: string;
+	};
+
+	const { framework, scope, projectId }: Props = $props();
+
+	const agentsService = inject(AGENTS_SERVICE);
+	// One mutation hook per row, so only the row being changed shows a spinner.
+	const [installSkill, installing] = agentsService.installSkill;
+	const [uninstallSkill, uninstalling] = agentsService.uninstallSkill;
+	const [updateSkills, updating] = agentsService.updateSkills;
+
+	const scopeState = $derived(
+		framework.scopes.find((entry: FrameworkScopeState) => entry.scope === scope),
+	);
+	const detected = $derived(
+		scope === "global" ? framework.detectedGlobally : framework.detectedInRepo,
+	);
+
+	let policyModal = $state<AgentWorkflowPolicyModal>();
+</script>
+
+{#if scopeState}
+	<CardGroup.Item>
+		{#snippet title()}
+			<span class="flex gap-6 items-center">
+				{framework.name}
+				{#if detected}
+					<Badge style="pop">Detected</Badge>
+				{/if}
+				{#if scopeState.installed && !scopeState.installed.upToDate}
+					<Tooltip text="Installed version {scopeState.installed.version} is out of date.">
+						<Badge style="warning">Outdated</Badge>
+					</Tooltip>
+				{/if}
+			</span>
+		{/snippet}
+
+		{#snippet caption()}
+			{#if scopeState.installed}
+				<code class="code-string skill-path">{scopeState.installed.path}</code>
+			{:else}
+				{framework.description}
+			{/if}
+		{/snippet}
+
+		{#snippet actions()}
+			<!--
+				The shared actions column neither adds a gap nor stops itself
+				shrinking, so three labelled buttons overflow the card. Only the
+				action worth reading stays labelled; the rest are icon-only with
+				tooltips.
+			-->
+			<div class="row-actions">
+				{#if scopeState.installed}
+					{#if !scopeState.installed.upToDate}
+						<Button
+							style="pop"
+							icon="refresh"
+							loading={updating.current.isLoading}
+							onclick={() => updateSkills({ frameworkId: framework.id, scope, projectId })}
+						>
+							Update
+						</Button>
+					{/if}
+					{#if scopeState.instructionPath}
+						<Tooltip text="Customize workflow preferences">
+							<Button kind="outline" icon="settings" onclick={() => policyModal?.show()} />
+						</Tooltip>
+					{/if}
+					<Tooltip text="Uninstall this skill">
+						<Button
+							kind="outline"
+							style="danger"
+							icon="bin"
+							loading={uninstalling.current.isLoading}
+							onclick={() => uninstallSkill({ frameworkId: framework.id, scope, projectId })}
+						/>
+					</Tooltip>
+				{:else}
+					<Button
+						style="pop"
+						icon="plus"
+						loading={installing.current.isLoading}
+						onclick={() => installSkill({ frameworkId: framework.id, scope, projectId })}
+					>
+						Install
+					</Button>
+				{/if}
+			</div>
+		{/snippet}
+	</CardGroup.Item>
+
+	<AgentWorkflowPolicyModal bind:this={policyModal} {scope} {projectId} />
+{/if}
+
+<style lang="postcss">
+	.row-actions {
+		display: flex;
+		flex-shrink: 0;
+		align-items: center;
+		gap: 6px;
+	}
+
+	/* A long path would otherwise set the content column's min width and
+	   squeeze the actions off the card. */
+	.skill-path {
+		display: inline-block;
+		max-width: 100%;
+		overflow: hidden;
+		text-overflow: ellipsis;
+		vertical-align: bottom;
+		white-space: nowrap;
+	}
+</style>
diff --git a/apps/desktop/src/components/settings/AgentWorkflowPolicyModal.svelte b/apps/desktop/src/components/settings/AgentWorkflowPolicyModal.svelte
new file mode 100644
index 00000000000..b3cd6d120af
--- /dev/null
+++ b/apps/desktop/src/components/settings/AgentWorkflowPolicyModal.svelte
@@ -0,0 +1,243 @@
+<script lang="ts">
+	import { AGENTS_SERVICE } from "$lib/agents/agentsService";
+	import { inject } from "@gitbutler/core/context";
+	import { Button, Checkbox, Modal, Textbox, Tooltip } from "@gitbutler/ui";
+	import type {
+		PolicyOptions,
+		SkillScope,
+		WorkflowOptionId,
+		WorkflowOptionInfo,
+	} from "@gitbutler/but-sdk";
+
+	type Props = {
+		scope: SkillScope;
+		projectId?: string;
+	};
+
+	const { scope, projectId }: Props = $props();
+
+	const agentsService = inject(AGENTS_SERVICE);
+	const policy = $derived(agentsService.policy({ scope, projectId }));
+	const [savePolicy, saving] = agentsService.setPolicy;
+
+	let modal = $state<Modal>();
+
+	// Local edit buffer, seeded from the installed policy each time the modal
+	// opens. Not derived: the user's in-progress edits must survive a
+	// background refetch of the query behind it.
+	let selected = $state<WorkflowOptionId[]>([]);
+	let publishPhrase = $state("ship it");
+	let branchPattern = $state("");
+	let commitConvention = $state("");
+
+	let open = $state(false);
+	// Plain variable, not $state: the effect below both reads and writes it,
+	// and it must not retrigger itself.
+	let seeded = false;
+
+	const policyState = $derived(policy.response);
+	/** Options are described by the backend so the wording lives in one place. */
+	const available = $derived(policyState?.available ?? []);
+
+	/**
+	 * Options collected under their group heading.
+	 *
+	 * Built by bucketing rather than by watching for the group to change
+	 * between neighbours: the backend sends options in the order the CLI
+	 * wizard presents them, which interleaves groups, so the naive approach
+	 * repeats a heading every time the sequence returns to a group.
+	 * Group order follows first appearance, which keeps it stable.
+	 */
+	const groups = $derived.by(() => {
+		const order: WorkflowOptionInfo[][] = [];
+		const seen = new Map<string, WorkflowOptionInfo[]>();
+		for (const option of available) {
+			let bucket = seen.get(option.group);
+			if (!bucket) {
+				bucket = [];
+				seen.set(option.group, bucket);
+				order.push(bucket);
+			}
+			bucket.push(option);
+		}
+		return order;
+	});
+
+	export function show() {
+		seeded = false;
+		open = true;
+		modal?.show();
+	}
+
+	/**
+	 * Seed the buffer once the policy has actually loaded.
+	 *
+	 * Doing this in `show()` is too early: the query is usually still in
+	 * flight when the button is clicked, so the buffer would be filled from
+	 * `undefined` and every box would render unchecked — including the ones
+	 * that are on by default.
+	 */
+	$effect(() => {
+		if (!open || seeded || !policyState) return;
+		seeded = true;
+		// `current` is null when no managed block exists yet, in which case the
+		// defaults are what a fresh setup would have written.
+		const current = policyState.current ?? policyState.defaults;
+		selected = [...current.selected];
+		publishPhrase = current.publishPhrase;
+		branchPattern = current.branchPattern ?? "";
+		commitConvention = current.commitConvention ?? "";
+	});
+
+	function has(id: WorkflowOptionId) {
+		return selected.includes(id);
+	}
+
+	function toggle(id: WorkflowOptionId) {
+		selected = has(id)
+			? selected.filter((entry: WorkflowOptionId) => entry !== id)
+			: [...selected, id];
+	}
+
+	/**
+	 * A repo-local rule is rendered once and written everywhere the setup
+	 * targets, so offering it globally would leak it into the user's global
+	 * config.
+	 */
+	function disabled(repoLocalOnly: boolean) {
+		return repoLocalOnly && scope !== "repository";
+	}
+
+	async function save(close: () => void) {
+		const options: PolicyOptions = {
+			selected: selected.filter((id: WorkflowOptionId) => {
+				const option = available.find((entry: WorkflowOptionInfo) => entry.id === id);
+				return !option || !disabled(option.repoLocalOnly);
+			}),
+			publishPhrase: publishPhrase.trim() || "ship it",
+			// An empty box means "no preference", not an empty pattern.
+			branchPattern: branchPattern.trim() || null,
+			commitConvention: commitConvention.trim() || null,
+		};
+		await savePolicy({ scope, projectId, options });
+		open = false;
+		close();
+	}
+</script>
+
+<Modal
+	bind:this={modal}
+	width="medium"
+	title="Customize agent workflow"
+	onSubmit={async (close) => await save(close)}
+>
+	<p class="text-12 text-body clr-text-2 m-b-12">
+		These preferences are written into the GitButler section of your agent instruction files.
+		{#if policyState?.diverged}
+			<br />Your instruction files currently disagree; saving will make them consistent.
+		{/if}
+	</p>
+
+	<div class="options">
+		{#each groups as group, groupIndex (group[0]?.group)}
+			<h4 class="group-heading text-13 text-semibold" class:group-heading--first={groupIndex === 0}>
+				{group[0]?.groupTitle}
+			</h4>
+			{#each group as option (option.id)}
+				{@const isDisabled = disabled(option.repoLocalOnly)}
+				<div class="option" class:option--disabled={isDisabled}>
+					<Checkbox
+						id="workflow-{option.id}"
+						checked={has(option.id)}
+						disabled={isDisabled}
+						onchange={() => toggle(option.id)}
+					/>
+					<label for="workflow-{option.id}" class="option__text">
+						<span class="text-13 text-semibold">{option.label}</span>
+						<span class="text-12 clr-text-2">
+							{#if isDisabled && option.repoLocalHelp}
+								<Tooltip text={option.repoLocalHelp}>
+									<span>{option.repoLocalHelp}</span>
+								</Tooltip>
+							{:else}
+								{option.help}
+							{/if}
+						</span>
+
+						{#if has(option.id) && !isDisabled}
+							{#if option.id === "publishPhrase"}
+								<Textbox label="Phrase" bind:value={publishPhrase} placeholder="ship it" />
+							{:else if option.id === "branchPattern"}
+								<Textbox
+									label="Pattern"
+									bind:value={branchPattern}
+									placeholder="<name>/<short-description>"
+								/>
+							{:else if option.id === "commitConvention"}
+								<Textbox
+									label="Convention"
+									bind:value={commitConvention}
+									placeholder="type(scope): summary"
+								/>
+							{/if}
+						{/if}
+					</label>
+				</div>
+			{/each}
+		{/each}
+	</div>
+
+	{#snippet controls(close)}
+		<Button
+			kind="outline"
+			type="reset"
+			onclick={() => {
+				open = false;
+				close();
+			}}>Cancel</Button
+		>
+		<Button style="pop" type="submit" loading={saving.current.isLoading}>Save</Button>
+	{/snippet}
+</Modal>
+
+<style lang="postcss">
+	/* The list is taller than the viewport on smaller windows, and the modal
+	   body does not scroll on its own, so the last option was unreachable. */
+	.options {
+		display: flex;
+		flex-direction: column;
+		max-height: 55vh;
+		padding-right: 4px;
+		overflow-y: auto;
+		gap: 12px;
+	}
+
+	.group-heading {
+		margin-top: 8px;
+		padding-top: 12px;
+		border-top: 1px solid var(--clr-border-3);
+		color: var(--clr-text-2);
+	}
+
+	.group-heading--first {
+		margin-top: 0;
+		padding-top: 0;
+		border-top: none;
+	}
+
+	.option {
+		display: flex;
+		align-items: flex-start;
+		gap: 10px;
+	}
+
+	.option--disabled {
+		opacity: 0.6;
+	}
+
+	.option__text {
+		display: flex;
+		flex-direction: column;
+		gap: 4px;
+	}
+</style>
diff --git a/apps/desktop/src/components/settings/AgentsAndCliSettings.svelte b/apps/desktop/src/components/settings/AgentsAndCliSettings.svelte
new file mode 100644
index 00000000000..951e03af646
--- /dev/null
+++ b/apps/desktop/src/components/settings/AgentsAndCliSettings.svelte
@@ -0,0 +1,33 @@
+<script lang="ts">
+	import AgentSkillList from "$components/settings/AgentSkillList.svelte";
+	import CliInstallCard from "$components/settings/CliInstallCard.svelte";
+	import { Spacer } from "@gitbutler/ui";
+	import type { SkillScope } from "@gitbutler/but-sdk";
+
+	type Props = {
+		projectId?: string;
+	};
+
+	const { projectId }: Props = $props();
+
+	// One component serves both settings modals. The only real difference is
+	// scope, which mirrors the same distinction the backend models, so this is
+	// not an invented abstraction.
+	const scope = $derived<SkillScope>(projectId ? "repository" : "global");
+</script>
+
+{#if !projectId}
+	<CliInstallCard />
+	<Spacer />
+{/if}
+
+<h3 class="text-14 text-semibold m-b-4">
+	{projectId ? "Skills for this project" : "Skills for all your projects"}
+</h3>
+<p class="text-12 text-body clr-text-2 m-b-12">
+	{projectId
+		? "Installed into this repository, so they travel with it and apply to everyone who works here."
+		: "Installed into your home directory, so they apply everywhere you use this agent."}
+</p>
+
+<AgentSkillList {scope} {projectId} />
diff --git a/apps/desktop/src/components/settings/CliInstallCard.svelte b/apps/desktop/src/components/settings/CliInstallCard.svelte
new file mode 100644
index 00000000000..87139f8b538
--- /dev/null
+++ b/apps/desktop/src/components/settings/CliInstallCard.svelte
@@ -0,0 +1,109 @@
+<script lang="ts">
+	import CliSymlinkSetup from "$components/settings/CliSymlinkSetup.svelte";
+	import { BACKEND } from "$lib/backend";
+	import { getUserErrorCode } from "$lib/backend/ipc";
+	import { CLI_MANAGER } from "$lib/config/cli";
+	import { showToast } from "$lib/notifications/toasts";
+	import { SETTINGS_SERVICE } from "$lib/settings/appSettings";
+	import { inject } from "@gitbutler/core/context";
+	import { Button, CardGroup } from "@gitbutler/ui";
+
+	const backend = inject(BACKEND);
+	const platformName = backend.platformName;
+	const settingsService = inject(SETTINGS_SERVICE);
+	const appSettings = settingsService.appSettings;
+
+	const cliManager = inject(CLI_MANAGER);
+	const [installCli, installing] = cliManager.install;
+	const [uninstallCli, uninstalling] = cliManager.uninstall;
+	const cliState = cliManager.state();
+
+	let showSymlink = $state(false);
+
+	const managedByPackageManager = $derived(!!$appSettings?.ui.cliIsManagedByPackageManager);
+	const linkState = $derived(cliState.response);
+
+	async function install() {
+		try {
+			await installCli();
+		} catch (err: unknown) {
+			// osascript returns a generic non-success when the user dismisses the
+			// macOS admin-privileges prompt. The backend tags that specific case
+			// so we can show an info toast instead of an error toast.
+			if (getUserErrorCode(err) === "CliInstallCancelled") {
+				showToast({ style: "info", message: "CLI install cancelled." });
+				return;
+			}
+			throw err;
+		}
+	}
+
+	async function uninstall() {
+		try {
+			await uninstallCli();
+		} catch (err: unknown) {
+			if (getUserErrorCode(err) === "CliUninstallCancelled") {
+				showToast({ style: "info", message: "CLI uninstall cancelled." });
+				return;
+			}
+			throw err;
+		}
+	}
+</script>
+
+<CardGroup>
+	<CardGroup.Item>
+		{#snippet title()}
+			GitButler CLI <code class="code-string">but</code>
+		{/snippet}
+
+		{#snippet caption()}
+			{#if managedByPackageManager}
+				The <code>but</code> CLI is managed by your package manager. Please use your package manager to
+				install, update, or remove it.
+			{:else if linkState?.blockedReason}
+				{linkState.blockedReason}
+			{:else if linkState?.installed}
+				Installed at <code class="code-string">{linkState.linkPath}</code>. Removing it deletes the
+				symlink only — the <code>but</code> binary inside GitButler stays where it is.
+			{:else if platformName === "windows"}
+				On Windows, you can manually copy the executable (<code>`but`</code>) to a directory in your
+				PATH. Click "Show command" for instructions.
+			{:else}
+				Installs the GitButler CLI (<code>`but`</code>) in your PATH, allowing you to use it from
+				the terminal. This action will request admin privileges. Alternatively, you could create a
+				symlink manually.
+			{/if}
+		{/snippet}
+
+		{#if !managedByPackageManager}
+			<div class="flex flex-col gap-16">
+				<div class="flex gap-8 justify-end">
+					{#if linkState?.installed}
+						<Button
+							style="danger"
+							kind="outline"
+							icon="bin"
+							loading={uninstalling.current.isLoading}
+							onclick={uninstall}>Uninstall</Button
+						>
+					{:else if platformName !== "windows"}
+						<Button style="pop" icon="play" loading={installing.current.isLoading} onclick={install}
+							>Install But CLI</Button
+						>
+					{/if}
+					<Button
+						style="gray"
+						kind="outline"
+						disabled={showSymlink}
+						onclick={() => (showSymlink = !showSymlink)}>Show command</Button
+					>
+				</div>
+			</div>
+
+			{#if showSymlink}
+				<CliSymlinkSetup class="m-t-14" />
+			{/if}
+		{/if}
+	</CardGroup.Item>
+</CardGroup>
diff --git a/apps/desktop/src/components/settings/GeneralSettings.svelte b/apps/desktop/src/components/settings/GeneralSettings.svelte
index a37b6bb827f..6d582201a9b 100644
--- a/apps/desktop/src/components/settings/GeneralSettings.svelte
+++ b/apps/desktop/src/components/settings/GeneralSettings.svelte
@@ -1,11 +1,7 @@
 <script lang="ts">
 	import { goto } from "$app/navigation";
-	import CliSymlinkSetup from "$components/settings/CliSymlinkSetup.svelte";
 	import AccessTokenSignIn from "$components/shared/AccessTokenSignIn.svelte";
 	import { BACKEND } from "$lib/backend";
-	import { getUserErrorCode } from "$lib/backend/ipc";
-	import { CLI_MANAGER } from "$lib/config/cli";
-	import { showToast } from "$lib/notifications/toasts";
 	import { PROJECTS_SERVICE } from "$lib/project/projectsService";
 	import { SETTINGS_SERVICE } from "$lib/settings/appSettings";
 	import { TERMINAL_SERVICE } from "$lib/settings/terminalService";
@@ -39,16 +35,11 @@
 	const updaterService = inject(UPDATER_SERVICE);
 	const disableAutoChecks = updaterService.disableAutoChecks;
 
-	const cliManager = inject(CLI_MANAGER);
-	const [instalCLI, installingCLI] = cliManager.install;
-
 	const backend = inject(BACKEND);
 	const platformName = backend.platformName;
 
 	const terminalService = inject(TERMINAL_SERVICE);
 
-	const appSettings = settingsService.appSettings;
-
 	let saving = $state(false);
 	let newName = $state("");
 	let isDeleting = $state(false);
@@ -154,8 +145,6 @@
 			isDeleting = false;
 		}
 	}
-
-	let showSymlink = $state(false);
 </script>
 
 {#if userService.user}
@@ -277,73 +266,6 @@
 	</CardGroup.Item>
 </CardGroup>
 
-<CardGroup>
-	<CardGroup.Item>
-		{#snippet title()}
-			Install the GitButler CLI <code class="code-string">but</code>
-		{/snippet}
-
-		{#snippet caption()}
-			{#if $appSettings?.ui.cliIsManagedByPackageManager}
-				The <code>but</code> CLI is managed by your package manager. Please use your package manager to
-				install, update, or remove it.
-			{:else if platformName === "windows"}
-				On Windows, you can manually copy the executable (<code>`but`</code>) to a directory in your
-				PATH. Click "Show Command" for instructions.
-			{:else}
-				Installs the GitButler CLI (<code>`but`</code>) in your PATH, allowing you to use it from
-				the terminal. This action will request admin privileges. Alternatively, you could create a
-				symlink manually.
-			{/if}
-		{/snippet}
-
-		{#if !$appSettings?.ui.cliIsManagedByPackageManager}
-			<div class="flex flex-col gap-16">
-				<div class="flex gap-8 justify-end">
-					{#if platformName !== "windows"}
-						<Button
-							style="pop"
-							icon="play"
-							onclick={async () => {
-								try {
-									await instalCLI();
-								} catch (err: unknown) {
-									// osascript returns a generic non-success when the
-									// user dismisses the macOS admin-privileges prompt.
-									// The backend tags that specific case with a
-									// `CliInstallCancelled` code so we can show an info
-									// toast instead of an error toast.
-									if (getUserErrorCode(err) === "CliInstallCancelled") {
-										showToast({
-											style: "info",
-											message: "CLI install cancelled.",
-										});
-										return;
-									}
-									throw err;
-								}
-							}}
-							loading={installingCLI.current.isLoading}
-						>
-							Install But CLI</Button
-						>
-					{/if}
-					<Button
-						style="gray"
-						kind="outline"
-						disabled={showSymlink}
-						onclick={() => (showSymlink = !showSymlink)}>Show command</Button
-					>
-				</div>
-			</div>
-
-			{#if showSymlink}
-				<CliSymlinkSetup class="m-t-14" />
-			{/if}
-		{/if}
-	</CardGroup.Item>
-</CardGroup>
-
 <Spacer />
 
 <CardGroup>
diff --git a/apps/desktop/src/components/settings/GeneralSettingsModalContent.svelte b/apps/desktop/src/components/settings/GeneralSettingsModalContent.svelte
index 21c0fed7e89..405b29a0f3c 100644
--- a/apps/desktop/src/components/settings/GeneralSettingsModalContent.svelte
+++ b/apps/desktop/src/components/settings/GeneralSettingsModalContent.svelte
@@ -1,5 +1,6 @@
 <script lang="ts">
 	import AppearanceSettings from "$components/projectSettings/AppearanceSettings.svelte";
+	import AgentsAndCliSettings from "$components/settings/AgentsAndCliSettings.svelte";
 	import AiSettings from "$components/settings/AiSettings.svelte";
 	import ExperimentalSettings from "$components/settings/ExperimentalSettings.svelte";
 	import GeneralSettings from "$components/settings/GeneralSettings.svelte";
@@ -51,6 +52,8 @@
 				<GitSettings />
 			{:else if currentPage.id === "integrations"}
 				<IntegrationsSettings />
+			{:else if currentPage.id === "agents"}
+				<AgentsAndCliSettings />
 			{:else if currentPage.id === "ai"}
 				<AiSettings />
 			{:else if currentPage.id === "telemetry"}
diff --git a/apps/desktop/src/components/settings/ProjectSettingsModalContent.svelte b/apps/desktop/src/components/settings/ProjectSettingsModalContent.svelte
index 7ac7117bce0..e19ec3f4942 100644
--- a/apps/desktop/src/components/settings/ProjectSettingsModalContent.svelte
+++ b/apps/desktop/src/components/settings/ProjectSettingsModalContent.svelte
@@ -3,6 +3,7 @@
 	import GeneralSettings from "$components/projectSettings/GeneralSettings.svelte";
 	import GitForm from "$components/projectSettings/GitForm.svelte";
 	import PreferencesForm from "$components/projectSettings/PreferencesForm.svelte";
+	import AgentsAndCliSettings from "$components/settings/AgentsAndCliSettings.svelte";
 	import SettingsModalLayout from "$components/settings/SettingsModalLayout.svelte";
 	import { projectSettingsPages } from "$lib/settings/projectSettingsPages";
 	import type { ProjectSettingsModalState, ProjectSettingsPageId } from "$lib/state/uiState.svelte";
@@ -34,6 +35,8 @@
 				<GeneralSettings projectId={data.projectId} />
 			{:else if currentPage.id === "git"}
 				<GitForm projectId={data.projectId} />
+			{:else if currentPage.id === "agents"}
+				<AgentsAndCliSettings projectId={data.projectId} />
 			{:else if currentPage.id === "ai"}
 				<CloudForm projectId={data.projectId} />
 			{:else if currentPage.id === "experimental"}
diff --git a/apps/desktop/src/components/shared/ToastController.svelte b/apps/desktop/src/components/shared/ToastController.svelte
index b8d24cc82cd..8a48ea2bded 100644
--- a/apps/desktop/src/components/shared/ToastController.svelte
+++ b/apps/desktop/src/components/shared/ToastController.svelte
@@ -13,10 +13,12 @@
 				testId={toast.testId ?? TestId.ToastInfoMessage}
 				style={toast.style ?? "info"}
 				error={toast.error}
-				secondaryLabel={toast.extraAction ? toast.extraAction.label : "Dismiss"}
+				secondaryLabel={toast.extraAction
+					? toast.extraAction.label
+					: (toast.dismissLabel ?? "Dismiss")}
 				secondaryTestId={toast.extraAction ? toast.extraAction.testId : undefined}
 				secondaryAction={toast.extraAction ? () => toast.extraAction?.onClick(dismiss) : dismiss}
-				tertiaryLabel={toast.extraAction ? "Dismiss" : undefined}
+				tertiaryLabel={toast.extraAction ? (toast.dismissLabel ?? "Dismiss") : undefined}
 				tertiaryAction={toast.extraAction ? dismiss : undefined}
 				shadow
 			>
diff --git a/apps/desktop/src/components/views/GlobalModalRouter.svelte b/apps/desktop/src/components/views/GlobalModalRouter.svelte
index 1904d8670ac..b931b53eafd 100644
--- a/apps/desktop/src/components/views/GlobalModalRouter.svelte
+++ b/apps/desktop/src/components/views/GlobalModalRouter.svelte
@@ -1,6 +1,7 @@
 <script lang="ts">
 	import CommitFailedModalContent from "$components/commit/CommitFailedModalContent.svelte";
 	import LoginConfirmationModalContent from "$components/onboarding/LoginConfirmationModalContent.svelte";
+	import AgentSetupModalContent from "$components/settings/AgentSetupModalContent.svelte";
 	import AuthorMissingModalContent from "$components/settings/AuthorMissingModalContent.svelte";
 	import GeneralSettingsModalContent from "$components/settings/GeneralSettingsModalContent.svelte";
 	import ProjectSettingsModalContent from "$components/settings/ProjectSettingsModalContent.svelte";
@@ -44,6 +45,16 @@
 					},
 				};
 			}
+			case "agent-setup": {
+				return {
+					state: modalState,
+					props: {
+						closeButton: true,
+						width: 560,
+						noPadding: true,
+					},
+				};
+			}
 			case "general-settings": {
 				return {
 					state: modalState,
@@ -115,6 +126,11 @@
 				userService.rejectIncomingUser();
 			}
 		}
+		// The wizard replaces whatever opened it, so put that back.
+		if (stableModalData?.state.type === "agent-setup" && stableModalData.state.returnTo) {
+			uiState.global.modal.set(stableModalData.state.returnTo);
+			return;
+		}
 		uiState.global.modal.set(undefined);
 	}
 
@@ -144,6 +160,8 @@
 			<CommitFailedModalContent data={stableModalData.state} oncloseclick={closeModal} />
 		{:else if stableModalData.state.type === "author-missing"}
 			<AuthorMissingModalContent data={stableModalData.state} close={closeModal} />
+		{:else if stableModalData.state.type === "agent-setup"}
+			<AgentSetupModalContent data={stableModalData.state} close={closeModal} />
 		{:else if stableModalData.state.type === "general-settings"}
 			<GeneralSettingsModalContent data={stableModalData.state} />
 		{:else if stableModalData.state.type === "project-settings"}
diff --git a/apps/desktop/src/lib/agents/agentsService.ts b/apps/desktop/src/lib/agents/agentsService.ts
new file mode 100644
index 00000000000..a670f3c3251
--- /dev/null
+++ b/apps/desktop/src/lib/agents/agentsService.ts
@@ -0,0 +1,112 @@
+import { invalidatesList, providesList, ReduxTag } from "$lib/state/tags";
+import { InjectionToken } from "@gitbutler/core/context";
+import type { BackendApi } from "$lib/state/backendApi";
+import type { AgentsStatus, PolicyOptions, PolicyState, SkillScope } from "@gitbutler/but-sdk";
+
+export const AGENTS_SERVICE = new InjectionToken<AgentsService>("AgentsService");
+
+type ScopedArgs = { scope: SkillScope; projectId?: string };
+type FrameworkArgs = ScopedArgs & { frameworkId: string };
+
+/**
+ * Agent skill install state, and the workflow policy that gets written into
+ * agent instruction files.
+ *
+ * Every command works without a project: the global settings page manages
+ * `$HOME` skills before any repository is open, so `projectId` is optional
+ * throughout and simply narrows results to a repository when given.
+ */
+export class AgentsService {
+	private api: ReturnType<typeof injectEndpoints>;
+
+	constructor(backendApi: BackendApi) {
+		this.api = injectEndpoints(backendApi);
+	}
+
+	status(args: { projectId?: string }) {
+		return this.api.endpoints.agentsStatus.useQuery(args);
+	}
+
+	/**
+	 * One-shot read for the startup check.
+	 *
+	 * Deliberately not `useQuery`: a component that renders nothing would hold
+	 * a live subscription forever, and an effect reading it would fire once
+	 * while still loading and again with data.
+	 */
+	async fetchStatus(args: { projectId?: string }) {
+		return await this.api.endpoints.agentsStatus.fetch(args, { forceRefetch: true });
+	}
+
+	policy(args: ScopedArgs) {
+		return this.api.endpoints.agentPolicyGet.useQuery(args);
+	}
+
+	get installSkill() {
+		return this.api.endpoints.agentSkillInstall.useMutation();
+	}
+
+	get uninstallSkill() {
+		return this.api.endpoints.agentSkillUninstall.useMutation();
+	}
+
+	get updateSkills() {
+		return this.api.endpoints.agentSkillsUpdate.useMutation();
+	}
+
+	get setPolicy() {
+		return this.api.endpoints.agentPolicySet.useMutation();
+	}
+}
+
+function injectEndpoints(backendApi: BackendApi) {
+	return backendApi.injectEndpoints({
+		endpoints: (build) => ({
+			agentsStatus: build.query<AgentsStatus, { projectId?: string }>({
+				extraOptions: { command: "agents_status" },
+				query: (args) => args,
+				providesTags: [providesList(ReduxTag.AgentsStatus)],
+			}),
+			agentPolicyGet: build.query<PolicyState, ScopedArgs>({
+				extraOptions: { command: "agent_policy_get" },
+				query: (args) => args,
+				providesTags: [providesList(ReduxTag.AgentPolicy)],
+			}),
+			agentSkillInstall: build.mutation<AgentsStatus, FrameworkArgs>({
+				extraOptions: { command: "agent_skill_install" },
+				query: (args) => args,
+				invalidatesTags: () => [
+					invalidatesList(ReduxTag.AgentsStatus),
+					invalidatesList(ReduxTag.AgentPolicy),
+				],
+			}),
+			agentSkillUninstall: build.mutation<
+				AgentsStatus,
+				FrameworkArgs & { removeInstructions?: boolean }
+			>({
+				extraOptions: { command: "agent_skill_uninstall" },
+				query: (args) => args,
+				invalidatesTags: () => [
+					invalidatesList(ReduxTag.AgentsStatus),
+					invalidatesList(ReduxTag.AgentPolicy),
+				],
+			}),
+			agentSkillsUpdate: build.mutation<AgentsStatus, ScopedArgs & { frameworkId?: string }>({
+				extraOptions: { command: "agent_skills_update" },
+				query: (args) => args,
+				invalidatesTags: () => [
+					invalidatesList(ReduxTag.AgentsStatus),
+					invalidatesList(ReduxTag.AgentPolicy),
+				],
+			}),
+			agentPolicySet: build.mutation<PolicyState, ScopedArgs & { options: PolicyOptions }>({
+				extraOptions: { command: "agent_policy_set" },
+				query: (args) => args,
+				invalidatesTags: () => [
+					invalidatesList(ReduxTag.AgentPolicy),
+					invalidatesList(ReduxTag.AgentsStatus),
+				],
+			}),
+		}),
+	});
+}
diff --git a/apps/desktop/src/lib/agents/setupPrompt.ts b/apps/desktop/src/lib/agents/setupPrompt.ts
new file mode 100644
index 00000000000..abe267b97a9
--- /dev/null
+++ b/apps/desktop/src/lib/agents/setupPrompt.ts
@@ -0,0 +1,13 @@
+let evaluated = false;
+
+/**
+ * Claim the one-per-process right to evaluate the agent setup prompt.
+ *
+ * The prompt already lives in the root layout, which mounts once per window.
+ * This is belt-and-braces against a dev HMR remount showing a second toast.
+ */
+export function markAgentPromptEvaluated(): boolean {
+	if (evaluated) return false;
+	evaluated = true;
+	return true;
+}
diff --git a/apps/desktop/src/lib/bootstrap/deps.ts b/apps/desktop/src/lib/bootstrap/deps.ts
index 0d78c637ffb..5161d86f9fd 100644
--- a/apps/desktop/src/lib/bootstrap/deps.ts
+++ b/apps/desktop/src/lib/bootstrap/deps.ts
@@ -1,3 +1,4 @@
+import { AGENTS_SERVICE, AgentsService } from "$lib/agents/agentsService";
 import {
 	PromptService as AIPromptService,
 	PROMPT_SERVICE as AI_PROMPT_SERVICE,
@@ -261,6 +262,7 @@ export function initDependencies(args: {
 	// ============================================================================
 
 	const cliManager = new CLIManager(clientState.backendApi);
+	const agentsService = new AgentsService(clientState.backendApi);
 	const dataSharingService = new DataSharingService(clientState.backendApi);
 	const promptService = new PromptService(backend);
 	const updaterService = new UpdaterService(
@@ -295,6 +297,7 @@ export function initDependencies(args: {
 		[CLIENT_STATE, clientState],
 		[CLIPBOARD_SERVICE, clipboardService],
 		[CLI_MANAGER, cliManager],
+		[AGENTS_SERVICE, agentsService],
 		[CLOUD_USER_SERVICE, cloudUserService],
 		[COMMIT_ANALYTICS, commitAnalytics],
 		[DATA_SHARING_SERVICE, dataSharingService],
diff --git a/apps/desktop/src/lib/config/cli.ts b/apps/desktop/src/lib/config/cli.ts
index 25b962fdcbf..201c8ff2a62 100644
--- a/apps/desktop/src/lib/config/cli.ts
+++ b/apps/desktop/src/lib/config/cli.ts
@@ -1,7 +1,9 @@
 // cli.ts, lol
 
+import { invalidatesList, providesList, ReduxTag } from "$lib/state/tags";
 import { InjectionToken } from "@gitbutler/core/context";
 import type { BackendApi } from "$lib/state/backendApi";
+import type { CliInstallState } from "@gitbutler/but-sdk";
 
 export const CLI_MANAGER = new InjectionToken<CLIManager>("CLIManager");
 
@@ -16,9 +18,22 @@ export default class CLIManager {
 		return this.api.endpoints.installCLI.useMutation();
 	}
 
+	get uninstall() {
+		return this.api.endpoints.uninstallCLI.useMutation();
+	}
+
 	path() {
 		return this.api.endpoints.cliPath.useQuery();
 	}
+
+	state() {
+		return this.api.endpoints.cliInstallState.useQuery();
+	}
+
+	/** One-shot read for the startup check; see AgentsService.fetchStatus. */
+	async fetchState() {
+		return await this.api.endpoints.cliInstallState.fetch(undefined, { forceRefetch: true });
+	}
 }
 
 function injectEndpoints(backendApi: BackendApi) {
@@ -27,6 +42,17 @@ function injectEndpoints(backendApi: BackendApi) {
 			installCLI: build.mutation<void, void>({
 				extraOptions: { command: "install_cli" },
 				query: () => ({}),
+				invalidatesTags: () => [invalidatesList(ReduxTag.CliInstallState)],
+			}),
+			uninstallCLI: build.mutation<CliInstallState, void>({
+				extraOptions: { command: "uninstall_cli" },
+				query: () => ({}),
+				invalidatesTags: () => [invalidatesList(ReduxTag.CliInstallState)],
+			}),
+			cliInstallState: build.query<CliInstallState, void>({
+				extraOptions: { command: "cli_install_state" },
+				query: () => ({}),
+				providesTags: [providesList(ReduxTag.CliInstallState)],
 			}),
 			cliPath: build.query<string, void>({
 				extraOptions: { command: "cli_path" },
diff --git a/apps/desktop/src/lib/notifications/toasts.ts b/apps/desktop/src/lib/notifications/toasts.ts
index d04a84a016d..5e54630ef07 100644
--- a/apps/desktop/src/lib/notifications/toasts.ts
+++ b/apps/desktop/src/lib/notifications/toasts.ts
@@ -16,6 +16,13 @@ export interface Toast {
 	title?: string;
 	style?: MessageStyle;
 	extraAction?: ExtraAction;
+	/**
+	 * Label for the dismiss button. Override when dismissing has a lasting
+	 * effect, so the wording does not imply "just this time".
+	 */
+	dismissLabel?: string;
+	/** Runs when the toast is dismissed, but not when it is replaced by id. */
+	onDismiss?: () => void;
 }
 
 export const toastStore: Writable<Toast[]> = writable([]);
@@ -83,5 +90,8 @@ export function showWarning(
 
 export function dismissToast(messageId: string | undefined) {
 	if (!messageId) return;
-	toastStore.update((items) => items.filter((m) => m.id !== messageId));
+	toastStore.update((items) => {
+		items.find((m) => m.id === messageId)?.onDismiss?.();
+		return items.filter((m) => m.id !== messageId);
+	});
 }
diff --git a/apps/desktop/src/lib/settings/generalSettingsPages.ts b/apps/desktop/src/lib/settings/generalSettingsPages.ts
index af8a098304b..7461aaa67c0 100644
--- a/apps/desktop/src/lib/settings/generalSettingsPages.ts
+++ b/apps/desktop/src/lib/settings/generalSettingsPages.ts
@@ -33,6 +33,11 @@ export const generalSettingsPages = [
 		label: "Integrations",
 		icon: "puzzle",
 	},
+	{
+		id: "agents",
+		label: "Agents & CLI",
+		icon: "robot",
+	},
 	{
 		id: "ai",
 		label: "AI Options",
diff --git a/apps/desktop/src/lib/settings/projectSettingsPages.ts b/apps/desktop/src/lib/settings/projectSettingsPages.ts
index 1564c8e6b2e..56554f0456b 100644
--- a/apps/desktop/src/lib/settings/projectSettingsPages.ts
+++ b/apps/desktop/src/lib/settings/projectSettingsPages.ts
@@ -18,6 +18,11 @@ export const projectSettingsPages = [
 		label: "Git stuff",
 		icon: "git",
 	},
+	{
+		id: "agents",
+		label: "Agents & CLI",
+		icon: "robot",
+	},
 	{
 		id: "ai",
 		label: "AI options",
diff --git a/apps/desktop/src/lib/state/tags.ts b/apps/desktop/src/lib/state/tags.ts
index 48466aba041..b9007d128e6 100644
--- a/apps/desktop/src/lib/state/tags.ts
+++ b/apps/desktop/src/lib/state/tags.ts
@@ -27,6 +27,9 @@ export enum ReduxTag {
 	BranchDetails = "BranchDetails",
 	SnapshotDiff = "SnapshotDiff",
 	Project = "Project",
+	CliInstallState = "CliInstallState",
+	AgentsStatus = "AgentsStatus",
+	AgentPolicy = "AgentPolicy",
 	ProjectGerrit = "ProjectGerrit",
 	InitalEditListing = "InitialEditListing",
 	EditChangesSinceInitial = "EditChangesSinceInitial",
diff --git a/apps/desktop/src/lib/state/uiState.svelte.ts b/apps/desktop/src/lib/state/uiState.svelte.ts
index 4b41558595b..66b6e70b575 100644
--- a/apps/desktop/src/lib/state/uiState.svelte.ts
+++ b/apps/desktop/src/lib/state/uiState.svelte.ts
@@ -13,11 +13,12 @@ export type GeneralSettingsPageId =
 	| "lanes-and-branches"
 	| "git"
 	| "integrations"
+	| "agents"
 	| "ai"
 	| "telemetry"
 	| "experimental"
 	| "organizations";
-export type ProjectSettingsPageId = "project" | "git" | "ai" | "experimental";
+export type ProjectSettingsPageId = "project" | "git" | "agents" | "ai" | "experimental";
 export type RejectionReason =
 	| "workspaceMergeConflict"
 	| "workspaceMergeConflictOfUnrelatedFile"
@@ -86,7 +87,8 @@ type GlobalModalType =
 	| "author-missing"
 	| "general-settings"
 	| "project-settings"
-	| "login-confirmation";
+	| "login-confirmation"
+	| "agent-setup";
 type BaseGlobalModalState = {
 	type: GlobalModalType;
 };
@@ -124,12 +126,23 @@ export type LoginConfirmationModalState = BaseGlobalModalState & {
 
 export type AppTheme = "system" | "light" | "dark";
 
+export type AgentSetupModalState = BaseGlobalModalState & {
+	type: "agent-setup";
+	projectId?: string;
+	/**
+	 * The modal to restore on close. The router holds one modal at a time, so
+	 * opening the wizard from settings would otherwise close settings for good.
+	 */
+	returnTo?: GeneralSettingsModalState | ProjectSettingsModalState;
+};
+
 export type GlobalModalState =
 	| CommitFailedModalState
 	| AuthorMissingModalState
 	| GeneralSettingsModalState
 	| ProjectSettingsModalState
-	| LoginConfirmationModalState;
+	| LoginConfirmationModalState
+	| AgentSetupModalState;
 
 export type CodeEditorSettings = {
 	schemeIdentifer: string;
diff --git a/apps/desktop/src/routes/+layout.svelte b/apps/desktop/src/routes/+layout.svelte
index 974c9796f50..f18ea559cd1 100644
--- a/apps/desktop/src/routes/+layout.svelte
+++ b/apps/desktop/src/routes/+layout.svelte
@@ -5,6 +5,7 @@
 	import { browser, dev } from "$app/environment";
 	import { afterNavigate, beforeNavigate } from "$app/navigation";
 	import { page } from "$app/state";
+	import AgentSetupPrompt from "$components/settings/AgentSetupPrompt.svelte";
 	import GlobalSettingsShortcutHandler from "$components/settings/GlobalSettingsShortcutHandler.svelte";
 	import ReloadShortcutHandler from "$components/settings/ReloadShortcutHandler.svelte";
 	import ThemeShortcutHandler from "$components/settings/ThemeShortcutHandler.svelte";
@@ -172,6 +173,7 @@
 </div>
 <ShareIssueModal />
 <ToastController />
+<AgentSetupPrompt />
 <ChipToastContainer />
 <AppUpdater />
 <GitInputPrompt />
diff --git a/crates/but-api/src/agents.rs b/crates/but-api/src/agents.rs
index c91fd871b00..fb65df5d9f7 100644
--- a/crates/but-api/src/agents.rs
+++ b/crates/but-api/src/agents.rs
@@ -222,6 +222,30 @@ pub mod json {
         }
     }
 
+    /// Topic a workflow option is grouped under in the preferences UI.
+    #[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
+    #[cfg_attr(feature = "export-schema", derive(schemars::JsonSchema))]
+    #[serde(rename_all = "camelCase")]
+    pub enum WorkflowGroupId {
+        /// How commits get made and shaped.
+        Committing,
+        /// How branches and pull requests are organised.
+        Branches,
+        /// What the agent is allowed to do on its own.
+        Automation,
+    }
+
+    impl From<but_skill::policy::WorkflowGroup> for WorkflowGroupId {
+        fn from(value: but_skill::policy::WorkflowGroup) -> Self {
+            use but_skill::policy::WorkflowGroup as G;
+            match value {
+                G::Committing => Self::Committing,
+                G::Branches => Self::Branches,
+                G::Automation => Self::Automation,
+            }
+        }
+    }
+
     /// Static description of a workflow option, so the UI never hardcodes the
     /// wording.
     #[derive(Debug, Serialize)]
@@ -230,6 +254,10 @@ pub mod json {
     pub struct WorkflowOptionInfo {
         /// Which option this describes.
         pub id: WorkflowOptionId,
+        /// Topic to group this option under.
+        pub group: WorkflowGroupId,
+        /// Heading for that group.
+        pub group_title: String,
         /// Checkbox label.
         pub label: String,
         /// Explanatory help text.
@@ -303,6 +331,7 @@ pub mod json {
         but_schemars::register_sdk_type!(super::InstalledSkill);
         but_schemars::register_sdk_type!(super::CliInstallState);
         but_schemars::register_sdk_type!(super::WorkflowOptionId);
+        but_schemars::register_sdk_type!(super::WorkflowGroupId);
         but_schemars::register_sdk_type!(super::WorkflowOptionInfo);
         but_schemars::register_sdk_type!(super::PolicyOptions);
         but_schemars::register_sdk_type!(super::PolicySource);
@@ -495,6 +524,46 @@ pub fn agent_skill_install(
     agents_status(project_id)
 }
 
+/// Rewrite outdated GitButler skills in place, bringing them up to the
+/// running version.
+///
+/// `framework_id` limits this to one agent; `None` refreshes every outdated
+/// installation at `scope`.
+///
+/// Updates the path each skill was *discovered* at rather than the canonical
+/// install path. Those differ when a skill was installed into a custom folder
+/// name, and writing to the canonical path would leave the outdated copy in
+/// place and add a second one beside it.
+#[but_api]
+#[instrument(err(Debug))]
+pub fn agent_skills_update(
+    scope: SkillScope,
+    project_id: Option<ProjectHandleOrLegacyProjectId>,
+    framework_id: Option<String>,
+) -> Result<AgentsStatus> {
+    let scope: Scope = scope.into();
+    let root = repo_root(project_id.clone())?;
+    let base = base_dir(scope, but_path::home_dir().as_deref(), root.as_deref())?;
+    let version = but_skill::cli_version();
+
+    for framework in FRAMEWORKS {
+        if framework_id.as_deref().is_some_and(|id| id != framework.id) {
+            continue;
+        }
+        let Some(format) = framework.format(matches!(scope, Scope::Global)) else {
+            continue;
+        };
+        for path in but_skill::status::find_format_installations(format, &base) {
+            if but_skill::status::is_current_skill_installation(&path, version) {
+                continue;
+            }
+            but_skill::install::write_skill_files(&path)?;
+        }
+    }
+
+    agents_status(project_id)
+}
+
 /// Remove the GitButler skill for one framework at one scope.
 ///
 /// `remove_instructions` additionally strips the managed policy block from
@@ -599,10 +668,22 @@ pub fn agent_policy_get(
     }
 
     Ok(PolicyState {
-        available: WorkflowOption::ALL
+        // Emitted grouped, one group at a time. `WorkflowOption::ALL` is in the
+        // order the CLI wizard prompts, which interleaves groups; a consumer
+        // rendering a heading whenever the group changes between neighbours
+        // would repeat every heading. Sorting here rather than reordering ALL
+        // keeps the wizard's prompt order untouched.
+        available: but_skill::policy::WorkflowGroup::ALL
             .into_iter()
+            .flat_map(|group| {
+                WorkflowOption::ALL
+                    .into_iter()
+                    .filter(move |option| option.group() == group)
+            })
             .map(|option| WorkflowOptionInfo {
                 id: option.into(),
+                group: option.group().into(),
+                group_title: option.group().title().to_string(),
                 label: option.label().to_string(),
                 help: option.help().to_string(),
                 default_selected: option.default_selected(),
@@ -668,3 +749,45 @@ pub fn cli_install_state() -> Result<CliInstallState> {
 pub fn uninstall_cli() -> Result<CliInstallState> {
     Ok(but_skill::cli_link::uninstall_cli()?.into())
 }
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    /// The policy catalogue must arrive with each group contiguous.
+    ///
+    /// `WorkflowOption::ALL` interleaves groups because it is ordered for the
+    /// CLI wizard's prompts, so a UI that renders a heading whenever the group
+    /// changes between neighbours would repeat every heading. Sorting happens
+    /// in `agent_policy_get`; this pins it.
+    #[test]
+    fn the_option_catalogue_is_emitted_with_groups_contiguous() {
+        let ordered: Vec<_> = but_skill::policy::WorkflowGroup::ALL
+            .into_iter()
+            .flat_map(|group| {
+                WorkflowOption::ALL
+                    .into_iter()
+                    .filter(move |option| option.group() == group)
+            })
+            .collect();
+
+        assert_eq!(
+            ordered.len(),
+            WorkflowOption::ALL.len(),
+            "every option should survive the grouping"
+        );
+
+        let mut seen = Vec::new();
+        for option in &ordered {
+            let group = option.group();
+            if seen.last() != Some(&group) {
+                assert!(
+                    !seen.contains(&group),
+                    "group {} appears more than once, so its heading would repeat",
+                    group.title()
+                );
+                seen.push(group);
+            }
+        }
+    }
+}
diff --git a/crates/but-server/src/lib.rs b/crates/but-server/src/lib.rs
index 11a74cba2a9..b1169344f03 100644
--- a/crates/but-server/src/lib.rs
+++ b/crates/but-server/src/lib.rs
@@ -759,6 +759,10 @@ pub async fn run(config: Config) -> anyhow::Result<()> {
             "/agent_skill_uninstall",
             but_post(agents::agent_skill_uninstall_cmd),
         )
+        .route(
+            "/agent_skills_update",
+            but_post(agents::agent_skills_update_cmd),
+        )
         .route("/agent_policy_get", but_post(agents::agent_policy_get_cmd))
         .route("/agent_policy_set", but_post(agents::agent_policy_set_cmd))
         .route("/open_url", but_post(open::open_url_cmd))
diff --git a/crates/but-skill/src/policy.rs b/crates/but-skill/src/policy.rs
index f1335cc9767..f3498305669 100644
--- a/crates/but-skill/src/policy.rs
+++ b/crates/but-skill/src/policy.rs
@@ -5,6 +5,33 @@ use std::fmt::Write as _;
 
 use crate::files::{MANAGED_BLOCK_END, MANAGED_BLOCK_START};
 
+/// A topic heading the preferences UI groups options under.
+///
+/// Ordered as the UI should present them.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum WorkflowGroup {
+    /// How commits get made and shaped.
+    Committing,
+    /// How branches and pull requests are organised.
+    Branches,
+    /// What the agent is allowed to do on its own.
+    Automation,
+}
+
+impl WorkflowGroup {
+    /// Every group, in presentation order.
+    pub const ALL: [Self; 3] = [Self::Committing, Self::Branches, Self::Automation];
+
+    /// Heading shown above the group.
+    pub fn title(self) -> &'static str {
+        match self {
+            Self::Committing => "Committing",
+            Self::Branches => "Branches & pull requests",
+            Self::Automation => "Automation",
+        }
+    }
+}
+
 #[derive(Debug, Clone, Copy, PartialEq, Eq)]
 pub enum WorkflowOption {
     FoldFixes,
@@ -98,6 +125,24 @@ impl WorkflowOption {
         matches!(self, Self::PushToTarget)
     }
 
+    /// Which topic this option belongs to.
+    ///
+    /// Purely a presentation grouping — it does not affect what is rendered.
+    /// Kept here rather than in the UI so the catalogue stays single-sourced,
+    /// for the same reason labels and help text are.
+    pub fn group(self) -> WorkflowGroup {
+        match self {
+            Self::FoldFixes
+            | Self::SuggestSplits
+            | Self::CommitConvention
+            | Self::CommitAfterTurn => WorkflowGroup::Committing,
+            Self::StackedBranches | Self::DraftPrs | Self::PushToTarget | Self::BranchPattern => {
+                WorkflowGroup::Branches
+            }
+            Self::AutoUpdate | Self::PublishPhrase => WorkflowGroup::Automation,
+        }
+    }
+
     /// The `###` heading this option renders as inside the managed block.
     ///
     /// Single-sourced because [`parse_managed_policy_block`] maps these
@@ -558,3 +603,41 @@ mod tests {
         assert_eq!(parsed.publish_phrase, default_publish_phrase());
     }
 }
+
+#[cfg(test)]
+mod group_tests {
+    use super::*;
+
+    /// Grouping is presentation only: every option must land in exactly one
+    /// group, and no group may be empty, or the settings UI would silently
+    /// drop an option or render an empty heading.
+    #[test]
+    fn every_option_belongs_to_exactly_one_non_empty_group() {
+        for group in WorkflowGroup::ALL {
+            let members: Vec<_> = WorkflowOption::ALL
+                .into_iter()
+                .filter(|option| option.group() == group)
+                .collect();
+            assert!(
+                !members.is_empty(),
+                "{} would render as an empty heading",
+                group.title()
+            );
+        }
+
+        let grouped: usize = WorkflowGroup::ALL
+            .into_iter()
+            .map(|group| {
+                WorkflowOption::ALL
+                    .into_iter()
+                    .filter(|option| option.group() == group)
+                    .count()
+            })
+            .sum();
+        assert_eq!(
+            grouped,
+            WorkflowOption::ALL.len(),
+            "every option should appear under exactly one group"
+        );
+    }
+}
diff --git a/crates/gitbutler-tauri/src/main.rs b/crates/gitbutler-tauri/src/main.rs
index c00ee931dc6..dc2af04f128 100644
--- a/crates/gitbutler-tauri/src/main.rs
+++ b/crates/gitbutler-tauri/src/main.rs
@@ -340,6 +340,7 @@ fn main() -> anyhow::Result<()> {
                 agents::tauri_agents_status::agents_status,
                 agents::tauri_agent_skill_install::agent_skill_install,
                 agents::tauri_agent_skill_uninstall::agent_skill_uninstall,
+                agents::tauri_agent_skills_update::agent_skills_update,
                 agents::tauri_agent_policy_get::agent_policy_get,
                 agents::tauri_agent_policy_set::agent_policy_set,
                 legacy::workspace::tauri_head_info::head_info,
diff --git a/packages/but-sdk/src/generated/graph/index.d.ts b/packages/but-sdk/src/generated/graph/index.d.ts
index 468d9f164d7..db231131d82 100644
--- a/packages/but-sdk/src/generated/graph/index.d.ts
+++ b/packages/but-sdk/src/generated/graph/index.d.ts
@@ -844,6 +844,7 @@ export interface WatcherEvent {
  * `callback` receives watcher events shaped as `{ name, payload }`.
  */
 export declare function watcherStart(projectId: string, callback: ((err: Error | null, arg: WatcherEvent) => any)): Promise<WatcherHandle>
+
 // Auto-generated by but-ts. Do not edit manually.
 // Generated from JSON schemas registered by #[but_api] functions.
 
@@ -3419,6 +3420,9 @@ export type WatcherWorktreeChangesPayload = {
   changes: WorktreeChanges;
 };
 
+/** Topic a workflow option is grouped under in the preferences UI. */
+export type WorkflowGroupId = "committing" | "branches" | "automation";
+
 /** One of the workflow preferences that render into the managed block. */
 export type WorkflowOptionId = "foldFixes" | "suggestSplits" | "stackedBranches" | "autoUpdate" | "draftPrs" | "pushToTarget" | "publishPhrase" | "branchPattern" | "commitConvention" | "commitAfterTurn";
 
@@ -3429,6 +3433,10 @@ export type WorkflowOptionId = "foldFixes" | "suggestSplits" | "stackedBranches"
 export type WorkflowOptionInfo = {
   /** Which option this describes. */
   id: WorkflowOptionId;
+  /** Topic to group this option under. */
+  group: WorkflowGroupId;
+  /** Heading for that group. */
+  groupTitle: string;
   /** Checkbox label. */
   label: string;
   /** Explanatory help text. */
diff --git a/packages/but-sdk/src/generated/linear/index.d.ts b/packages/but-sdk/src/generated/linear/index.d.ts
index 7d442f3225b..74b4ed15092 100644
--- a/packages/but-sdk/src/generated/linear/index.d.ts
+++ b/packages/but-sdk/src/generated/linear/index.d.ts
@@ -844,6 +844,7 @@ export interface WatcherEvent {
  * `callback` receives watcher events shaped as `{ name, payload }`.
  */
 export declare function watcherStart(projectId: string, callback: ((err: Error | null, arg: WatcherEvent) => any)): Promise<WatcherHandle>
+
 // Auto-generated by but-ts. Do not edit manually.
 // Generated from JSON schemas registered by #[but_api] functions.
 
@@ -3419,6 +3420,9 @@ export type WatcherWorktreeChangesPayload = {
   changes: WorktreeChanges;
 };
 
+/** Topic a workflow option is grouped under in the preferences UI. */
+export type WorkflowGroupId = "committing" | "branches" | "automation";
+
 /** One of the workflow preferences that render into the managed block. */
 export type WorkflowOptionId = "foldFixes" | "suggestSplits" | "stackedBranches" | "autoUpdate" | "draftPrs" | "pushToTarget" | "publishPhrase" | "branchPattern" | "commitConvention" | "commitAfterTurn";
 
@@ -3429,6 +3433,10 @@ export type WorkflowOptionId = "foldFixes" | "suggestSplits" | "stackedBranches"
 export type WorkflowOptionInfo = {
   /** Which option this describes. */
   id: WorkflowOptionId;
+  /** Topic to group this option under. */
+  group: WorkflowGroupId;
+  /** Heading for that group. */
+  groupTitle: string;
   /** Checkbox label. */
   label: string;
   /** Explanatory help text. */