docs(skill): refactor conductor skill into slim top-level with reference files

.claude/skills/conductor/SKILL.md

@@ -1,12 +1,25 @@
 ---
 name: conductor
-description: Create, validate, and run workflows. Use when orchestrating AI agents via YAML workflow files, creating new workflows, debugging execution, configuring routing between agents, setting up human-in-the-loop gates, or understanding workflow YAML schema.
+description: Validate, run, and execute workflows; creating new workflows when explicitly asked. Use when orchestrating AI agents via YAML workflow files, executing an existing workflow, debugging execution, configuring routing between agents, setting up human-in-the-loop gates, or understanding workflow YAML schema. Only create new workflows when explicitly asked.
 ---
 
 # Conductor
 
 CLI tool for defining and running multi-agent workflows with the GitHub Copilot SDK or Anthropic Claude.
 
+> **DO NOT create new workflow files unless the user explicitly asks you to create one.** Default to running, validating, or debugging existing workflows. If the user's request is ambiguous, assume they want to run or modify an existing workflow rather than create a new one.
+
+## Error Handling
+
+> **CRITICAL — do NOT improvise workarounds.** If `conductor` fails for any reason (installation failure, provider error, missing dependency, platform bug), you MUST:
+>
+> 1. **Report the exact error** to the user — include the full error message.
+> 2. **Stop and wait for user direction.** Do NOT attempt to simulate, replicate, or approximate the multi-agent workflow yourself. The value of this skill is the structured multi-agent orchestration — a single-agent attempt is not an equivalent substitute.
+
+## Setup
+
+Conductor is installed automatically when needed. If a `conductor` command fails with "command not found", install it. For installation instructions, see [references/setup.md](references/setup.md).
+
 ## Quick Reference
 
 ```bash
@@ -49,40 +62,29 @@ Full output is shown by default. Use `-q` (quiet) for minimal output or `-s` (si
 - Validation rules
 - Type definitions
 
-## Workflow Structure Overview
+## Minimal Workflow Example
 
 ```yaml
 workflow:
   name: my-workflow
-  entry_point: first_agent
-  runtime:
-    provider: copilot               # or claude
-    default_model: gpt-5.2
-    temperature: 0.7
+  entry_point: answerer
   input:
-    question:
-      type: string
-  context:
-    mode: accumulate                # accumulate, last_only, explicit
-  limits:
-    max_iterations: 10
-  cost:
-    show_summary: true
+    question: { type: string }
 
 agents:
-  - name: first_agent
-    prompt: |
-      Answer: {{ workflow.input.question }}
+  - name: answerer
+    prompt: "Answer: {{ workflow.input.question }}"
     output:
-      answer:
-        type: string
+      answer: { type: string }
     routes:
       - to: $end
 
 output:
-  answer: "{{ first_agent.output.answer }}"
+  answer: "{{ answerer.output.answer }}"
 ```
 
+For runtime config, context modes, limits, and cost tracking, see [references/authoring.md](references/authoring.md).
+
 ## Key Concepts
 
 | Concept | Description |
@@ -101,108 +103,4 @@ output:
 | `--web` | Real-time web dashboard with DAG graph, live streaming, in-browser human gates |
 | `checkpoint` | Auto-saved on failure; resume with `conductor resume` |
 
-## Common Patterns
-
-**Linear pipeline**: `agent1 → agent2 → agent3 → $end`
-
-**Loop until quality**:
-```yaml
-routes:
-  - to: $end
-    when: "{{ output.score >= 90 }}"
-  - to: self
-```
-
-**Conditional branching**:
-```yaml
-routes:
-  - to: success_path
-    when: "{{ output.approved }}"
-  - to: failure_path
-```
-
-**Parallel execution**:
-```yaml
-parallel:
-  - name: researchers
-    agents: [web_researcher, academic_researcher]
-    failure_mode: continue_on_error
-    routes:
-      - to: synthesizer
-```
-
-**For-each (dynamic parallel)**:
-```yaml
-for_each:
-  - name: processors
-    type: for_each
-    source: finder.output.topics
-    as: item
-    max_concurrent: 5
-    agent:
-      prompt: "Process {{ item }} (index: {{ _index }})"
-      output:
-        result: { type: string }
-    routes:
-      - to: aggregator
-```
-
-**Script step** (shell command):
-```yaml
-agents:
-  - name: check_version
-    type: script
-    command: python3
-    args: ["--version"]
-    routes:
-      - to: analyzer
-        when: "exit_code == 0"
-      - to: error_handler
-```
-
-**File include** (`!file` tag):
-```yaml
-agents:
-  - name: analyzer
-    system_prompt: !file prompts/system.md
-    prompt: !file prompts/analyze.md
-```
-
-**Human gate**:
-```yaml
-- name: review
-  type: human_gate
-  prompt: "Review: {{ designer.output.summary }}"
-  options:
-    - label: Approve
-      value: approved
-      route: $end
-    - label: Revise
-      value: changes
-      route: designer
-      prompt_for: feedback
-```
-
-## Template Variables (Jinja2)
-
-```jinja2
-{{ workflow.input.param }}                  # Input parameter
-{{ workflow.name }}                         # Workflow name
-{{ agent_name.output.field }}               # Agent output
-{{ output.field }}                          # Current output (in routes)
-{{ group.outputs.agent.field }}             # Parallel group outputs
-{{ group.outputs[0].field }}                # For-each outputs (index)
-{{ group.outputs["key"].field }}            # For-each outputs (key_by)
-{% if agent is defined %}...{% endif %}     # Conditional
-{% for item in list %}...{% endfor %}       # Loop
-{{ value | default("fallback") }}           # Filter
-```
-
-## Providers
-
-| Provider | Auth | MCP Support |
-|----------|------|-------------|
-| `copilot` | `GITHUB_TOKEN` | ✅ Full |
-| `claude` | `ANTHROPIC_API_KEY` | ✅ Full |
-
-Per-agent provider override: `provider: claude` on any agent definition for multi-provider workflows.
+For pattern examples (linear, loop, conditional, parallel, for-each, human gate) and template syntax, see [references/authoring.md](references/authoring.md).

.claude/skills/conductor/references/execution.md

@@ -120,12 +120,7 @@ The command:
 
 If already up to date, prints a confirmation message and exits.
 
-**Examples:**
-
-```bash
-# Check for updates and install if available
-conductor update
-```
+**Passive update hints:** On every CLI invocation, Conductor checks for updates (cached 24 hours, 2-second timeout) and prints a one-line hint if a newer version is available. Hints only appear when stderr is a TTY and `--silent` is not set.
 
 ### conductor resume
 
@@ -337,7 +332,7 @@ conductor stop
 conductor validate workflow.yaml
 ```
 
-Catch configuration errors before execution. Reports agent count, parallel groups, for-each groups, human gates, and more.
+Catch configuration errors before execution of new workflows. Reports agent count, parallel groups, for-each groups, human gates, and more.
 
 ### Check Exit Codes
 
@@ -444,6 +439,44 @@ conductor run workflow.yaml --skip-gates
 
 Auto-selects the first option at each gate.
 
+## Interactive Interrupt
+
+During execution, press **Esc** or **Ctrl+G** to pause the workflow. An interactive menu appears with these actions:
+
+| Action | Description |
+|--------|-------------|
+| **Continue with guidance** | Provide text guidance that is appended to subsequent agent prompts |
+| **Skip to agent** | Jump to a specific agent in the workflow |
+| **Stop** | Stop the workflow entirely |
+| **Cancel** | Resume execution as-is |
+
+Guidance text accumulates across multiple interrupts and is injected into agent context.
+
+Disable with `--no-interactive`. In `--skip-gates` mode, interrupts auto-cancel.
+
+## Checkpoint & Resume
+
+When a workflow fails, Conductor automatically saves a checkpoint containing:
+- All completed agent outputs
+- Current workflow state and iteration count
+- Workflow file hash (to detect changes)
+- Failure details (agent, error type, message)
+
+Checkpoints are stored in `$TMPDIR/conductor/checkpoints/`.
+
+```bash
+# List available checkpoints
+conductor checkpoints
+
+# Resume from latest checkpoint for a workflow
+conductor resume workflow.yaml
+
+# Resume from a specific checkpoint file
+conductor resume --from /tmp/conductor/checkpoints/my-workflow-20260303-153000.json
+```
+
+If the workflow file has changed since the checkpoint was saved, a warning is displayed but resumption proceeds.
+
 ## Provider Configuration
 
 ### Override Provider
@@ -515,46 +548,7 @@ Environment variables in YAML configs support `${VAR}` and `${VAR:-default}` int
 3. [ ] Verify entry_point exists as an agent, parallel group, or for-each group
 4. [ ] Ensure all paths lead to `$end`
 5. [ ] Test with `--dry-run` first
-6. [ ] Use `-V` to trace execution with full details
-7. [ ] Check template variables are defined before use
-8. [ ] Verify for-each `source` resolves to an array
-9. [ ] Check parallel groups have 2+ agents
-10. [ ] Review cost output for unexpected token usage
-
-## Interactive Interrupt
-
-During execution, press **Esc** or **Ctrl+G** to pause the workflow. An interactive menu appears with these actions:
-
-| Action | Description |
-|--------|-------------|
-| **Continue with guidance** | Provide text guidance that is appended to subsequent agent prompts |
-| **Skip to agent** | Jump to a specific agent in the workflow |
-| **Stop** | Stop the workflow entirely |
-| **Cancel** | Resume execution as-is |
-
-Guidance text accumulates across multiple interrupts and is injected into agent context.
-
-Disable with `--no-interactive`. In `--skip-gates` mode, interrupts auto-cancel.
-
-## Checkpoint & Resume
-
-When a workflow fails, Conductor automatically saves a checkpoint containing:
-- All completed agent outputs
-- Current workflow state and iteration count
-- Workflow file hash (to detect changes)
-- Failure details (agent, error type, message)
-
-Checkpoints are stored in `$TMPDIR/conductor/checkpoints/`.
-
-```bash
-# List available checkpoints
-conductor checkpoints
-
-# Resume from latest checkpoint for a workflow
-conductor resume workflow.yaml
-
-# Resume from a specific checkpoint file
-conductor resume --from /tmp/conductor/checkpoints/my-workflow-20260303-153000.json
-```
-
-If the workflow file has changed since the checkpoint was saved, a warning is displayed but resumption proceeds.
+6. [ ] Check template variables are defined before use
+7. [ ] Verify for-each `source` resolves to an array
+8. [ ] Check parallel groups have 2+ agents
+9. [ ] Review cost output for unexpected token usage

.claude/skills/conductor/references/setup.md

@@ -0,0 +1,18 @@
+# Conductor Setup
+
+## Installation
+
+Conductor does not need to be checked before every use. Simply run `conductor` commands directly. If the command fails with "command not found", install it:
+
+```bash
+uv tool install --locked git+https://github.com/microsoft/conductor.git
+```
+
+If `uv` is also not available, install it first:
+
+```bash
+curl -LsSf https://astral.sh/uv/install.sh | sh
+```
+
+After installation, retry the original `conductor` command.
+

src/conductor/cli/app.py

@@ -839,7 +839,7 @@ def update() -> None:
     """Check for and install the latest version of Conductor.
 
     Fetches the latest release from GitHub and upgrades using
-    ``uv tool install --force``.
+    ``uv tool install --locked --force git+https://github.com/microsoft/conductor.git@v{version}``.
 
     \b
     Examples: