/github-agents-md-maintainer

name: github-agents-md-maintainer
description: >
  Create an automation that keeps AGENTS.md current in one or more GitHub
  repositories. On a schedule - weekly by default - it clones the default
  branch, starts an OpenHands conversation that reads the repository and
  creates or updates AGENTS.md, and opens a pull request with the result.
triggers:
  - /agents-md:setup

AGENTS.md Maintainer Automation

Create a cron automation that keeps each configured repository's `AGENTS.md` - the file an agent reads first when it starts work there - matching what the repository actually is. It is created when missing, updated when the repository has moved on, and left alone when it is still accurate.

The automation script is deterministic: scheduling, the once-per-week claim, the clone, the branch, the commit, the push, the pull request, and the clone's removal are all handled in Python. The LLM is invoked only to read the repository and write the file.

A week is one unit of work per repository, so a cron that fires more often than intended, a retried run, or a restarted service cannot open the same pull request twice. **A repository whose previous pull request from this automation is still open is skipped**, because a second one would edit the same file and reviewing it would tell you nothing the first did not.

---

The script imports shared GitHub transport from `scripts/github_client.py`, installed with this skill. Include it beside `main.py` when packaging manually, as shown below.

Prerequisites

Required secret

Verify that the following secret is set in **OpenHands Settings -> Secrets**:

| Secret name | Token type | Minimum permissions | |---|---|---| | `GITHUB_PERSONAL_ACCESS_TOKEN` | Classic PAT | `repo` | | `GITHUB_PERSONAL_ACCESS_TOKEN` | Fine-grained PAT | Contents: **Read and write**, Metadata: Read, Pull requests: **Read and write** |

Contents write is required because the branch is pushed, and pull request write because the pull request is opened. No issue permission is needed: this automation never comments on an issue.

Check with:

curl -s https://api.github.com/user \
  -H "Authorization: Bearer $GITHUB_PERSONAL_ACCESS_TOKEN" \
  | python3 -c "import json,sys; d=json.load(sys.stdin); print(d.get('login') or d.get('message'))"

If the token is missing or invalid, inform the user and stop.

---

Setup Workflow

Follow these steps in order.

Step 1 - Verify `GITHUB_PERSONAL_ACCESS_TOKEN`

Run the `curl` check above.

• If absent: *"GITHUB_PERSONAL_ACCESS_TOKEN is not set. Please add it in

OpenHands Settings -> Secrets."* Stop.

• If the API returns `{"message": "Bad credentials"}`: tell the user the token is

invalid and ask them to update it. Stop.

Step 2 - Collect repositories

Ask: *"Which GitHub repositories should have their AGENTS.md maintained? (Format: `owner/repo`, e.g. `myorg/backend`. List several separated by commas.)"*

Validate access to **each** repository, and confirm the token can push:

curl -s "https://api.github.com/repos/{owner}/{repo}" \
  -H "Authorization: Bearer $GITHUB_PERSONAL_ACCESS_TOKEN" \
  | python3 -c "
import json, sys
d = json.load(sys.stdin)
if 'message' in d:
    print('ERROR:', d['message'])
else:
    print(f\"Accessible. Default branch: {d.get('default_branch')}. Push: {d.get('permissions',{}).get('push')}\")
"

Record every accepted repository into `REPOS = ["{owner}/{repo}", ...]`. Each repository keeps its own state and its own weekly claim, so one falling behind never blocks another.

Step 3 - Collect the schedule

Ask: *"How often should AGENTS.md be checked? (Press Enter for the default: every Monday at 09:00 UTC, `0 9 * * 1`.)"*

Default: `0 9 * * 1`. Record as `CRON_SCHEDULE`, and the timezone as `CRON_TIMEZONE` (default `UTC`).

A schedule more frequent than weekly is allowed but rarely useful: the work is keyed by ISO week, so extra runs inside the same week do nothing but poll.

Step 4 - Collect the pull request mode

Ask: *"Should the pull requests be opened as drafts? 1. Draft (default) - opened as a draft, ready for a human to mark ready 2. Ready for review - opened as a normal pull request (Press Enter for Draft)"*

Map the choice to `DRAFT_PULL_REQUEST` (`True` or `False`).

Step 5 - Collect the branch prefix

Ask: *"What branch prefix should the automation use? (Press Enter for the default: `openhands/agents-md`, which produces `openhands/agents-md-2026-W34`.)"*

Record as `BRANCH_PREFIX`. The prefix is also how the automation recognises its own open pull requests, so changing it later makes it stop seeing the older ones.

Step 6 - Confirm the secret scope

The agent is handed `GITHUB_PERSONAL_ACCESS_TOKEN`, because it pushes its branch and opens the pull request itself. Ask: *"Beyond the GitHub token, does reading this repository need a secret of its own? (Press Enter for none.)"*

Record the answers appended to the default, as `AGENT_SECRET_NAMES = ["GITHUB_PERSONAL_ACCESS_TOKEN", "NAME", ...]`. Keep it an allow-list: the conversation reads a whole repository, so the rest of the deployment's secrets should stay out of its reach.

Step 7 - Generate the automation script

Read `scripts/main.py` from this skill's directory. Apply exactly four constant substitutions near the top of the file:

> The script also reads a `config.json` shipped beside it, if there is one, over > these constants. That is how the catalog entry > (`automations/catalog/github-agents-md-maintainer/`) configures an unmodified > copy, since a declarative host cannot rewrite Python. This setup path > substitutes the constants and ships no `config.json`, so the two never collide.

| Placeholder | Replace with | |---|---| | `REPOS = ["owner/repo"]` | `REPOS = ["{owner_repo}", ...]` - one entry per repository from Step 2 | | `BRANCH_PREFIX = "openhands/agents-md"` | `BRANCH_PREFIX = "{branch_prefix}"` | | `DRAFT_PULL_REQUEST = True` | `DRAFT_PULL_REQUEST = {True or False}` | | `AG