fix(openhands-automation): stop steering agents away from deterministic scripts

[enyst]

• A human has tested these changes.

---

Why

The skill's rule 0 tells the agent to prefer a no-LLM custom script for deterministic tasks, but the rest of the text pulls toward the prompt preset: the prompt examples model deterministic tasks, the custom-automation reference opens with a "do not use unless explicitly requested" warning, there is no complete no-LLM example in the body, and custom scripts carry an extra consent step that presets do not. An agent follows the weight of the document, not the rule.

Summary

• Replace prompt-preset examples that model deterministic tasks (hourly health check, run tests on push, weekly temp-file cleanup) with tasks that need judgment: Sentry error triage, bug-ticket reproduction, weekly dependency review, flagging risky pushes to main.
• Delete the stop-sign warning at the top of references/custom-automation.md and list deterministic tasks as a first-class reason to use the custom path.
• Add a complete no-LLM worked example (hourly health check with a Slack alert: script, tarball, upload, create) next to the prompt-preset examples.
• Collapse rules 2 to 4 into one symmetric rule: present prompt preset, plugin preset, and custom script side by side and build what the user picks. The existing "ready to deploy?" confirmation applies to every path. Matching one-sided sentences in "Choosing the Right Preset" and "Reference Files" are rewritten, and a duplicated references/security.md bullet is removed.
• Regenerate skills/index.js.

Issue Number

Fixes #685

How to Test

uv sync --group test
uv run python scripts/sync_extensions.py --check
uv run pytest -q tests/test_skills_catalog.py tests/test_catalogs.py tests/test_sync_extensions.py tests/test_skill_plugin_loading.py tests/test_sdk_loading.py

All pass locally (179 tests). The new example script was extracted from the Markdown and run directly: it compiles, exits 0 on a 200 response, and takes the failure path with exit 1 on an unreachable URL.

To check the behavioral change, load the skill into a conversation and ask for "post a reminder to Slack every 5 minutes". The agent should present the custom-script option next to the presets with a cost note, rather than defaulting to the prompt preset or asking for extra permission to write a script.

Video/Screenshots

Not applicable; Markdown and generated catalog changes only.

Notes

Text only; no change to the automation API or to what the presets do. The regenerated skills/index.js diff is the updated content string for this one skill.

🤖 Generated with Claude Code

[all-hands-bot]

This review was posted by an AI agent (OpenHands).

Summary

The change does what the linked issue (#685, ready-for-dev, priority:low) asks for: the deterministic prompt examples are replaced with agent-shaped ones (Sentry triage, bug reproduction, dependency review, risky-push review), the stop-sign warning at the top of references/custom-automation.md is gone and deterministic tasks are now a first-class reason to use the custom path, a complete no-LLM worked example is added, and rules 2-4 are collapsed into one symmetric rule. I verified in the workspace that skills/index.js is regenerated (node scripts/build-skills-catalog.mjs produces no further diff), uv run python scripts/sync_extensions.py --check passes, and the focused suite is green (179 passed). All check runs on the head are green. Scope is correct for this repository: it is a skill-content change only, with no API or preset behavior change.

Two non-blocking but real defects remain, both caused by incomplete follow-through on this same edit.

1. Dangling rule cross-reference after the renumbering (inline)

Collapsing rules 2-4 shifts the webhook-reachability rule from 5 to 4, but the in-body pointer near Polling as a Webhook Alternative still reads (see rule 5). There is no rule 5 any more, so an agent following that pointer lands nowhere. Anchored inline at the renumbered rule.

2. README.md was not updated, contrary to the issue's acceptance criteria and the repo convention

skills/openhands-automation/README.md is untouched by this PR (git diff HEAD~1 HEAD -- .../README.md is empty). It still frames the prompt preset as (recommended) in the Features list and describes custom automations as being For advanced users who need full control - exactly the imbalance this PR removes from SKILL.md. The issue's triage acceptance criteria explicitly require the README to stop presenting the prompt preset as the recommended default, and AGENTS.md states: "If you change a skill's behavior or scope, update its README.md (if present) accordingly." The README also still calls /preset/prompt "(recommended)" in prose while SKILL.md moved to an even-handed framing, so the two artifacts now disagree. This is the one acceptance criterion the PR does not meet; adding a short README edit closes it.

Everything else I checked holds up: the new example script compiles, the references/custom-automation.md "when to use" list names deterministic tasks first, the duplicated references/security.md bullet is removed, and no remaining preset example matches a rule 0 instant-recognition pattern (the residual "Generate a weekly status report" / "Daily Report" string is generic enough to be judgment-based and is pre-existing).

🔄 CHANGES REQUESTED

[all-hands-bot]

This rule was renumbered from 5 to 4 by this PR, but the cross-reference near Polling as a Webhook Alternative further down still says (see rule 5). Rule 5 no longer exists, so the pointer is dangling. Update that sentence to (see rule 4).