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.

---

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}
AGENT_SECRET_NAMES: list[str] = ["GITHUB_PERSONAL_ACCESS_TOKEN"]	the list from Step 6

Use a safe string writer such as json.dumps(value) when inserting user-provided repository names or prefixes into Python string literals.

Write the customized script to a temporary build directory and validate it:

mkdir -p /tmp/agents-md-build
# write the customized main.py to /tmp/agents-md-build/main.py
python3 -m py_compile /tmp/agents-md-build/main.py && echo "Syntax OK"

Step 8 - Package and upload

Determine the Automation backend URL and auth from the <RUNTIME_SERVICES> block in your system context:

• OPENHANDS_HOST: the Automation backend url_from_agent
• Auth: X-Session-API-Key: $OPENHANDS_AUTOMATION_API_KEY

tar -czf /tmp/agents-md.tar.gz -C /tmp/agents-md-build .

TARBALL_PATH=$(curl -s -X POST \
  "${OPENHANDS_HOST}/api/automation/v1/uploads?name=github-agents-md-maintainer" \
  -H "X-Session-API-Key: $OPENHANDS_AUTOMATION_API_KEY" \
  -H "Content-Type: application/gzip" \
  --data-binary @/tmp/agents-md.tar.gz \
  | python3 -c "import json,sys; print(json.load(sys.stdin)['tarball_path'])")

echo "Uploaded: $TARBALL_PATH"

Step 9 - Register the automation

curl -s -X POST "${OPENHANDS_HOST}/api/automation/v1" \
  -H "X-Session-API-Key: $OPENHANDS_AUTOMATION_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{
    \"name\": \"AGENTS.md Maintainer: {repo_summary}\",
    \"trigger\": {\"type\": \"cron\", \"schedule\": \"{cron_schedule}\", \"timezone\": \"{cron_timezone}\"},
    \"tarball_path\": \"$TARBALL_PATH\",
    \"entrypoint\": \"python3 main.py\",
    \"timeout\": 900
  }" | python3 -m json.tool

Record the returned id.

Step 10 - Confirm

Tell the user:

✅ AGENTS.md Maintainer is running!

• Automation ID: {id}
• Repositories: {owner}/{repo}, ... (one line each)
• Schedule: {cron_schedule} ({cron_timezone})
• Branch prefix: {branch_prefix}
• Pull requests: {draft or ready for review}
• State file per repository: ~/.openhands/workspaces/automation-state/github_agents_md_{id}_{owner}__{repo}.json

Each week it reads the repository and proposes an AGENTS.md change, or reports that none is needed. While one of its pull requests is still open, it stays quiet - merge or close it to get the next one.

---

Runtime Behaviour (per run)

Each cron run executes main.py, which loads config.json if the catalog shipped one, checks that git is available, resolves and validates GITHUB_PERSONAL_ACCESS_TOKEN once, then processes every repository in REPOS independently. One repository failing does not stop the others; the run fails only if every repository fails.

For each repository:

1. Loads that repository's state and reads its default branch.
2. Computes the current ISO week, e.g. 2026-W34, and stops here if that week is already recorded - which is what makes extra runs inside a week harmless.
3. Lists open pull requests whose head branch starts with the branch prefix. If any exist, records the skip and moves on.
4. Asks GitHub whether AGENTS.md exists on the default branch, which decides whether the run is a create or an update, and the pull request's title.
5. Claims the week in state before the slow work, so an overlapping run cannot start it twice.
6. Picks the first free branch name ({prefix}-{period}, else a numbered variant), clones the default branch shallow and single-branch into {WORKSPACE_BASE}/agents-md/{owner}__{repo}/{period}, and creates the branch.
7. Starts an OpenHands conversation with that clone as its working directory, and only the secrets named in AGENT_SECRET_NAMES attached.
8. When the conversation reaches idle, finished, error, or stuck:
   • Adopts the pull request the agent opened, if GitHub says one exists.
   • Records the failure and opens nothing if the conversation errored.
   • Records no-changes and opens nothing if there are no commits - the expected outcome when AGENTS.md is already accurate.
   • Otherwise commits what was left, pushes, and opens the pull request itself.
   • Retries a failed push or pull request on the next two runs before giving up.
9. Removes the clone once the conversation is confirmed stopped.

---

Additional Resources

• references/state-schema.md - State JSON schema and the task lifecycle.
• scripts/main.py - The complete automation script.

---

Troubleshooting

Symptom	Likely cause	Fix
Nothing happens for a repository	A pull request from this automation is still open	Merge or close it; the next run proposes the following one
Nothing happens after a manual dispatch	The current ISO week is already recorded in state	Wait for the next week, or clear that week's entry from the state document
"The token cannot push to ..."	Token lacks Contents: write	Issue a token with write access, or drop the repository from REPOS
git is not available in the automation runtime	The runtime image has no git	Use a runtime image that ships git
Pull request says nothing changed	The agent judged AGENTS.md accurate but still committed	Read its summary in the pull request body; tighten the prompt if it keeps making cosmetic edits
Every run reports no-changes	AGENTS.md is accurate, or the agent cannot read the repository	Open the conversation from the run log and check what it saw
Clones remain under agents-md/	Their conversations had not stopped yet	They are removed by a later run once the conversation is terminal