github-agents-md-maintainer

Files (9)

• .claude-plugin
• .codex-plugin
• plugin.json · .plugin/
• README.md
• SKILL.md
• agents-md-setup.md · commands/
• state-schema.md · references/
• github_client.py · scripts/
• main.py · scripts/

SKILL.md (first lines)

# 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:
```bash
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:
```bash
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

From OpenHands/extensions, MIT.

More from OpenHands/extensions