github-agents-md-maintainer

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.

---

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.