@openhands/extensions 0.17.0 → 0.18.0

package/automations/catalog/github-agents-md-maintainer/manifest.json

@@ -0,0 +1,96 @@
+{
+  "id": "github-agents-md-maintainer",
+  "name": "AGENTS.md Maintainer",
+  "category": "Documentation",
+  "icon": "bot",
+  "description": "Keep AGENTS.md current in your repositories. On a schedule, an agent reads the repository, creates or updates AGENTS.md, and opens a pull request - and stays quiet while one of its pull requests is still open.",
+  "requires": {
+    "integrations": {
+      "github": {
+        "message": "Used to read the repository, push the branch, and open the pull request."
+      }
+    },
+    "features": [
+      "customTarball"
+    ]
+  },
+  "popularityRank": 80,
+  "estimatedSetupMinutes": 3,
+  "exampleImplementation": "Trigger: cron, weekly by default (0 9 * * 1)\nRequired secret: GITHUB_PERSONAL_ACCESS_TOKEN, with permission to write contents and pull requests\n\n1. Read the repositories, branch prefix, pull request mode, and schedule from setup.\n2. Process each repository independently, with its own state, so one falling behind never blocks another.\n3. Key one unit of work to the ISO week, so a cron that fires more often, a retried run, or a restarted service cannot open the same pull request twice.\n4. Skip a repository whose previous pull request from this automation is still open; a second one would edit the same file.\n5. Ask GitHub whether AGENTS.md exists, which decides create vs update and the pull request title.\n6. Clone the default branch into a directory of its own, create the working branch, and start an OpenHands conversation with that directory as its workspace.\n7. The agent reads the repository, edits AGENTS.md, commits, pushes, and opens the pull request; the script verifies that on GitHub and opens it itself when the agent did not.\n8. Record no-changes when AGENTS.md is already accurate, which is the expected result most weeks.\n9. Remove the clone once the conversation has stopped.",
+  "setup": {
+    "version": "1.0",
+    "mode": "direct",
+    "form": {
+      "triggers": {
+        "cron": {
+          "schedule": {
+            "type": "cron",
+            "label": "Check frequency",
+            "help": "How often to review AGENTS.md. Work is keyed by ISO week, so a schedule more frequent than weekly only polls.",
+            "default": "0 9 * * 1",
+            "required": true
+          },
+          "timezone": {
+            "type": "timezone",
+            "label": "Timezone",
+            "help": "Timezone the schedule is interpreted in.",
+            "default": "UTC",
+            "required": true
+          }
+        }
+      },
+      "args": {
+        "repositories": {
+          "type": "repo-picker",
+          "label": "Repositories",
+          "help": "The repositories whose AGENTS.md is maintained. Each keeps its own state and its own weekly claim.",
+          "provider": "github",
+          "multiple": true,
+          "required": true
+        },
+        "branchPrefix": {
+          "type": "text",
+          "label": "Branch prefix",
+          "help": "Branches are named after this prefix and the ISO week, such as openhands/agents-md-2026-W34. It is also how the automation recognises its own open pull requests.",
+          "default": "openhands/agents-md",
+          "required": true,
+          "constraints": {
+            "minLength": 1,
+            "maxLength": 50
+          }
+        },
+        "pullRequestMode": {
+          "type": "select",
+          "label": "Pull request mode",
+          "help": "Whether the pull request is opened as a draft or ready for review.",
+          "default": "draft",
+          "required": true,
+          "options": [
+            {
+              "value": "draft",
+              "label": "Draft"
+            },
+            {
+              "value": "ready",
+              "label": "Ready for review"
+            }
+          ]
+        }
+      }
+    },
+    "bundle": {
+      "version": "1.0.0",
+      "entrypoint": "python3 main.py",
+      "timeout": 900,
+      "files": {
+        "main.py": "skills/github-agents-md-maintainer/scripts/main.py"
+      },
+      "config": {
+        "repos": "{{form.repositories}}",
+        "branch_prefix": "{{form.branchPrefix}}",
+        "pull_request_mode": "{{form.pullRequestMode}}"
+      }
+    },
+    "message": "This deployment cannot run the scheduled AGENTS.md automation directly. Set it up in this conversation instead: confirm the repositories to maintain, the branch prefix, whether pull requests open as drafts, and the schedule, then create the automation."
+  }
+}

package/automations/catalog/github-issue-to-pr/manifest.json

@@ -0,0 +1,107 @@
+{
+  "id": "github-issue-to-pr",
+  "name": "GitHub Issue to PR Agent",
+  "category": "Software development",
+  "description": "Watch for a configurable label on GitHub issues, implement the issue in a clone of the default branch, and open a pull request for each label event.",
+  "requires": {
+    "integrations": {
+      "github": {
+        "message": "Used to read labelled issues, push the branch, and open the pull request."
+      }
+    },
+    "features": [
+      "customTarball"
+    ]
+  },
+  "popularityRank": 95,
+  "estimatedSetupMinutes": 4,
+  "exampleImplementation": "Trigger: cron polling for open GitHub issues with a configured label such as openhands\nRequired secret: GITHUB_PERSONAL_ACCESS_TOKEN, with permission to write contents, issues, and pull requests\n\n1. Read the repositories, trigger label, branch prefix, draft mode, and polling schedule from setup.\n2. Poll each repository independently, with its own state, so issue numbers never collide.\n3. List open labelled issues, drop pull requests, and find the latest matching GitHub labeled issue event for each.\n4. Deduplicate on the label event ID so every label application queues exactly one attempt.\n5. Clone the default branch into a directory of its own, create the working branch, and start an OpenHands conversation with that directory as its workspace. The clone carries no credential and the agent is handed no secrets, because the prompt is built from an issue body that anyone can write.\n6. Comment on the issue with the branch and the conversation link.\n7. Once the conversation has stopped, commit whatever the agent left, push the branch, open a draft pull request titled after the issue, and comment the link on the issue. An agent that made no changes gets its answer posted instead.\n8. Remove the clone once the conversation has stopped, so nothing accumulates between runs.",
+  "setup": {
+    "version": "1.0",
+    "mode": "direct",
+    "form": {
+      "triggers": {
+        "cron": {
+          "schedule": {
+            "type": "cron",
+            "label": "Check frequency",
+            "help": "How often to look for newly labelled issues.",
+            "default": "*/15 * * * *",
+            "required": true
+          },
+          "timezone": {
+            "type": "timezone",
+            "label": "Timezone",
+            "help": "Timezone the schedule is interpreted in.",
+            "default": "UTC",
+            "required": true
+          }
+        }
+      },
+      "args": {
+        "repositories": {
+          "type": "repo-picker",
+          "label": "Repositories",
+          "help": "The repositories whose labelled issues are implemented. Each is polled independently and keeps its own state, so issue numbers never collide between them.",
+          "provider": "github",
+          "multiple": true,
+          "required": true
+        },
+        "triggerLabel": {
+          "type": "text",
+          "label": "Trigger label",
+          "help": "Only issues carrying this label are worked on.",
+          "default": "openhands",
+          "required": true,
+          "constraints": {
+            "minLength": 1,
+            "maxLength": 50
+          }
+        },
+        "branchPrefix": {
+          "type": "text",
+          "label": "Branch prefix",
+          "help": "Branches are named after this prefix and the issue number, such as openhands/issue-42.",
+          "default": "openhands/issue",
+          "required": true,
+          "constraints": {
+            "minLength": 1,
+            "maxLength": 50
+          }
+        },
+        "pullRequestMode": {
+          "type": "select",
+          "label": "Pull request mode",
+          "help": "Whether the pull request is opened as a draft or ready for review.",
+          "default": "draft",
+          "required": true,
+          "options": [
+            {
+              "value": "draft",
+              "label": "Draft"
+            },
+            {
+              "value": "ready",
+              "label": "Ready for review"
+            }
+          ]
+        }
+      }
+    },
+    "bundle": {
+      "version": "1.0.0",
+      "entrypoint": "python3 main.py",
+      "timeout": 900,
+      "files": {
+        "main.py": "skills/github-issue-to-pr/scripts/main.py"
+      },
+      "config": {
+        "repos": "{{form.repositories}}",
+        "trigger_label": "{{form.triggerLabel}}",
+        "branch_prefix": "{{form.branchPrefix}}",
+        "pull_request_mode": "{{form.pullRequestMode}}"
+      }
+    },
+    "message": "This deployment cannot run the scheduled issue-to-PR automation directly. Set it up in this conversation instead: confirm the repositories to watch, the trigger label, the branch prefix, whether pull requests open as drafts, and the polling schedule, then create the automation."
+  }
+}

package/automations/catalog/github-pr-reviewer/manifest.json

@@ -1,5 +1,6 @@
 {
   "id": "github-pr-reviewer",
+  "version": "1.0.0",
   "name": "GitHub Code Review Agent",
   "category": "Code review",
   "description": "Watch for a configurable label on GitHub pull requests, inspect full PR and repository context, and post an AI review comment once per label event.",

package/automations/catalog/github-repo-monitor/manifest.json

@@ -1,5 +1,6 @@
 {
   "id": "github-repo-monitor",
+  "version": "1.0.0",
   "name": "GitHub repository monitor",
   "category": "Developer tools",
   "description": "Watch a repository for @OpenHands mentions in issues and PR comments, start a conversation, and post the agent's reply back to GitHub.",

package/automations/catalog/news-digest/manifest.json

@@ -0,0 +1,76 @@
+{
+  "id": "news-digest",
+  "name": "Daily news digest",
+  "category": "Research",
+  "icon": "activity",
+  "description": "Read a list of public RSS and Atom feeds on a schedule, hand an agent everything new, and have it pick out what matters for your topics and write a short digest. Connects to nothing and needs no credentials.",
+  "requires": {
+    "integrations": {},
+    "features": [
+      "customTarball"
+    ]
+  },
+  "popularityRank": 78,
+  "estimatedSetupMinutes": 2,
+  "exampleImplementation": "Trigger: cron, daily by default (0 8 * * *)\nRequired secret: none. The feeds are public URLs and the conversation is started with an empty secret allow-list and no MCP servers.\n\n1. Read the feed list, the topics, and the schedule from setup.\n2. Key one unit of work to the UTC date, so a cron that fires more often, a retried run, or a restarted service cannot write the same digest twice.\n3. Fetch every feed over plain HTTPS and parse RSS 2.0, RSS 1.0/RDF and Atom by local element name. A feed that is down, moved, or no longer a feed is reported and skipped; the run fails only when every feed fails.\n4. Drop stories already covered by an earlier digest and stories older than the lookback window. Do not judge what a story is about: that has no right answer and is the agent's call.\n5. Start no conversation at all when nothing new was published, and leave the day open for a later run. A quiet day costs no tokens.\n6. Otherwise start an OpenHands conversation with the newest stories and the topics in the prompt, and let it decide which are relevant, group them, merge duplicate coverage, and write the digest.\n7. Deliver it three ways that need no credentials: it stays in the conversation, it is printed into the run log, and its opening is kept in state.\n8. Remember the reported stories only once a digest exists, so a failed run is recovered by the next one rather than lost.",
+  "setup": {
+    "version": "1.0",
+    "mode": "direct",
+    "form": {
+      "triggers": {
+        "cron": {
+          "schedule": {
+            "type": "cron",
+            "label": "Digest time",
+            "help": "When the digest is written. Work is keyed by UTC date, so a schedule more frequent than daily only polls until there is something new.",
+            "default": "0 8 * * *",
+            "required": true
+          },
+          "timezone": {
+            "type": "timezone",
+            "label": "Timezone",
+            "help": "Timezone the schedule is interpreted in.",
+            "default": "UTC",
+            "required": true
+          }
+        }
+      },
+      "args": {
+        "feeds": {
+          "type": "textarea",
+          "label": "Feeds",
+          "help": "One RSS or Atom feed URL per line. They must be public: this automation signs in to nothing, so a feed behind a login will simply fail and be skipped.",
+          "default": "https://news.ycombinator.com/rss\nhttps://feeds.arstechnica.com/arstechnica/index\nhttps://www.theverge.com/rss/index.xml",
+          "required": true,
+          "constraints": {
+            "minLength": 8,
+            "maxLength": 4000
+          }
+        },
+        "topics": {
+          "type": "textarea",
+          "label": "Topics of interest",
+          "help": "One topic per line, or separated by commas. The agent reads every new story and decides which ones are about these, so write them the way you would explain your interests to a colleague rather than as search terms. Leave this empty to cover whatever is most significant.",
+          "default": "artificial intelligence, open source, developer tools",
+          "required": false,
+          "constraints": {
+            "maxLength": 2000
+          }
+        }
+      }
+    },
+    "bundle": {
+      "version": "1.0.0",
+      "entrypoint": "python3 main.py",
+      "timeout": 900,
+      "files": {
+        "main.py": "skills/news-digest/scripts/main.py"
+      },
+      "config": {
+        "feeds": "{{form.feeds}}",
+        "topics": "{{form.topics}}"
+      }
+    },
+    "message": "This deployment cannot run the scheduled news digest directly. Set it up in this conversation instead: confirm the feeds to read, the topics to watch for, and the schedule, then create the automation."
+  }
+}

package/automations/catalog-index.js

@@ -4,13 +4,16 @@
 
 import entry0 from "./catalog/github-pr-reviewer/manifest.json" with { type: "json" };
 import entry1 from "./catalog/github-repo-monitor/manifest.json" with { type: "json" };
-import entry2 from "./catalog/slack-standup-digest/manifest.json" with { type: "json" };
-import entry3 from "./catalog/slack-channel-monitor/manifest.json" with { type: "json" };
-import entry4 from "./catalog/linear-triage-assistant/manifest.json" with { type: "json" };
-import entry5 from "./catalog/jira-issue-to-pr/manifest.json" with { type: "json" };
-import entry6 from "./catalog/research-brief-writer/manifest.json" with { type: "json" };
-import entry7 from "./catalog/upstream-fork-sync/manifest.json" with { type: "json" };
-import entry8 from "./catalog/incident-retrospective-drafter/manifest.json" with { type: "json" };
+import entry2 from "./catalog/github-issue-to-pr/manifest.json" with { type: "json" };
+import entry3 from "./catalog/slack-standup-digest/manifest.json" with { type: "json" };
+import entry4 from "./catalog/slack-channel-monitor/manifest.json" with { type: "json" };
+import entry5 from "./catalog/linear-triage-assistant/manifest.json" with { type: "json" };
+import entry6 from "./catalog/jira-issue-to-pr/manifest.json" with { type: "json" };
+import entry7 from "./catalog/research-brief-writer/manifest.json" with { type: "json" };
+import entry8 from "./catalog/github-agents-md-maintainer/manifest.json" with { type: "json" };
+import entry9 from "./catalog/upstream-fork-sync/manifest.json" with { type: "json" };
+import entry10 from "./catalog/incident-retrospective-drafter/manifest.json" with { type: "json" };
+import entry11 from "./catalog/news-digest/manifest.json" with { type: "json" };
 
 export const AUTOMATION_CATALOG_ENTRIES = [
   entry0,
@@ -22,4 +25,7 @@ export const AUTOMATION_CATALOG_ENTRIES = [
   entry6,
   entry7,
   entry8,
+  entry9,
+  entry10,
+  entry11,
 ];

package/automations/catalog.schema.json

@@ -21,8 +21,17 @@
       "pattern": "^[a-z0-9]+(-[a-z0-9]+)*$",
       "description": "Stable identifier. Must equal the name of the directory holding this manifest."
     },
+    "version": {
+      "type": "string",
+      "pattern": "^\\d+\\.\\d+\\.\\d+$",
+      "description": "Semantic version of this template. Present only on entries whose direct setup sends provenance to the automation service; bump it when the prompt, form, or filter changes meaningfully."
+    },
     "name": { "type": "string", "minLength": 1 },
     "category": { "type": "string", "minLength": 1 },
+    "icon": {
+      "description": "The glyph the card shows, named from the same closed set the interface manifest's navigation uses. Absent means the host derives one from requires.integrations, which is right for an automation whose identity is the service it talks to and wrong for one whose identity is the work itself.",
+      "enum": ["layout-dashboard", "sparkles", "bot", "circle-alert", "activity", "timer"]
+    },
     "description": { "type": "string", "minLength": 1 },
     "requires": { "$ref": "#/$defs/requires" },
     "popularityRank": { "type": "integer", "minimum": 0 },
@@ -233,9 +242,8 @@
       "required": ["integrations"],
       "properties": {
         "integrations": {
-          "description": "Keyed by integration id, each of which must resolve to an integrations/catalog entry.",
+          "description": "Keyed by integration id, each of which must resolve to an integrations/catalog entry. Empty when the automation connects to nothing and needs no credential - a requirement worth stating, and the reason the key stays required rather than becoming optional.",
           "type": "object",
-          "minProperties": 1,
           "propertyNames": { "type": "string", "minLength": 1 },
           "additionalProperties": {
             "type": "object",

package/automations/index.d.ts

@@ -1,7 +1,24 @@
 export interface RecommendedAutomation {
   id: string;
+  /**
+   * Semantic version of this template. Present only on entries whose direct
+   * setup sends provenance to the automation service; bumped when the prompt,
+   * form, or filter changes meaningfully.
+   */
+  version?: string;
   name: string;
   category: string;
+  /**
+   * The glyph the card shows, from the closed set the interface manifest's
+   * navigation uses. Absent means the host derives one from the integrations.
+   */
+  icon?:
+    | "layout-dashboard"
+    | "sparkles"
+    | "bot"
+    | "circle-alert"
+    | "activity"
+    | "timer";
   description: string;
   requires: AutomationPrerequisites;
   popularityRank: number;
@@ -83,7 +100,7 @@ export interface AutomationIntegrationRequirement {
 }
 
 export interface AutomationPrerequisites {
-  /** Keyed by integration catalog id. */
+  /** Keyed by integration catalog id. Empty when the automation needs nothing connected. */
   integrations: Record<string, AutomationIntegrationRequirement>;
   /** Deployment capabilities this automation cannot run without. */
   features?: string[];

package/automations/interface.json

@@ -150,7 +150,9 @@
   },
   "featuredAutomationIds": [
     "github-pr-reviewer",
-    "github-repo-monitor",
+    "github-agents-md-maintainer",
+    "news-digest",
+    "github-issue-to-pr",
     "slack-channel-monitor"
   ],
   "responderIntegrationIds": ["github", "slack"]

package/marketplaces/openhands-extensions.json

@@ -681,6 +681,32 @@
         "official"
       ]
     },
+    {
+      "name": "github-agents-md-maintainer",
+      "source": "./skills/github-agents-md-maintainer",
+      "description": "Create an automation that keeps AGENTS.md current in one or more GitHub repositories. On a schedule an agent reads the repository, creates or updates AGENTS.md, and opens a pull request - staying quiet while one of its own pull requests is still open.",
+      "category": "automations",
+      "keywords": [
+        "github",
+        "agents-md",
+        "documentation",
+        "maintenance",
+        "automation"
+      ]
+    },
+    {
+      "name": "github-issue-to-pr",
+      "source": "./skills/github-issue-to-pr",
+      "description": "Create an automation that implements GitHub issues when a configurable trigger label is applied. Clones the default branch for the agent, then commits, pushes, and opens the pull request itself - the agent is handed no GitHub credential.",
+      "category": "automations",
+      "keywords": [
+        "github",
+        "issue",
+        "pull-request",
+        "automation",
+        "integration"
+      ]
+    },
     {
       "name": "github-pr-reviewer",
       "source": "./skills/github-pr-reviewer",
@@ -781,6 +807,18 @@
         "jira",
         "atlassian"
       ]
+    },
+    {
+      "name": "news-digest",
+      "source": "./skills/news-digest",
+      "description": "Create an automation that reads public RSS and Atom feeds on a schedule, keeps what is new and matches the configured topics, and has an agent write a short digest of it. Needs no credentials.",
+      "category": "automations",
+      "keywords": [
+        "news",
+        "rss",
+        "atom",
+        "digest"
+      ]
     }
   ]
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openhands/extensions",
-  "version": "0.17.0",
+  "version": "0.18.0",
   "description": "Public OpenHands extension catalogs for skills, plugins, integrations, and automation templates.",
   "license": "MIT",
   "type": "module",

package/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "openhands-extensions"
-version = "0.17.0"
+version = "0.18.0"
 description = "OpenHands extensions, plugins, and skills (Python bindings for the integration catalog)"
 requires-python = ">=3.12"
 dependencies = [

package/python/openhands_extensions/_version.py

@@ -18,7 +18,7 @@ from importlib.metadata import PackageNotFoundError, version
 #: Kept in lock-step with pyproject.toml/package.json by the version test.
 #: release-please only rewrites a semver found on the annotated line itself, so
 #: the annotation must stay on the assignment; on its own line it is a no-op.
-_FALLBACK_VERSION = "0.17.0"  # x-release-please-version
+_FALLBACK_VERSION = "0.18.0"  # x-release-please-version
 
 try:
     __version__: str = version("openhands-extensions")

package/skills/github-agents-md-maintainer/.plugin/plugin.json

@@ -0,0 +1,19 @@
+{
+  "name": "github-agents-md-maintainer",
+  "version": "1.0.0",
+  "description": "Create an automation that keeps AGENTS.md current in one or more GitHub repositories. On a schedule it clones the default branch, has an agent read the repository and create or update AGENTS.md, and opens a pull request - staying quiet while one of its own pull requests is still open.",
+  "author": {
+    "name": "OpenHands",
+    "email": "contact@all-hands.dev"
+  },
+  "homepage": "https://github.com/OpenHands/extensions",
+  "repository": "https://github.com/OpenHands/extensions",
+  "license": "MIT",
+  "keywords": [
+    "github",
+    "agents-md",
+    "documentation",
+    "maintenance",
+    "automation"
+  ]
+}

package/skills/github-agents-md-maintainer/README.md

@@ -0,0 +1,59 @@
+# AGENTS.md Maintainer
+
+Create an automation that keeps `AGENTS.md` current in one or more GitHub
+repositories, on a schedule.
+
+## Trigger
+
+This skill is activated by:
+
+- `/agents-md:setup`
+
+## Features
+
+- Creates `AGENTS.md` when it is missing, updates it when the repository has
+  moved on, and leaves it alone when it is accurate
+- Runs weekly by default, keyed by ISO week, so extra runs inside a week are
+  harmless
+- Stays quiet while one of its own pull requests is still open, instead of
+  stacking a pull request per week over the same file
+- Maintains several repositories from one automation, each with its own state
+- Clones the default branch for the agent and removes the clone when the run ends
+- Lets the agent open the pull request, and opens it in Python when the agent
+  did not - a failed push or a dead conversation never loses the work
+- Opens draft pull requests by default, titled `docs: update AGENTS.md` or
+  `docs: add AGENTS.md`
+
+## What the agent is asked to do
+
+Read the repository - layout, the build, test, lint and format commands as they
+are actually defined, language and framework versions, contributing docs - and
+edit `AGENTS.md` to match. It is told to treat an existing file as someone
+else's writing: correct what is wrong, add what is missing, remove what no
+longer exists, and leave the rest alone. Only knowledge that helps in most
+future tasks belongs there, which is the rule the `agent-memory` skill sets out;
+task-specific notes and unverified commands do not.
+
+## Prerequisites
+
+Set `GITHUB_PERSONAL_ACCESS_TOKEN` in OpenHands Settings -> Secrets, able to
+read the repositories, **write contents** (to push the branch) and **write pull
+requests**. No issue permission is needed - this automation never comments on an
+issue.
+
+The automation runtime must have `git` available.
+
+## Quick Start
+
+Ask OpenHands:
+
+> "Set up an AGENTS.md maintenance automation for `myorg/backend` and
+> `myorg/frontend`, weekly."
+
+## See Also
+
+- [SKILL.md](SKILL.md) - Full setup workflow reference
+- [references/state-schema.md](references/state-schema.md) - State document and
+  task lifecycle
+- [../agent-memory/SKILL.md](../agent-memory/SKILL.md) - What belongs in an
+  AGENTS.md, and what does not