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.

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:

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.

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

Run these commands from this skill's directory, write the customized script to a temporary build directory, and validate it:

mkdir -p /tmp/agents-md-build
cp -L scripts/github_client.py /tmp/agents-md-build/github_client.py
# 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

Set OPENHANDS_HOST and AUTH_HEADER for the commands below:

• OpenHands Cloud or Enterprise - a <HOST> value is in your system prompt: use it as OPENHANDS_HOST, with AUTH_HEADER="Authorization: Bearer $OPENHANDS_API_KEY"
• Local Agent Canvas - an Automation backend is listed in the <RUNTIME_SERVICES> block of your system context: use its url_from_agent as OPENHANDS_HOST, with AUTH_HEADER="X-Session-API-Key: $OPENHANDS_AUTOMATION_API_KEY"

On OpenHands Cloud or Enterprise each run starts in a fresh sandbox, so the automation keeps its state in the KV store: check that kvStore is listed under features in GET ${OPENHANDS_HOST}/api/automation/v1/capabilities before deploying.

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 "$AUTH_HEADER" \
  -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"