orca/docs/reference/agent-skill-auto-update-plan.md

Agent Skill Auto-Update Design

Summary

Orca should record when a user or agent enters a workflow that needs an Orca-managed agent skill, then ask about missing/outdated setup after the next Orca restart. The restart-time check should update automatically only when Orca can prove it is updating the same tracked install the user already has. When Orca cannot prove that but has a safe manual install/update command, the restart prompt should show a contextual setup/update modal instead.

Settings must not trigger background skill updates. Settings may continue to show status and manual controls.

Automatic managed-skill updates are experimental and off by default. Users can opt in from the Experimental settings pane; when disabled, Orca still records the same workflow triggers, but stale global managed-skill updates fall back to the contextual manual update modal on the next restart instead of running in the background.

Goals

• Avoid sending users to Settings -> CLI for routine skill maintenance.
• Keep managed Orca skills current without interrupting the workflow that revealed the need.
• Avoid surprising writes to user-managed, project-managed, remote, or ambiguous skill installs.
• Avoid repeated subprocess/network work when many agents attempt the same skill.
• Explain any modal in the context that caused it, especially when an agent triggered the need.

Non-Goals

• Do not build a generic updater for every skill on the Skills page.
• Do not silently update bundled, plugin, hand-copied, local-path, or user-authored skills.
• Do not run broad skill checks at app startup; only re-check previously recorded managed-skill workflow needs.
• Do not infer update scope from Orca's current working directory.

Managed Skills

Initial support is limited to Orca-owned feature skills:

• orca-linear
• orchestration
• computer-use
• orca-cli

Core UX Rule

Auto-update and ask prompts have the same deferred trigger.

User or agent enters a workflow that needs a managed skill
-> Orca records that managed skill need for the next launch
-> after Orca restarts, coordinator checks whether background update is safe
-> if safe, update in the background
-> if unsafe or update fails and Orca has a safe manual command, show the contextual modal
-> otherwise return fallback state without opening an unactionable modal

There is no separate "ask" trigger. Asking is the restart-time fallback path for the same recorded intent boundary.

The automatic-updates setting does not create a new trigger. It only controls whether an eligible stale global install may be updated quietly when the recorded request is flushed after restart. Because the setting is off by default, that same restart-time flush shows the update modal when an update is needed unless the user has explicitly enabled experimental automatic updates.

Deferred Intent Triggers

Skill	Trigger
orca-linear	User starts a new worktree from a Linear task, or launches/continues an agent workflow attached to a Linear issue where agents are expected to read or update the issue.
orchestration	User starts an orchestration workflow, such as /orchestration, handoff, child-agent coordination, or an explicit orchestration enable/use action.
computer-use	User starts a Computer Use workflow, or an agent first attempts to invoke computer-use for the active task.
orca-cli	A workflow that depends on the Orca CLI skill starts, such as Browser Use, mobile emulator agent workflows, or another feature that explicitly needs Orca CLI affordances.

Settings pages, setup guide status cards, and generic skill browsing should not record deferred automatic updates. They can display status and manual actions.

The Experimental settings pane exposes the opt-in experimental preference as "Automatically update verified Orca skills" with copy explaining that Orca can update verified Orca-managed global skills in the background only after a workflow has recorded the need and the safe update path has been proven on restart. Leaving it off means updates are reviewed manually after restart.

Modal Copy Requirements

When the fallback modal appears after restart, the modal must name the feature context and workspace. Do not claim that an agent attempted the skill unless the triggering surface can prove that; runtime and workflow entry points can also be initiated directly by the user.

Examples:

• "Orca Orchestration was used in octopus. Update the orchestration skill to enable agents to coordinate reliably."
• "The Orca CLI skill is needed in octopus. Update the CLI skill to enable this workflow to continue reliably."
• "A worktree was started from a Linear task in octopus. Install the Linear agent skill to enable agents to read and update Linear issues."

When a safe command is available, the modal should show the exact command Orca would run or wanted the user to run. When no safe command is available, it should explain why Orca cannot update automatically and offer a re-check after the user fixes the install/runtime state.

Safety Model

Orca must not choose scope from preference or cwd. It must choose scope from the existing install.

Auto-update is eligible only when all checks pass:

1. The skill is one of the managed Orca skills.
2. The workflow trigger requires that skill.
3. Discovery finds an existing install for the current runtime.
4. Discovery identifies a concrete runtime target: host or a specific WSL distro.
5. Discovery identifies a concrete scope:
   • home means global/user scope.
   • repo means project scope.
6. The matching lock file contains an entry for the skill.
7. The lock entry has enough update metadata for the skills CLI to update non-interactively.
8. The source is expected to be updateable without interactive auth.
9. The active project runtime is not repair-required.
10. The coordinator has not recorded a recent failed attempt for the same skill/runtime/scope.

For the first version, auto-update should be limited to tracked global installs. Project-scoped installs should use the same trigger and show a manual-review fallback until project-scope behavior and a safe explicit update command are proven.

Scope Resolution

Do not run:

npx skills update -y

Plain -y skips prompts and lets the skills CLI infer project vs global scope from cwd. That is not safe for background maintenance.

For global installs, run an explicit global command:

npx --yes skills update <skill> --global --yes

For future project support, run an explicit project command from the project root:

npx --yes skills update <skill> --project --yes

For WSL, wrap the explicit command with the selected WSL distro command path used by the existing setup UI.

Symlinks should be resolved with realpath for dedupe, but symlink targets must not override visible scope. A skill visible under a global home root remains global. A skill visible under a repo root remains project-scoped.

Coordinator Design

Add one central managed-skill update coordinator in the main process.

The coordinator key is:

skillName + runtime + distro + scope

Responsibilities:

• Read discovery results and lock metadata.
• Decide whether auto-update is eligible.
• Serialize update attempts per key.
• Deduplicate in-flight checks and updates.
• Cache success for the current app version/session.
• Store failure cooldowns.
• Refresh skill discovery after success.
• Return fallback information when auto-update is unsafe or failed.

Renderer surfaces should not independently spawn update commands. Workflow surfaces should record a restart prompt request; the restart flush should call the coordinator and then either clear resolved requests, show an actionable modal response that includes a manual command, or avoid interrupting for non-actionable fallback state.

Performance Guardrails

The update path must be cheap when many agents are running.

• Do not check on every tool call or every render.
• Do not run one subprocess per agent.
• Do not run network/npm work repeatedly for the same skill/runtime/scope.
• Share one in-flight promise across all callers.
• Cache success for the current app version/session.
• Back off after failure.
• Prefer invalidating "needs check" after an Orca app update, then checking only after a recorded workflow need is flushed on restart.

Example:

50 agents attempt orchestration
-> first attempt records orchestration for the next restart
-> repeated attempts dedupe to the same restart prompt request
-> next Orca launch flushes one update/check

Invalidation

The default invalidation should be app-version based.

Orca app updates
-> managed skill check state is invalidated
-> next workflow trigger records a restart prompt request
-> next Orca launch checks each recorded skill/runtime/scope once
-> success is cached for the session/app version

This matches the likely reason managed Orca skills need updating: Orca changed what agents need.

Optional future invalidation:

• Manual "Re-check" or "Update" from Settings.
• Lockfile mtime changes.
• Skill directory mtime changes.
• A long TTL if managed skills are expected to change independently of app releases.

Risks And Mitigations

Risk	Mitigation
Wrong scope gets updated	Never use cwd inference; require discovery scope plus matching lockfile; use explicit --global or --project.
User has both global and project installs	Treat as ambiguous unless the active workflow has a single proven scope; show a manual-review fallback instead of guessing.
User has custom/local/hand-copied skill	Require lock metadata; show a manual-review fallback if metadata is missing, malformed, or not Orca-managed.
Copy-mode installs are recreated as symlinks by upstream CLI	Avoid auto-update unless install metadata is trusted; call this out only when the fallback/manual path is actionable.
Private repo or auth-gated source needs credentials	Do not auto-update when source/auth cannot be proven non-interactive; show a manual-review fallback rather than running a command.
WSL distro unavailable or project runtime repair-required	Do not run host update commands; show runtime-context fallback guidance and allow re-check after repair.
SSH/remote filesystem update writes somewhere unexpected	Do not auto-update remote/SSH skills in v1.
Modal appears unexpectedly because a workflow triggered it	Workflow triggers only record restart prompts; modal copy must name the feature context and workspace without guessing whether an agent or user initiated it.
50 agents cause 50 checks	Central coordinator with in-flight dedupe, success cache, and failure cooldown.
User leaves automatic updates off	Keep the same deferred triggers, but return the manual update modal for stale global installs after restart without cooling that disabled-path modal away.
Update command hangs or npm/network is slow	Add timeout, cancellation on app shutdown where possible, and emit a modal only when a manual command is available.
Upstream skills CLI lacks reliable dry-run status	Do not show stale status unless backed by coordinator evidence; use update command only after eligibility passes.
Supply-chain/source surprise	Limit to Orca-managed skill names and tracked lock entries; do not update arbitrary Skills page entries.
Update succeeds but running agents keep old skill context	Treat update as best effort for future invocations; do not restart or mutate already-running agent prompts.

User Flow

1. User starts a workflow that needs a managed skill.
2. Orca records the skill name and workflow context as a restart prompt request.
3. After Orca restarts, the renderer flushes recorded restart prompt requests.
4. Coordinator returns one of:
   • ready: installed and recently checked.
   • updated: Orca verified and ran the single-skill global update command successfully.
   • fallback: return reason and optional command.
5. For ready and updated, remove the persisted restart prompt request.
6. For fallback, show the contextual modal for actionable setup/manual-review states and keep cooldown/unsupported internal states silent.

Implementation Steps

1. Extend discovery with canonical realpath fields while preserving visible root and source kind.
2. Add lockfile readers for global and project skills CLI metadata.
3. Add a managed-skill coordinator in main:
   • eligibility evaluation
   • explicit-scope command execution once the verified CLI contract is available
   • host/WSL routing
   • in-flight dedupe
   • app-version/session success cache
   • failure cooldowns
4. Add IPC:
   • skills:ensureManagedReady
   • skills:deferManagedReadyPrompt
   • skills:flushRestartPrompts
5. Wire the deferred intent boundary triggers:
   • Linear worktree-from-task and linked Linear agent workflow.
   • Orchestration workflow start.
   • Computer Use workflow start or first runtime invocation.
   • Browser Use/mobile emulator workflow start for orca-cli.
6. Add contextual modal copy and fallback reason handling.
7. Add the experimental opt-in automatic managed-skill updates setting in Agents settings.
8. Keep Settings manual update/status behavior separate from automatic update triggers.

Tests

• Global tracked skill update eligibility and verified single-skill npx execution.
• Project tracked skill falls back in v1.
• Same skill in global and project scope falls back as ambiguous.
• Symlinked visible global install remains global after realpath.
• Missing lock entry falls back.
• Legacy or local lock entry falls back.
• WSL runtime fallbacks do not open dead-end setup modals until WSL commands are supported.
• 50 concurrent requests for one skill produce one update attempt.
• Failure cooldown prevents repeated attempts.
• Default-disabled automatic updates show the manual update modal after restart for each recorded stale-update trigger.
• App-version invalidation re-enables a single check after update.
• Agent-triggered fallback modal includes the recorded triggering context after restart.

Recommended First Version

Ship the coordinator and deferred intent-boundary triggers with restart-prompt behavior by default. Keep automatic updates available as an experimental opt-in for tracked global Orca-managed installs only. When enabled, the coordinator runs the explicit single-skill global update command after restart-time discovery and lockfile validation, then verifies the post-update install before reporting updated. Everything else uses the same deferred trigger and returns fallback state; actionable fallback states open a contextual modal after restart.

This covers the common setup path from Orca's own install buttons while protecting custom, project, remote, and ambiguous installs.