Repository navigation
docs: document plugin-spec automations - #794
Conversation
Co-authored-by: openhands <openhands@all-hands.dev>
Co-authored-by: openhands <openhands@all-hands.dev>
Co-authored-by: openhands <openhands@all-hands.dev>
Co-authored-by: openhands <openhands@all-hands.dev>
all-hands-bot
left a comment
all-hands-bot
left a comment
There was a problem hiding this comment.
This review was posted by an AI agent (OpenHands).
Scope assessment. This change edits skills/openhands-automation, which is this repository's job - AGENTS.md says to put reusable skills and plugins here - so it should not move repositories or close on ownership grounds.
It does need a product/architecture decision before merge.
The PR's stated purpose and its Closes #816 link are additive documentation: #816 asks for plugin-spec to be documented "alongside prompt presets, plugin presets, and custom scripts", and its acceptance criteria require the README to name plugin-spec "without removing or reframing the existing preset and custom-script guidance". #816's own triage is explicit that "Repositioning the presets as legacy, or making plugin-spec the default and preferred creation path, belongs to issue #802 ... It is a non-goal here even though PR #794 also makes those edits."
This PR makes exactly that repositioning anyway:
skills/openhands-automation/SKILL.mdnow ranks plugin-spec first as "Preferred" in## Creating Automations, and its "Choosing the Right Preset" table demotes the prompt and plugin presets to one-off/fallback roles.skills/openhands-automation/README.mdnow frames custom scripts as warranted "only when the user needs full packaging ... outside the preferred plugin-spec path", and the prompt preset as "one-off".
That is the direction owned by the still-open issue #802, which carries needs-automation-release. Its blocking upstream items are not settled: OpenHands/automation#614 and #615 (agent-profile propagation and selection), OpenHands/automation#617 (repo cloning in plugin-spec runs), and #799 (plugins/prompt-task) all remain open. Making plugin-spec the skill's default before that direction lands steers agents and users toward the higher-friction git-repo-plus-manifest path that #802 is gated on.
Decision for a maintainer: either narrow #794 to the additive documentation #816 requests and leave the "preferred creation path" repositioning to #802 once its needs-automation-release blockers clear, or have #794 explicitly absorb #802's direction and reconcile the two issues.
🛑 MAINTAINER DECISION REQUIRED
|
Decision on the review at #794 (review): keep the scoped preferred-path guidance in this PR. I updated the original ticket, #816, so plugin-spec is the preferred way to create reusable, code-backed, or deterministic automations that can be packaged as executable plugins (using the This is not a blanket switch for prompt-style LLM tasks. #802 still owns the profile-aware prompt-task default and recipe-skill migrations; its dependencies OpenHands/automation#614, OpenHands/automation#615, OpenHands/automation#617 and #799 remain open. Until they land, retain prompt presets for one-off reasoning and plugin presets where there is no executable plugin-spec contract; do not call every preset legacy. One remaining inconsistency before merging #794: the endpoint table still labels This comment was created by an AI agent (OpenHands) on behalf of the user. |
all-hands-bot
left a comment
all-hands-bot
left a comment
There was a problem hiding this comment.
This review was posted by an AI agent (OpenHands). (Fresh pass on head aec34e56; a prior review exists on this SHA, but the maintainer decision on 2026-10-27 superseded its scope concern, so the technical review proceeds.)
Scope, re-checked against current state. The change edits skills/openhands-automation, which this repository owns. Issue #816 has since been updated to explicitly include the preferred-path guidance and its acceptance criteria, and the maintainer decision of 2026-10-27 keeps the scoped preferred-path guidance in this PR while leaving the prompt-style default to #802. The earlier maintainer-decision blocker is therefore resolved; this is no longer a scope stop.
Verification on this head. All GitHub Actions checks on aec34e56 are green: the single Validate PR description failure completed at 19:48:29Z on 2026-10-21 and was succeeded by a passing run of the same check at 19:49:00Z on the same SHA; test, check, sync-extensions, and sync-sdk-skill all pass. In the workspace: node scripts/build-skills-catalog.mjs leaves skills/index.js unchanged, uv run --group test pytest tests/test_skills_catalog.py -x passes all 50 tests, the full suite passes (1420 passed, 23 skipped), and python scripts/sync_extensions.py --check passes with only pre-existing non-blocking coverage warnings. All JSON examples in the new plugin-spec section parse as valid JSON, and the documented request fields, manifest schema, runner contracts, profile rules, HTTP 422 behaviors, update semantics, and credential-free source examples match the implemented contract described in #816's acceptance criteria.
Remaining finding. One material inconsistency is left, also flagged in the maintainer's 2026-10-27 comment and required by #816's acceptance criteria: the Automation Endpoints table still labels /api/automation/v1/preset/prompt unconditionally as "(recommended)". The PR itself now positions plugin-spec as the preferred path and the prompt preset as one-off LLM work (in Creating Automations, the agent behavior rules, and the Choosing the Right Preset table), so the table contradicts the rest of the PR and the issue it closes. Once that label is qualified or removed, this is ready to merge.
🔄 CHANGES REQUESTED
Co-authored-by: openhands <openhands@all-hands.dev>
all-hands-bot
left a comment
all-hands-bot
left a comment
There was a problem hiding this comment.
This review was posted by an AI agent (OpenHands).
Scope. The change edits skills/openhands-automation, which this repository owns per AGENTS.md. Issue #816 (now priority:medium, ready-for-dev) explicitly includes the preferred-path guidance in its requirements and acceptance criteria, and #802 continues to own the prompt-style default; the PR's scoped wording is consistent with that split. No maintainer decision is pending.
Verification on head cae1a6d. All GitHub Actions checks on this SHA pass, including test, check, sync-extensions, sync-sdk-skill, and Validate PR description. In the workspace, node scripts/build-skills-catalog.mjs leaves skills/index.js unchanged, uv run --group test pytest tests/test_skills_catalog.py -x passes all 50 tests, and the full suite passes (1420 passed, 23 skipped). All JSON examples in the plugin-spec section parse as valid JSON.
Finding resolved. The previously flagged inconsistency - the endpoint table labeling /api/automation/v1/preset/prompt unconditionally as "(recommended)" - is fixed in cae1a6d: the row now reads "Create one-off automations from a prompt", the review thread is resolved, and no "recommended" label remains anywhere in SKILL.md or README.md. This matches the scoped preference in #816 and the maintainer's 2026-10-27 comment. The endpoint table is now consistent with the creation rules, agent behavior rules, and the Choosing the Right Preset table. No remaining material findings; the documentation accurately reflects the plugin-spec contract (request fields, manifest schema, runner rules, profile behavior, HTTP 422 cases, update semantics) with credential-free source examples.
✅ APPROVED
|
🚀 Released in v0.37.0. |
HUMAN:
Documenting plugin-spec automations in the automation skill so users know about the preferred path for reusable/code-backed automations.
AGENT:
Why
The automation skill documented prompt presets, plugin presets, and custom scripts but did not cover plugin-spec automations (
POST /api/automation/v1/plugin-spec), the preferred path for reusable, code-backed, and deterministic automations. Users and agents had no reference for the manifest schema, runtime profiles, entrypoint runners, config schema, or suggested trigger templates.Summary
/api/automation/v1/plugin-specto the automation skill endpoint reference..plugin/plugin.jsonautomationmetadata,config_schema,suggested_trigger_template, runtime profile requirements, runners, and update behavior.skills/index.jsto keep the skills catalog in sync with the updated SKILL.md content.Issue Number
Closes #816
How to Test
node scripts/build-skills-catalog.mjsand confirmskills/index.jsis unchanged (already regenerated in this PR).uv run --group test pytest tests/test_skills_catalog.py -xand confirm all 50 tests pass.skills/openhands-automation/SKILL.mdandskills/openhands-automation/README.mdfor accuracy against theOpenHands/automationimplementation.Notes
This PR was created by an AI agent (OpenHands) on behalf of the user.