Agent-Friendly GitHub

A GitHub repository is the shared workspace where agents and humans collaborate on code. Agents can do real work there — filing issues, opening PRs, and landing commits — but only if the repo is configured to make the happy path obvious and the dangerous path hard. The central principle: anything safety-critical is enforced by configuration (rulesets, required checks, CODEOWNERS, Actions permissions), never left to agent goodwill. Agents err, and they can be prompt-injected; the repo must stay safe regardless.

Core Standard

Every rule below is stated in enforceable form in config-checklist.md, which is the authority; this section is the shape of the standard, not a second copy of it. Where a bullet reads as a principle rather than a check, treat it as the reason a checklist item exists — the checklist item is what an audit scores.

• Configuration is the enforced contract and conventions are advisory — safety-critical rules live in rulesets, required status checks, and CODEOWNERS, never in agent instructions that can be overridden or bypassed.
• The agent's identity never holds repository administration — every rule above depends on this one, because an identity that can edit or delete the ruleset is not bound by it; where the agent unavoidably holds admin, the boundary moves to the agent harness's permission configuration and the repo is in a documented degraded state.
• (Principle) Optimize for the agent's first correct contribution — discoverable conventions (AGENTS.md, CONTRIBUTING), issue and PR templates, a canonical label set, and a fast unambiguous green path are all part of the setup.
• Every agent action is attributable and auditable — agents use a distinct identity, commits are authored with attribution preserved (signing is strongly recommended but opt-in, not required), issues and PRs are cross-linked, and no silent force-push or history rewrite occurs on protected branches.
• All repo-resident text is untrusted input — issue bodies, PR descriptions, comments, and code file content can carry prompt-injection payloads into both the agent and CI; never grant write access or secrets to workflows triggered by untrusted actors, and never interpolate untrusted ${{ github.event.* }} expressions directly into a run: script — bind them through env: and reference the variable instead.
• The agent cannot launder its own approval — an agent that authored a PR must not approve it, trigger auto-merge to satisfy a human-review requirement, or manipulate review requests to make its own work look approved. After a post-approval push, the agent requests fresh human review rather than treating stale approval as sufficient.
• Merge authority defaults to the human — an agent does not merge a PR it authored unless the human has explicitly authorized the agent to merge it (a standing grant in AGENTS.md or an in-session instruction that specifically says the agent may merge); green required checks and a zero-review configuration are gate outcomes, not delegation.
• Constrain blast radius by default — a summary of controls that are each an atomic item in config-checklist.md: the least-privilege GITHUB_TOKEN, third-party actions pinned to a full commit SHA, OIDC over long-lived PATs, protected branches that no automation identity can bypass, environment gates for production deployments, and dismiss-stale-reviews-on-push.
• Right-size to the repo's team and risk — the security boundary is human-vs-agent, not author-vs-reviewer, so never configure a repo such that the legitimate human maintainer cannot merge their own work. Match controls to a repository profile (solo, small-team, org/high-risk) rather than applying every control everywhere; the profiles and their exceptions are defined in config-checklist.md.
• The agent never publishes to consumers — and because releases ride on the same contents: write the agent needs to push branches, this one cannot be enforced by withholding a permission: it takes a protected tag ruleset, a harness deny rule on the release and package endpoints, and publishing from a protected ref.
• (Principle) Fix flaky or slow required checks before they become a bypass habit — an unreliable green path creates pressure to retry, skip, or override, which is how agents learn to route around guardrails.
• Work identically across public/private and monorepo/traditional repos — scope ownership with explicit CODEOWNERS path prefixes, use an always-running monorepo gate check rather than paths:-filtering a required check, and do not disable secret scanning, Dependabot, or branch protection just because a repo is private.

Agent-Instruction-File Strategy

Single source of truth with thin adapters. Keep one canonical instructions file per repo — by emerging convention AGENTS.md — that holds all repo-wide norms: branching strategy, commit format, review expectations, label taxonomy, test commands, and off-limits paths. Per-tool files like CLAUDE.md or GEMINI.md are thin pointers or includes, not independent copies; each should reference the canonical file using whatever include or reference mechanism that tool supports. For Claude Code, the entire repo-wide content of CLAUDE.md is a single line: @AGENTS.md.

What goes where. Repo-wide conventions live exclusively in the canonical file. Tool-specific overrides — a tool's own invocation flags, permission scopes, or UI quirks — belong only in that tool's file, and only when they cannot be expressed generically. Reusable procedures (release workflows, audit checklists, operating playbooks) belong as committed artifacts rather than pasted into instruction files; instruction files cross-link to them instead.

Monorepo scoping. In a monorepo, nest an AGENTS.md in each package or subtree whose rules differ from the root file's — different build or test commands, ownership, review expectations, or off-limits paths; the root AGENTS.md covers cross-cutting norms. This mirrors CODEOWNERS path scoping: both files answer "who owns this path and what rules apply here?"

Drift control. Keep instruction files CODEOWNERS-owned so changes go through review, and limit their content to repo-wide norms plus cross-links — reusable procedures live as committed artifacts (see What goes where above). Cross-link rather than duplicate; duplicate content drifts and creates conflicting instructions. Treat the canonical file as a first-class repository artifact, not an afterthought.

When To Use

• Setting up a new repo for agent work, or hardening an existing one against the threat classes this skill covers.
• Auditing an existing repo's agent-friendliness and security posture against the config checklist.
• Guiding how an agent operates day-to-day in an already-configured repo — branching, committing, opening PRs, responding to review.

When Not To Use

• Org-level settings: SSO enforcement, team membership, OAuth app policy — those live outside repo configuration.
• CI pipeline design beyond the security surface — this skill hardens trigger permissions and injection points, not what the build actually does.
• Self-hosted runner hardening — runner OS configuration and network isolation are out of scope.
• At-scale repo provisioning or template instantiation — that is infrastructure-as-code territory.
• GitHub Projects, Milestones, and Wikis except where they directly affect PR or issue traceability.
• Layout of the repo's wider documentation surface — where README, docs/, ADRs, and per-directory context files sit, how an agent routes between them, and how they stay fresh — use agent-friendly-docs. This skill owns what an instruction file is and how harnesses read it; that skill owns where every other doc lives around it.
• GitHub Enterprise Server specifics — flagged untested; the concepts likely apply but the exact field names and API paths have not been validated against GHES.

Vocabulary

• Enforced vs advisory contract: enforced rules are implemented in rulesets, required checks, or CODEOWNERS and cannot be bypassed by agent action; advisory rules live in documentation and rely on good behavior.
• Protected branch: a branch with rules applied via classic branch protection (predates rulesets) or a repository ruleset (preferred).
• Ruleset: the current GitHub mechanism for branch and tag rules — supports bypass-actors lists, multiple target patterns, and org-level inheritance; prefer over classic branch protection.
• Required check: a status check (CI job, code-quality gate) that must pass before a PR can merge; declared as a required_status_checks rule in the ruleset.
• CODEOWNERS path ownership: a CODEOWNERS file entry that maps a glob path to one or more required reviewers; ownership is enforced when "Require review from code owners" is enabled in the ruleset.
• Agent identity: how the agent is identified as the actor — a GitHub App installation (fine-grained permissions, short-lived tokens, clear audit trail), a bot PAT (broader scope, longer-lived, less auditable), or a user account; config-checklist.md §4 ranks these, with user accounts last. For a local coding agent on a developer machine with a supported harness adapter, the agent-bot-identity skill implements the GitHub App option — registration, token minting, credential routing, and verification — and hands back to this skill as the repo-side authority.
• Least-privilege token: a GITHUB_TOKEN or PAT scoped to only the permissions the current job requires; declared per-job in permissions: in the workflow file.
• Untrusted input / injection surface: any repo-resident text the agent reads and acts on — issue titles, PR bodies, commit messages, code files, comments — that an adversary could craft to alter agent or CI behavior.
• Green path: the end-to-end flow where the agent opens a branch, pushes commits, opens a PR, required checks pass, a human approves, and the PR merges without manual intervention.
• Blast radius: the scope of damage if an agent is compromised or makes an error — limited by least-privilege tokens, pinned actions, protected branches, and environment gates.
• Control plane: the configuration that constrains the agent — rulesets, required checks, Actions settings, environments, secrets — as distinct from the code it works on. An agent that can change the control plane is not constrained by it (T10).
• Attribution / audit trail: the verifiable record of who authored each commit and triggered each action — preserved by a distinct agent identity, retained author and co-author metadata, linear history, and no squash-without-author-preservation; signed commits add tamper-evidence on top (their opt-in status is governed by config-checklist.md §2).
• Approval laundering: a pattern where the agent that authored a PR also satisfies the human-review requirement, either by self-approving or by manipulating the review state.
• Dependency confusion / namespace hijacking: a supply-chain attack where a public package with a higher version number shadows a private internal package; mitigated by explicit registry pinning and private package namespacing.
• Bypass-actors list: the set of identities (individual users, teams, roles, or apps) that may bypass ruleset conditions on a protected branch; its required contents — no automation identity the agent can act as, and the profile-scoped human escape hatch — are governed by config-checklist.md §2.
• Monorepo path scoping: restricting rules, ownership, and required checks to specific directory prefixes so unrelated packages do not block each other.
• Canonical instructions file: the single authoritative file (conventionally AGENTS.md) that all agents and per-tool adapter files defer to for repo-wide norms.

Workflow

First pick the repository profile (solo, small-team, or org/high-risk) defined at the top of config-checklist.md — it determines which controls apply and, critically, keeps a single-maintainer repo from locking its lone human out of merging. Then classify your task and follow the matching path:

• Set up a repo for agent work → follow setup-workflow.md.
• Audit an existing repo's posture → follow audit-workflow.md.
• Operate as an agent in a configured repo → follow operating-playbook.md.

Both Set up and Audit walk config-checklist.md as their normative standard; Operate follows operating-playbook.md and does not walk the checklist — where a playbook rule mirrors a configured control, the configuration is the authoritative, enforced version. The rationale behind every checklist rule — including which threat class it mitigates — lives in threat-model.md. Concrete artifacts (ruleset JSON, CODEOWNERS snippets, workflow permission blocks, label YAML) live in references/examples/. Sources for every dated GitHub claim — and the list of claims asserted but not verified — live in decisions/001-github-fact-sheet.md.

Done Criteria

• Set up: every item in config-checklist.md is either configured (with the specific GitHub field or setting noted) or explicitly marked N/A with a one-line justification; all emitted artifacts (ruleset JSON, CODEOWNERS file, workflow snippets) are listed.
• Audit: every checklist item is recorded as a finding with severity and a Tn threat reference, OK with brief evidence, or not-checked with reason; the full report follows the format defined in audit-workflow.md.
• Operate: the change followed every applicable rule in operating-playbook.md; the PR links its issue, all required checks pass, attribution is preserved in commit history, and no ruleset or review requirement was bypassed.