How to review AGENTS.md security before a coding agent runs it

A coding agent can read files, run commands, and reach external services. That makes a repository instruction file more than documentation: it can influence actions taken with the operator’s filesystem, network, and credentials. A hostile or compromised repository does not need an executable installer if an instruction file can persuade an agent to fetch one.

The first review should therefore happen before the agent opens the repository with normal permissions. Static inspection cannot prove that a repository is safe, but it can expose instruction-shaped risk while the reviewer still controls the trust boundary.

Do not stop at a root AGENTS.md. Current coding tools can discover instructions through several filenames and scoped directories. Review root and nested AGENTS.md and CLAUDE.md files, .github/copilot-instructions.md, Cursor rule files, GEMINI.md, and legacy or current Windsurf and Devin rule paths used by the repository.

Nested files matter because they can narrow or replace rules when an agent enters a subtree. Review symlinks and unusually generated instruction files too, and compare every discovered path with the files changed by the pull request.

The useful question is not whether a file contains security vocabulary. It is whether the instructions create a path from untrusted text to capabilities the agent can exercise. These eight signals are intentionally narrow review prompts, not automatic vulnerability verdicts.

• Invisible Unicode or bidirectional controls that can hide or reorder instructions.
• Download-and-execute chains such as curl or wget piped into a shell.
• Requests to print, upload, copy, or transmit secrets and credential files.
• Instructions to bypass approvals, safeguards, sandboxes, or permission prompts.
• Mutable remote instructions fetched at runtime without an immutable version.
• Destructive commands aimed at broad paths, history, or repository state.
• Broad access to SSH, cloud, package-manager, browser, or environment credentials.
• Encoded payloads decoded and executed without a reviewable intermediate artifact.

A pull-request check makes instruction changes visible before they reach the default branch. The workflow below checks out the proposed contents with a read-only token and runs the Repo Agent Kit scanner without a GitHub token, network requests, telemetry, dependency installation, or repository code execution.

The major-version tag is convenient for adoption. For the strongest third-party Action boundary, GitHub recommends replacing @v1 with the action’s full reviewed commit SHA and updating that pin deliberately.

name: Agent instruction security
on:
  pull_request:

permissions:
  contents: read

jobs:
  scan:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v6
      - uses: sunxiayi/repo-agent-instruction-security-scan@v1

A clean scan does not make untrusted repository content safe to execute. Keep the agent on least privilege: mount only the files it needs, prefer read-only access until a change is authorized, restrict outbound destinations, and place credentials outside the agent environment behind a narrowly scoped proxy or tool.

Approval prompts help only when they remain meaningful. If a workflow disables permission checks or auto-approves commands, a malicious instruction has fewer boundaries to cross. Use isolation, filesystem controls, network restrictions, credential separation, and audit logs as independent layers.

Pull-request protection starts after a repository already exists in your workflow. For a pre-trust local review, run the zero-dependency CLI from its reviewed v1.1.2 GitHub release before opening the clone with a coding agent. It scans only the supported instruction files and executes none of their contents.

The default text report is designed for a terminal. JSON and SARIF 2.1.0 outputs are available for evidence retention and code-scanning systems, and the same release includes a pre-commit hook for later changes.

npx --yes github:sunxiayi/repo-agent-instruction-security-scan#v1.1.2 .

Deterministic patterns miss novel phrasing, indirect social engineering, compromised dependencies, malicious source code, and instructions assembled at runtime. They can also flag legitimate administration or release guidance that needs human context.

Treat every finding as a place to inspect and every zero-finding result as only one completed layer. Review the exact diff, the repository owner and commit provenance, the permissions the agent will receive, and the commands that could run before granting trust.

The review model above combines vendor guidance about prompt injection and agent isolation, GitHub’s Action hardening guidance, current instruction-file discovery documentation, and the public scanner implementation used by Repo Agent Kit.

• Anthropic: Securely deploying AI agents
• GitHub: Secure use reference for Actions
• VS Code: Use custom instructions
• Repo Agent Kit scanner Action source