[AgentOps] Added an AGENTS.md for coding agents working in .github/workflows/ dir

[lisa-tarbo]

Background

When reviewing github workflows for security issues, I continually needed to ground Claude Code with the Claude Code CLI and the claude-code-action security readme docs.

Aims

1. Create a new AGENTS.md file for AI coding agents working in .github/workflows/.
2. Document security best practices for workflows (GITHUB_TOKEN permissions, GitHub App short-lived installation access token, etc)
3. Document important references to anthropics/claude-code-action and claude_args flags to ground Claude when adding, updating and reviewing these complex workflows in future.

Details of what done

• AGENTS.md owns the security mechanics (permissions, tokens, --allowedTools); the README owns command/agent frontmatter, the workflow index, fork behavior, and troubleshooting, and only references AGENTS.md rather than restating it.
• Separation of concerns helped with simplification.
• Limited to verifiable facts to remove factually wrong and misleading claims

Reviewer notes

1. At first I did not want to include README changes in this PR, but they are linked, so now include both README-claude-workflows.md and AGENTS.md in this PR
2. The existing workflows have NOT yet been reviewed using the AGENTS.md file, so no workflows will be fixed/improved in this PR.

[coderabbitai]

Important

• 🔍 Trigger review

This repository does not receive automatic reviews because it has fewer than 10 stars.

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Team

Run ID: 7a1e6eec-8be1-4fc0-b7b5-34831b1bcb60

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: 34d82df0-ffc6-454d-b046-96c6c8f45a84

📥 Commits

Reviewing files that changed from the base of the PR and between ad678a0 and 356950c.

📒 Files selected for processing (2)

• .github/workflows/AGENTS.md
• .github/workflows/CLAUDE.md

Included review availability: Your plan provides up to 1 included review per hour; 0 remain after this review.

---

Walkthrough

Adds .github/workflows/AGENTS.md with Claude Code references, security rules for workflow permissions and tools, and a local actionlint testing command. Updates .github/workflows/CLAUDE.md to reference AGENTS.md.

Estimated code review effort: 1 (Trivial) | ~5 minutes

Merge Risk: ⚪ Minimal · up to 35695

This change adds guidance for coding agents working in GitHub workflows without changing workflow behavior, so no actionable merge-blocking risk remains after normal checks and review.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check. Docstring coverage is scoped to functions touched by this diff. Analyzed 0 functions across 0…
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Title check	✅ Passed	The title clearly identifies the main change: adding AGENTS.md guidance for coding agents in the .github/workflows directory.
Description check	✅ Passed	The description explains the purpose and scope of the AGENTS.md addition, including workflow security guidance and Claude Code references.

Full details: Docstring Coverage

Explanation

No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check. Docstring coverage is scoped to functions touched by this diff. Analyzed 0 functions across 0 files. (2 skipped: 2 unsupported.)

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch workflow-AGENTS-file

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[claude]

Review: .github/workflows/AGENTS.md

Good addition, and well-scoped — short enough that an agent will actually load and follow it, security-framed rather than descriptive, and it links out instead of restating the operator docs. The CLAUDE.md → @AGENTS.md one-liner correctly mirrors the root pattern, and .markdownlintignore's bare CLAUDE.md entry already covers the nested copy (gitignore semantics), so MD041 won't fire on it.

I left one inline comment that I'd treat as blocking: the --allowedTools section contradicts README-claude-workflows.md. Everything below is non-blocking.

Verified accurate

• permissions: {} as the starting point — all 7 workflows already do this.
• The ocs-agent installation-token bypass, and the token:/github_token:/GH_TOKEN: tracing rule — both match claude.yml, update-changelog.yml, and update-api-docs.yml.
• uv run prek run actionlint --all-files — prek is a dev dependency and the actionlint hook is configured.

Suggestions

1. persist-credentials: false reads as an existing convention, but no workflow sets it (0/7). Worth a parenthetical like "not yet applied to existing workflows — apply going forward", so an agent auditing a workflow doesn't assume it's already true, and doesn't mass-add it across all seven in an unrelated PR.

2. One README gotcha is worth pulling across: "A denied tool call doesn't fail the run — it's silently skipped and Claude continues without it." That's the corollary to "never infer a workflow is read-only from this list" and it's the most common cause of a truncated-looking result — exactly the failure mode this file's audience hits.

3. Action pinning isn't covered. The repo pins claude-code-action@v1.0.190 exactly but floats actions/checkout@v7, astral-sh/setup-uv@v7, peter-evans/create-pull-request@v8. Given the file already flags permission/tool changes as security-sensitive, a line on when to pin tightly — or just why claude-code-action gets exact pinning and the others don't — would round out the "Any workflow" section.

4. Duplication vs. link (for the follow-up PR). The "Any workflow" bullets are near-verbatim restatements of the README's "Gotchas & checklist". Reasonable as an interim step given you've deferred the README changes, but it's two sources of truth on the same mechanics — a future edit lands in one file only. When you do the follow-up, consider keeping the why-it-matters framing here and sourcing the mechanics from the README by link, the way the Reference docs section already does.

_{Note: I couldn't fetch the upstream claude-code-action docs during this review, so the two claims sourced from them ("this action disables Bash by default", and the --allowedTools semantics) are unverified on my side rather than disputed.}

[lisa-tarbo]

I will be working on the README updates in another branch.... I think I need to work on them in one branch. Pausing this for now.

Is there anything else that you think is missing from the AGENTS?