diff --git a/public-docs/agent-profiles.md b/public-docs/agent-profiles.md new file mode 100644 index 0000000000..e5084c0cd4 --- /dev/null +++ b/public-docs/agent-profiles.md @@ -0,0 +1,54 @@ +--- +title: Agent profiles +description: Save agent settings for one-click selection and use notes to guide delegation for UI work, planning, and reviews. +nav: Agent profiles +order: 32 +category: Orchestration +--- + +# Agent profiles + +Save the settings you use together as a named profile. Choose **UI work**, **Planning**, or **Review** when creating an agent instead of selecting its model, thinking level, and mode each time. + +- **For you:** one selection applies the saved provider, model, mode, thinking level, and available feature settings. +- **For an orchestrating agent:** profile notes explain when to choose those settings for delegated work. + +## Create a profile + +1. Open **Settings → your host → Agents → Agent profiles**. +2. Select **New profile** and give it a name, such as **UI work**. +3. Choose its provider, model, mode, thinking level, and any available features. +4. Fill in **When to use** with the kind of work this profile should handle. +5. Select **Save**. + +Profiles are saved on that host. The available settings depend on the provider and model you choose. + +## Apply settings in one click + +When creating an agent, open the model picker and select a saved profile under **Profiles**. Paseo applies its settings together; you can still adjust them before sending your prompt. + +Changing a saved profile affects future selections. It does not update agents you already launched. + +## Guide delegation with notes + +The **When to use** field is the profile's notes. Paseo exposes these notes through its tools so an orchestrating agent can read them before choosing how to launch a worker. + +Give each profile a clear specialty: + +| Profile | Example notes | +| -------- | -------------------------------------------------------------------------------------------- | +| UI work | Use for components, layout, styling, and visual polish. | +| Planning | Use for architecture, investigating root causes, and comparing implementation approaches. | +| Review | Use for independent review of diffs, correctness, missing tests, and unnecessary complexity. | + +Each profile can use a different provider and model, or different settings for the same model. + +After [enabling Paseo tools](/docs/orchestration#get-started), ask: + +> Check my Paseo profiles and their notes. Choose one for the settings-page UI change, then use a review profile for an independent review of the diff. + +The orchestrator reads the profiles, selects settings for each task, and launches the workers. Notes guide that choice; put the worker's actual assignment in its task prompt. + +The bundled [Paseo skill](/docs/skills#paseo-paseo-reference) instructs agents to check profiles and read their notes before delegating. If none fit, it directs the agent to discover configured providers and models and tell you about the fallback. + +See [Common workflows](/docs/orchestration-workflows) for delegation examples or the [MCP reference](/docs/mcp#agent-profiles) for the tool interface. diff --git a/public-docs/cli.md b/public-docs/cli.md index f47270144a..72ad71d076 100644 --- a/public-docs/cli.md +++ b/public-docs/cli.md @@ -1,12 +1,12 @@ --- -title: CLI +title: CLI reference description: "Paseo CLI reference: manage projects, workspaces, agents, plugins, scripts, schedules, daemons, and permissions from your terminal." -nav: CLI -order: 3 -category: Getting started +nav: CLI reference +order: 35 +category: Orchestration --- -# CLI +# CLI reference The Paseo CLI lets you manage agents from your terminal. It's the same interface exposed by the daemon's API, so anything you can do in the app you can do from the command line. @@ -193,10 +193,10 @@ behavior. ## Listing agents ```bash -paseo ls # Running agents in current directory -paseo ls -a # Include completed/stopped agents -paseo ls -g # All directories -paseo ls -a -g --json # Full list as JSON +paseo ls # Non-archived agents in active workspaces +paseo ls -a # Also include archived agents +paseo ls -g # Non-archived agents across all workspaces +paseo ls -a -g --json # All agents, including archived, as JSON ``` ## Streaming output @@ -213,6 +213,8 @@ Agent IDs can be shortened, `abc` works if it's unambiguous. Send follow-up tasks to a running or idle agent: +Use the recipient's agent ID from `paseo ls`, or [copy it from the agent's tab](/docs/orchestration-workflows#send-a-prompt-to-another-agent). + ```bash paseo send "now run the tests" paseo send --image screenshot.png "what's wrong here?" diff --git a/public-docs/mcp.md b/public-docs/mcp.md index ff011f2dfc..a52327174a 100644 --- a/public-docs/mcp.md +++ b/public-docs/mcp.md @@ -2,19 +2,22 @@ title: MCP reference description: Reference for the Paseo tools agents use to manage agents, workspaces, scripts, terminals, and schedules. nav: MCP reference -order: 33 +order: 34 category: Orchestration --- # MCP reference -This is the complete catalog behind the workflows in [Orchestration](/docs/orchestration) and [Common workflows](/docs/orchestration-workflows). You normally ask for an outcome in natural language and let the agent choose the tools. +[Enable Paseo tools](/docs/orchestration#get-started) to give agents this catalog. Ask for an outcome in natural language, or use the tool interfaces below. -Paseo can inject these tools into every new agent it launches. Open **Settings → your host → Agents** and turn on **Enable Paseo tools**, or set `daemon.mcp.injectIntoAgents` to `true`. +## Configuration -Depending on the provider, Paseo delivers the catalog through its native tool interface or MCP. The capabilities are the same either way. +| Setting | Default | Purpose | +| ----------------------------- | ------- | -------------------------------------------------- | +| `daemon.mcp.enabled` | `true` | Run the MCP server. | +| `daemon.mcp.injectIntoAgents` | `false` | Give agents launched by Paseo access to its tools. | -The MCP server itself is controlled by `daemon.mcp.enabled`. Existing agents may need a reload. +Depending on the provider, Paseo delivers tools through its native tool interface or MCP. The capabilities are the same. Start a new agent or reload an existing one after changing injection settings. ## Limit Paseo tools by provider @@ -87,7 +90,7 @@ MCP does not expose an agent-detach tool. Detaching is a manual user action in t | Tool | Function | | -------------------- | --------------------------------------------------------------------------------------- | | `create_agent` | Create an agent, optionally placing it in an existing workspace with `workspaceId`. | -| `send_agent_prompt` | Send a task to a running agent. | +| `send_agent_prompt` | Send a prompt to an existing agent using its `agentId` and a `prompt`. | | `get_agent_status` | Return the latest snapshot for an agent. | | `list_agents` | List recent agents as compact metadata. | | `cancel_agent` | Abort an agent's current run but keep the agent alive. | @@ -150,6 +153,26 @@ Both use the same cron engine, but they have deliberately different interfaces. MCP heartbeats are ephemeral: create or delete them. To change one, delete it and create a replacement. Pause, resume, update, inspect, logs, and run-once apply to new-agent schedules only. +### Agent profiles + +| Tool | Function | +| --------------- | ---------------------------------------------------------------------------------------------------------------------------------- | +| `list_profiles` | Return the host's saved agent profiles, including their notes and launch settings. Returns an empty list when none are configured. | + +Before delegating, read each profile's `notes` and choose the profile the user named or the one that fits the task. See [Agent profiles](/docs/agent-profiles) for setup and example notes. + +`create_agent` has no profile parameter and requires a `provider/model` pair. If the profile has no model, call `list_models` for its provider and choose an available model for the task before launching. Apply the chosen profile's values to the launch request: + +| Profile field | `create_agent` field | +| ------------------------------- | --------------------------------------------------------------------------- | +| `provider` and optional `model` | `provider` as `provider/model`, using the saved or discovered model ID | +| `modeId` | `settings.modeId` | +| `thinkingOptionId` | `settings.thinkingOptionId` | +| `featureValues` | `settings.features` | +| `notes` | Selection guidance for the orchestrator; supply the task in `initialPrompt` | + +Omit absent optional settings. If no profile fits, use provider discovery to choose available settings. + ### Providers | Tool | Function | diff --git a/public-docs/orchestration-workflows.md b/public-docs/orchestration-workflows.md index c1b60328ab..e7e5f271c3 100644 --- a/public-docs/orchestration-workflows.md +++ b/public-docs/orchestration-workflows.md @@ -1,6 +1,6 @@ --- title: Common orchestration workflows -description: Copyable prompts for delegating, parallelizing, reviewing, and continuing agent work with Paseo. +description: Prompts for delegating, parallelizing, reviewing, and continuing agent work with Paseo. nav: Common workflows order: 31 category: Orchestration @@ -8,87 +8,96 @@ category: Orchestration # Common orchestration workflows -These examples are prompts for your main agent. Change the provider, model, task, and branch names to fit your work. +[Enable Paseo tools](/docs/orchestration#get-started), then ask your main agent for one of these workflows. Adapt the tasks to your project. [Agent profiles](/docs/agent-profiles) let you save settings and describe which agent to use for each kind of work. ## Send work to a different model -Keep a strong planner in the main chat and send implementation to a workhorse: +Keep planning in your main chat and delegate implementation: -```text -Stay as the orchestrator. Use Paseo to find the available Codex 5.6 model, then -create a worktree-isolated workspace and launch a subagent there. Ask it to -implement the parser change and run the focused tests. -``` +> Use Paseo to check my agent profiles and their notes. Choose one for implementation, create a workspace with worktree isolation, and launch a subagent there to implement the parser change. Have it run the focused tests and report back. -Ask the orchestrator to inspect providers first when you are unsure of the exact model ID. Available models come from your own installed and authenticated CLIs. +The worker makes the change in its own worktree. If no profile fits, the agent can discover your configured providers and models and tell you what it chose. ## Fan out research -Read-only work can safely share one workspace: +Split independent questions between workers: -```text -Create three Paseo subagents in this workspace. Have one trace the request path, -one inspect the tests, and one look for related regressions. Do not edit files. -Synthesize their findings when all three report back. -``` +> Create three Paseo subagents in this workspace. Have one trace the request path, one inspect the tests, and one look for related regressions. Do not edit files. Synthesize their findings when all three report back. -Each worker appears in the Subagents track, and the orchestrator can keep working while they run. +The workers share your files and appear in the Subagents track. Your main agent collects their findings into one answer. ## Parallelize edits without collisions -Give each independent implementation its own worktree-isolated workspace: +Give each independent change its own worktree: -```text -Split these two issues between two Paseo subagents. Create a separate workspace -with worktree isolation from main for each issue, use the best available -implementation model, and have each agent run the focused checks for its change. -Summarize both diffs when done. -``` +> Split these two issues between two Paseo subagents. Create a separate workspace with worktree isolation from main for each issue. Check my profiles for suitable implementation settings, and have each agent run the focused checks for its change. Summarize both diffs when done. -Use the current workspace for collaboration on the same files. Use worktrees when agents may edit independently. +Each worker edits a separate checkout. You get two changes to inspect, with their check results. ## Implement, then review -Use different models for making and judging the change: +Choose different agents for making and judging a change: -```text -Create a worktree-isolated workspace and launch a worker there to implement this -feature. When it finishes, create a second subagent in the same workspace to -review the diff for correctness, missing tests, and unnecessary complexity. -Bring the review back here. -``` +> Check my Paseo profiles and their notes for implementation and review. Create a workspace with worktree isolation and launch an implementation worker there. When it finishes, launch an independent reviewer in that workspace to check correctness, missing tests, and unnecessary complexity. Bring the review back here. -The second agent sees the worker's files without sharing its conversation context, which makes the review more independent. +The reviewer sees the worker's files in a fresh conversation. Use profiles from different providers when you want another model's judgment. + +## Send a prompt to another agent + +Agents can prompt each other by **agent ID**, the identifier Paseo uses to address a specific agent. They can communicate across workspaces on the same host, including with agents they did not launch. + +1. Right-click the receiving agent's tab and select **Copy agent id**. +2. Paste that ID into your conversation with the sending agent and ask: + +> Use Paseo to send this prompt to agent [paste agent ID here]: “Review the parser changes in your workspace and report any missing test cases.” + +The receiving agent gets the prompt in its existing conversation. To have it send a separate message back, give it the sender's agent ID too. + +Underneath, the agent calls `send_agent_prompt` with the recipient's `agentId` and a `prompt`. Agents can also discover IDs with `list_agents`; the CLI uses [`paseo send `](/docs/cli#sending-messages). For another host, use the [remote CLI workflow](#work-on-another-machine). ## Check, redirect, or continue work -The orchestrator can inspect a worker and send a follow-up without starting over: +Send these prompts separately as needed: -```text -Summarize what the subagents are doing and flag anything blocked. -``` +> Summarize what the subagents are doing and flag anything blocked. -```text -Tell the parser worker to add the malformed-input case and rerun its test file. -``` +You get a progress summary in the main conversation. -```text -Cancel the UI worker's current turn, but keep the agent so I can redirect it. -``` +> Tell the parser worker to add the malformed-input case and rerun its test file. + +The worker continues in its existing conversation. + +> Cancel the UI worker's current turn, but keep the agent so I can redirect it. + +The current task stops; the worker remains available for a follow-up. + +## Work on another machine + +The CLI can target another Paseo host. First [connect it to the remote daemon](/docs/cli#connecting-to-a-remote-daemon) and identify a workspace on that host. The repository and required provider must be available there. + +> Use the Paseo CLI with the remote host and workspace I supplied. Launch an agent there to investigate the failing build, inspect its output, and summarize the findings here. Do not change files. + +The worker runs on the remote machine. Use the CLI's global `--host` option for that destination; injected Paseo tools operate on the main agent's own host. ## Keep an agent working with a heartbeat -Use a heartbeat when the current agent should wake itself up, reassess the task, and continue working: +A heartbeat prompts the same agent periodically, preserving its conversation: -```text -Use Paseo to create a heartbeat every 10 minutes. Continue this migration in -small steps, run the focused checks after each step, and stop when the migration -is complete or after two hours. -``` +> Use Paseo to create a heartbeat every 10 minutes. Continue this migration in small steps, run the focused checks after each step, and delete the heartbeat when the migration is complete. Set it to expire after two hours. -```text -Create a heartbeat every 5 minutes to check this deployment. Investigate any -failure and report meaningful changes in this conversation. Stop after one hour. -``` +The agent resumes the task on that cadence. For a fresh agent on each run, [create a schedule](/docs/schedules) instead. -A heartbeat returns to the same conversation. For cron-style recurring work such as daily triage, use a [schedule](/docs/schedules). For reusable workflows such as handoffs, committees, advisors, and bounded loops, see [Orchestration skills](/docs/skills). +## Where the work appears + +Open the **Subagents track** near the composer to inspect delegated work. + +| | Paseo subagents | Native provider subagents | +| ------------ | ---------------------------------------------- | ---------------------------------------------- | +| Provider | Any configured provider | Chosen within the parent provider's own system | +| Workspace | Current or explicitly selected workspace | Managed by the provider | +| Conversation | Full agent session you can talk to | Read-only timeline | +| Controls | Follow up, change settings, archive, or detach | Lifecycle managed by the provider | + +A Paseo subagent in another workspace still belongs to its parent's track. It also opens as a tab in its own workspace. To make it a top-level agent, detach it in the app or with [`paseo agent detach`](/docs/cli#agent-modes). + +See the [MCP reference](/docs/mcp#mental-model) for workspace and parentage rules. diff --git a/public-docs/orchestration.md b/public-docs/orchestration.md index aec9b51f9e..74c15a36aa 100644 --- a/public-docs/orchestration.md +++ b/public-docs/orchestration.md @@ -1,6 +1,6 @@ --- title: Orchestration -description: Give any coding agent control of Paseo so it can launch and coordinate agents from other providers. +description: Coordinate agents across providers and machines, delegate work, and keep tasks moving with schedules and heartbeats. nav: Overview order: 30 category: Orchestration @@ -8,72 +8,63 @@ category: Orchestration # Orchestration -Paseo orchestration gives a coding agent control of the Paseo daemon. The agent can discover every provider and model you have configured, create workspaces, launch other agents, send them follow-ups, and create heartbeats or schedules. The same work stays visible in the Paseo app. +Paseo lets your coding agents coordinate other agents, split work across providers and machines, and keep tasks moving automatically. -## Native subagents vs Paseo subagents +## What your agents can do -The most important difference from native subagents is that **Paseo subagents can cross provider boundaries**. +- **Choose providers and models:** launch other agents using any provider and model configured on the host. +- **Delegate and parallelize:** split research, implementation, and review between agents, including agents from different providers. +- **Communicate with each other:** agents can [send prompts to other agents by ID](/docs/orchestration-workflows#send-a-prompt-to-another-agent) to ask questions, share findings, or request work. +- **Coordinate ongoing work:** check progress, stop tasks, and collect results. +- **Create workspaces and worktrees:** give independent changes their own [working directories](/docs/worktrees). +- **Work across machines:** use the [CLI](/docs/cli#connecting-to-a-remote-daemon) to launch and manage agents on another reachable Paseo host. +- **Choose by specialty:** use [agent profiles](/docs/agent-profiles) and their notes to select settings for UI work, planning, or reviews. +- **Create schedules:** run a prompt in a new agent at [specified times](/docs/schedules). +- **Create heartbeats:** prompt the same agent periodically to [continue its task](/docs/orchestration-workflows#keep-an-agent-working-with-a-heartbeat). -```text -Claude Code (Fable 5) => Codex (GPT-5.6) -Codex (GPT-5.6) => Grok Build -Cursor => Claude Code (Fable 5) +## Get started + +Use built-in Paseo tools or the CLI. Both let an agent launch and coordinate workers. + +### Built-in Paseo tools (MCP) + +Enable Paseo tools so agents running inside Paseo can manage agents and workspaces on their host directly. + +1. Open **Settings → your host → Agents**. +2. Turn on **Enable Paseo tools**. Tool injection is off by default. +3. Start a new agent, or reload an existing agent so it receives the tools. +4. Ask: + +> Use Paseo to launch a second agent to review this branch. Have it report potential bugs without changing files, then summarize its findings. + +The worker appears in the **Subagents track** near the composer. Open it to follow the conversation. Your main agent receives a notification when the worker finishes, and you can keep talking while it works. + +See the [MCP reference](/docs/mcp) for tool configuration and the full catalog. [Orchestration skills](/docs/skills) are optional reusable workflows. + +### CLI + +Agents with shell access can also use the Paseo CLI. This route does not require enabling tool injection. With Paseo installed, a running host, and Codex configured: + +```bash +paseo run --provider codex --background \ + "Review this branch without changing files" +paseo ls -a ``` -Native subagents belong to one provider. Claude Code launches Claude Code subagents; Codex launches Codex subagents. They are useful when the parent provider can handle the whole task itself. +The first command starts a worker and returns immediately; the second lists agents from active workspaces, including archived agents. When a Paseo agent runs the command, the worker becomes its subagent in the same workspace. From your own terminal, it starts in a new local workspace. -Paseo subagents are full agents managed by the Paseo daemon. The orchestrator can choose any configured provider and model, keep the worker in the current workspace, or place it in another workspace created for the task. Use them when you want one model to plan, another to implement, and another to review. +See the [CLI reference](/docs/cli) for follow-ups, output, worktrees, and remote hosts. -| | Native subagent | Paseo subagent | -| -------------------- | ----------------------------------------- | -------------------------------------------------- | -| Provider | Same provider as its parent | Any provider configured in Paseo | -| Working directory | Managed by the parent provider | Current or explicitly selected workspace | -| Lifecycle | Owned by the parent provider | Managed by Paseo; can receive follow-ups | -| Where you inspect it | Read-only timeline in the Subagents track | Full agent session in the Subagents track | -| Best for | Fast, provider-native delegation | Cross-provider work and explicit workspace control | +## Pick settings once with profiles -## Try it +Save a provider, model, thinking level, mode, and available feature settings as an **agent profile**, then select it in one click when creating an agent. -Open **Settings → your host → Agents**, then turn on **Enable Paseo tools**. Start a new agent, or reload an existing one so it receives the tools. +Add **When to use** notes so an orchestrating agent can choose a profile for the task: UI work, planning, or independent review. [Create profiles and write delegation notes](/docs/agent-profiles). -Then ask naturally: +## Go further -```text -Stay as the orchestrator. Use Paseo to find my available Codex models, then -create a worktree-isolated workspace, then launch a GPT-5.6 subagent there. Ask -it to implement the parser change, run the focused tests, and report back here. -``` - -The orchestrator discovers the provider and model IDs, starts the worker, and receives a notification when it finishes. You can keep talking to the orchestrator in the meantime. - -Agent creation has one default: when an agent creates another agent without a workspace ID, the new agent is its subagent in the same workspace. Passing a workspace ID changes where the subagent works, not who its parent is. - -## Where the work appears - -Spawned work appears in the **Subagents track** above the composer. Open a row to read the live conversation. - -Both kinds of subagent appear there: - -- **Paseo subagents** open as full agent sessions. You can talk to them directly, change their settings, or archive them. -- **Native provider subagents** open as read-only timelines. You can inspect their work, but their provider owns their lifecycle. - -A cross-workspace subagent still belongs to its parent's Subagents track. Paseo also opens its workspace so the work is not hidden in an otherwise empty workspace. If you want to turn any subagent into a top-level agent, detach it manually in the app or with `paseo agent detach`; detachment is not an agent-creation mode. - -If an agent says background work is running but the track is empty, update Paseo. Provider-created subagent timelines require Paseo 0.1.107 or newer. - -## Keep an agent working with a heartbeat - -A heartbeat sends a prompt back into the same agent on a cron cadence. Use one when the agent should keep reassessing a live task: continue a refactor, babysit CI, watch a deployment, or retry after an external system changes. - -Ask the agent directly: - -```text -Use Paseo to create a heartbeat every 10 minutes. Keep checking this PR, fix any -new CI failures, and stop when all checks pass or after two hours. -``` - -The base [`/paseo` orchestration skill](/docs/skills) teaches agents how to create heartbeats, so you only need to ask. A heartbeat continues the current conversation; a [schedule](/docs/schedules) is better for standalone cron-style jobs such as daily triage. - -You do not need to name MCP tools in your prompts. Ask for the workflow; the agent uses the tools underneath. - -Continue with [Common workflows](/docs/orchestration-workflows) for copyable prompts, [Orchestration skills](/docs/skills) for packaged workflows, or the [MCP reference](/docs/mcp) for the complete tool catalog. +- [Delegate implementation and get an independent review](/docs/orchestration-workflows#implement-then-review). +- [Run parallel changes in separate worktrees](/docs/orchestration-workflows#parallelize-edits-without-collisions). +- [Coordinate work on another machine](/docs/orchestration-workflows#work-on-another-machine). +- [Create recurring jobs](/docs/schedules) or [continue a task with a heartbeat](/docs/orchestration-workflows#keep-an-agent-working-with-a-heartbeat). +- [Install reusable orchestration skills](/docs/skills). diff --git a/public-docs/providers.md b/public-docs/providers.md index fbf5e0c84c..ea7f09e36e 100644 --- a/public-docs/providers.md +++ b/public-docs/providers.md @@ -24,5 +24,6 @@ Either way, **you install the underlying CLI**. Paseo runs it. ## Where to go next - [Supported providers](/docs/supported-providers), the full list with install links. -- [Custom providers](/docs/custom-providers), add your own provider, point an existing one at a different endpoint, run multiple profiles, or override the binary in `~/.paseo/config.json`. +- [Agent profiles](/docs/agent-profiles), save model, mode, and thinking settings together, with notes to guide delegation. +- [Custom providers](/docs/custom-providers), add your own provider, point an existing one at a different endpoint, configure multiple provider aliases, or override the binary in `~/.paseo/config.json`. - [paseo.sh/agents](/agents), per-agent landing page for each supported provider. diff --git a/public-docs/skills.md b/public-docs/skills.md index c1fae01515..c8ac09c4b6 100644 --- a/public-docs/skills.md +++ b/public-docs/skills.md @@ -1,65 +1,55 @@ --- title: Orchestration skills -description: "Paseo orchestration skills: teach coding agents to spawn, coordinate, and manage other agents using slash commands." +description: Reusable workflows for handing off tasks, getting a second opinion, and planning with multiple agents. nav: Skills -order: 32 +order: 33 category: Orchestration --- # Orchestration skills -Paseo ships orchestration skills that teach coding agents how to use Paseo tools and the CLI to spawn, coordinate, and manage other agents. Skills package common workflows as slash commands, so agents know how to orchestrate without you writing the briefing and safety rails each time. +Skills give your agents reusable instructions for delegation, handoffs, and reviews. You can also [ask for these workflows directly](/docs/orchestration-workflows) without installing skills. -Start with [Orchestration](/docs/orchestration) if you want the mental model, or [Common workflows](/docs/orchestration-workflows) for prompts you can use without installing skills. +| Skill | Use it to | +| ------------------ | -------------------------------------------------------------------- | +| `/paseo` | Look up how to manage agents, workspaces, schedules, and heartbeats. | +| `/paseo-handoff` | Transfer a task and its context to another agent. | +| `/paseo-committee` | Get two independent analyses of a difficult problem. | +| `/paseo-advisor` | Get a second opinion on your current work. | ## Installation -Two ways to install: +- **In Paseo:** Open **Settings → your host → Agents → Orchestration skills** and choose which skills to install on that host. +- **From the terminal:** Run `npx skills add getpaseo/paseo` on the machine where your agents run. -- **Paseo app:** Connect to the host, then open Settings → Host → Agents → Orchestration skills. The selected host installs the skills on its own machine. -- **Manual:** `npx skills add getpaseo/paseo`, this installs to `~/.agents/skills/` and sets up symlinks for each agent. - -When a daemon finds installed Paseo skills, it keeps the selected bundled skills up to date on startup without removing deselected directories. Use the host's Orchestration skills card to install, update, choose, or uninstall skills. Removal always asks for confirmation. +Use the same settings card to update or uninstall skills. The host also refreshes selected installed Paseo skills on startup. ## `/paseo`, Paseo Reference -The foundational skill. Paseo reference for managing projects, workspaces, and agents. Load it when an agent needs to register a project, create agents, send them prompts, or manage workspace isolation. +The foundational reference used by the other skills. It teaches agents to check your [agent profiles and their notes](/docs/agent-profiles#guide-delegation-with-notes) before delegating, then apply the selected launch settings. If no profile fits, it directs them to discover available providers and models and tell you about the fallback. -Not typically invoked directly by users, it's a reference that other skills depend on. - -``` -/paseo show me the Paseo CLI surface for creating an agent in a worktree-isolated workspace -``` +> /paseo show me how to create an agent in a workspace with worktree isolation ## `/paseo-handoff`, Task Handoff -Hands off the current task to another agent with full context. Use it when you say "handoff", "hand off", "hand this to", or want to pass work to another agent. +Transfer the current task with a briefing: relevant files, progress, decisions, constraints, and acceptance criteria. The skill checks profiles before choosing the receiving agent; you can name the profile you want. -The receiving agent gets a self-contained briefing with the task, context, relevant files, current state, what's been tried, decisions, acceptance criteria, and constraints. Provider comes from orchestration preferences unless you name one. Supports worktree-isolated workspaces when you ask for one. +> /paseo-handoff hand off the auth fix to an implementation agent in its own worktree -``` -/paseo-handoff hand off the auth fix to codex in a worktree-isolated workspace -/paseo-handoff hand this to claude opus for review -``` +The receiving agent gets the context it needs to continue. Ask for a separate worktree when it should edit independently. ## `/paseo-committee`, Committee Planning -Forms a committee of two high-reasoning agents to step back, do root cause analysis, and produce a plan. Use it when stuck, looping, tunnel-visioning, or facing a hard planning problem. +Get two agents to analyze a difficult problem independently. The skill checks profile notes for planning and analysis, preferring different provider families when possible. -Committee members do analysis only. They do not edit, create, or delete files. The orchestrating agent synthesizes their plans, implements, then sends the diff back for review. +> /paseo-committee why are the websocket connections dropping under load? -``` -/paseo-committee why are the websocket connections dropping under load? -/paseo-committee plan the auth system migration -``` +Committee members return analyses without editing files. The main agent synthesizes their plans, implements the solution, and sends the diff back for review. ## `/paseo-advisor`, Advisor -Spins up a single agent as an advisor, a second opinion on the current task. Use it when you say "advisor", "second opinion", "what does X think", or want an outside take without delegating the work itself. +Get another agent's judgment on a design, diff, or question. The skill chooses a profile whose notes fit the work, or uses the profile you name. -The advisor gives a judgment. You decide what to do. The advisor prompt is analysis-only and ends with a no-edits instruction. +> /paseo-advisor did I miss anything in this migration plan? -``` -/paseo-advisor did I miss anything in this migration plan? -/paseo-advisor --provider claude/opus what is the UX risk in this flow? -``` +The advisor returns a second opinion without editing files.