Create automations as plugin-spec automations in openhands-automation and the recipe skills #802

Problem

All the skills that create automations for users use the tarball presets. Presets never read the user's agent profile, so a profile with sub-agents runs without the task tool (OpenHands/automation#557). Presets are also being replaced by plugin-spec automations (OpenHands/automation#612). An agent following these skills therefore creates the kind of automation that ignores the profile.

Where, at 47f679e:

• skills/openhands-automation/SKILL.md:
  • rule 1, "default to preset endpoints";
  • the endpoint table, which marks preset/prompt "recommended";
  • the Prompt Preset and Plugin Preset sections.
  • It never mentions POST /v1/plugin-spec or agent profiles.
• skills/openhands-automation/README.md: its examples are prompt presets.
• Recipe skills that end by creating a prompt preset:
  • incident-retrospective
  • linear-triage
  • research-brief
  • slack-standup-digest
  • upstream-fork-sync, which also passes repos

Proposed change

• openhands-automation: make plugin-spec automations the default for work that needs an LLM.
  • A prompt-style task becomes POST /v1/plugin-spec, created from plugins/prompt-task (feat(plugins): add prompt-task, the stock plugin for prompt automations #799), with the prompt in config.prompt and an agent_profile_id the user picks from GET /api/agent-profiles.
  • Check GET /v1/capabilities for pluginSpecAgentProfiles. Use a preset only when it's missing, or for a feature plugin-spec doesn't cover yet (see below).
  • Document authoring an executable plugin for what the plugin preset does today.
  • Describe the presets as legacy.
• Recipe skills: create their automation the same way, with the recipe's prompt in config.prompt.

Blocked on

• feat: copy the run's agent profile into its cloud sandbox automation#614 and feat: let users choose a plugin-spec automation's agent profile automation#615 being merged and released. They make plugin-spec runs launch from the profile on OHE, add agent_profile_id, and render the prompt from config. The needs-automation-release label tracks this.
• feat(plugins): add prompt-task, the stock plugin for prompt automations #799 (plugins/prompt-task) being merged.
• Repo cloning for plugin-spec runs ([Feature]: Clone an automation's repositories in plugin-spec runs automation#617), which the main skill's repos guidance and upstream-fork-sync need.
• Plugin-spec has no A/B variants (references/ab-testing.md) and no per-automation model, because the profile owns the model. Until it does, these stay documented as preset-only.

Acceptance criteria

• On a service that advertises pluginSpecAgentProfiles, following openhands-automation for a prompt-style task creates a POST /v1/plugin-spec automation from plugins/prompt-task with the chosen agent_profile_id, and its runs launch from that profile.
• The five recipe skills create plugin-spec automations the same way, with upstream-fork-sync once [Feature]: Clone an automation's repositories in plugin-spec runs automation#617 lands.
• The presets appear only as legacy, or for variants and model.
• Repo checks pass (pytest tests/, scripts/sync_extensions.py --check).

I'm an AI agent (Claude Code) helping @simonrosenberg.

OpenHands AI triage

The following comments and acceptance criteria were added by the OpenHands AI agent.

Triage

Scope: change the agent-facing automation-creation guidance in skills/openhands-automation (SKILL.md, README.md) and the five recipe skills so a prompt-style task is created as a plugin-spec automation (POST /v1/plugin-spec) from plugins/prompt-task (#799) with the task text in config.prompt and the agent_profile_id the user picks from GET /api/agent-profiles, gated on pluginSpecAgentProfiles in GET /v1/capabilities. The plugins/prompt-task manifest at the PR #799 head already declares entrypoint.runner: "conversation", entrypoint.arguments: "{{ config.prompt }}", runtime.agent_profile.required: true, and a required prompt in config_schema, and CreatePluginSpecAutomationRequest accepts agent_profile_id on the #615 branch, so the request shape is fixed by the repository, not invented here. plugins/openhands/commands/create.md is the same guidance surface (it currently says "Always use the preset/prompt endpoint") and is included so the "presets appear only as legacy" criterion holds across the repository.

Dependencies: this issue is explicitly blocked on OpenHands/automation#614 and #615 being merged and released, on #799, and on OpenHands/automation#617 for repos/upstream-fork-sync. Those gate the plugin-spec path working end to end, not the ability to author the guidance, so this is ready to develop alongside them, consistent with the sibling #800.

Non-goals: no changes to the prompt/plugin preset endpoints or their behavior; no Automation Service, SDK, or Agent Canvas code; no marketplace or automations/catalog manifest changes (the host derives the create endpoint per AGENTS.md); no A/B variants or per-automation model support for plugin-spec, which stay documented as preset-only until OpenHands/automation adds them.

Acceptance Criteria

• skills/openhands-automation/SKILL.md documents plugin-spec as the default for LLM work: a prompt-style task is created with POST /v1/plugin-spec, the plugin naming plugins/prompt-task, the task text in config.prompt, and the agent_profile_id the user chose from GET /api/agent-profiles; the skill no longer marks /v1/preset/prompt "recommended".
• The skill instructs the agent to read GET /v1/capabilities and use the plugin-spec path when pluginSpecAgentProfiles is present, and to fall back to a preset (with the reason stated to the user) only when that feature is absent.
• Each of incident-retrospective, linear-triage, research-brief, slack-standup-digest, and upstream-fork-sync creates its automation through POST /v1/plugin-spec with the recipe's constructed prompt in config.prompt and a selected agent_profile_id; none of the five still posts to /api/automation/v1/preset/prompt. upstream-fork-sync keeps cloning its repository once repo cloning for plugin-spec runs ([Feature]: Clone an automation's repositories in plugin-spec runs automation#617) is available.
• Presets are described as legacy: no agent-facing automation-creation guidance (skills/openhands-automation/SKILL.md, skills/openhands-automation/README.md, plugins/openhands/commands/create.md, and the five recipe skills) still instructs always using a preset for prompt-style tasks, and the only preset-only uses named are A/B variants and per-automation model.
• skills/openhands-automation/SKILL.md documents how to author an executable plugin for the capabilities the plugin preset covers today, and the README examples use the plugin-spec path.
• Repo checks pass: pytest tests/ and python scripts/sync_extensions.py --check.