AGENTS: extract issue/PR guidelines into a dedicated skill and clean up structure#66739
AGENTS: extract issue/PR guidelines into a dedicated skill and clean up structure#66739joechenrh wants to merge 5 commits intopingcap:masterfrom
Conversation
Signed-off-by: Ruihao Chen <joechenrh@gmail.com>
ti-chi-bot
bot
added
do-not-merge/needs-linked-issue
do-not-merge/needs-triage-completed
release-note-none
|
Review Complete Findings: 0 issues ℹ️ Learn more details on Pantheon AI. |
ti-chi-bot
bot
added
the
size/XS
|
Hi @joechenrh. Thanks for your PR. PRs from untrusted users cannot be marked as trusted with I understand the commands that are listed here. DetailsInstructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the kubernetes-sigs/prow repository. |
|
Note Reviews pausedIt looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the Use the following commands to manage reviews:
Use the checkboxes below for quick actions:
No actionable comments were generated in the recent review. 🎉 ℹ️ Recent review info⚙️ Run configurationConfiguration used: Repository UI Review profile: CHILL Plan: Pro Run ID: 📒 Files selected for processing (1)
📝 WalkthroughWalkthroughUpdated documentation: Changes
Estimated code review effort🎯 2 (Simple) | ⏱️ ~10 minutes Poem
🚥 Pre-merge checks | ✅ 3✅ Passed checks (3 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 Generate unit tests (beta)
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. Comment |
ti-chi-bot
bot
removed
do-not-merge/needs-linked-issue
do-not-merge/needs-triage-completed
labels
The issue and PR writing guidance (labeling, description style, examples) is only relevant when an agent is creating or reviewing issues/PRs. Keeping it in AGENTS.md costs context tokens on every session regardless of task. Move the full guidance into `.agents/skills/github-workflow/SKILL.md` so it loads on demand, and keep only the mechanical must-not-break rules (title format, Issue Number line, HTML comments) in AGENTS.md with a pointer to the skill. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
ti-chi-bot
bot
added
size/M
joechenrh
changed the title
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
🧹 Nitpick comments (1)
AGENTS.md (1)
159-159: Make the skill handoff explicit.Now that the detailed issue/PR policy lives outside
AGENTS.md, Line 159 should instruct agents to consult the skill when they are creating or reviewing issues/PRs, not just point at it. That keeps the responsibility discoverable from the root instruction file.Suggested wording
-- For detailed guidance on writing issues, PRs, labeling, and descriptions, see `.agents/skills/github-workflow/SKILL.md`. +- When creating, reviewing, or editing issues/PRs, consult `.agents/skills/github-workflow/SKILL.md` for detailed guidance on writing issues, PRs, labeling, and descriptions.Based on learnings: Applies to
AGENTS.md: Document agent responsibilities, capabilities, and interactions in AGENTS.md🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@AGENTS.md` at line 159, Replace the generic pointer in AGENTS.md that reads "For detailed guidance on writing issues, PRs, labeling, and descriptions, see `.agents/skills/github-workflow/SKILL.md`" with an explicit instruction telling agents to consult the GitHub workflow skill when creating or reviewing issues/PRs (e.g., "When creating or reviewing issues or PRs, consult the GitHub workflow skill `.agents/skills/github-workflow/SKILL.md` for the detailed issue/PR policy and required steps"); update the sentence so it makes the handoff explicit and actionable, referencing the skill path `.agents/skills/github-workflow/SKILL.md` and the contexts "creating" and "reviewing" issues/PRs to ensure discoverability from AGENTS.md.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Nitpick comments:
In `@AGENTS.md`:
- Line 159: Replace the generic pointer in AGENTS.md that reads "For detailed
guidance on writing issues, PRs, labeling, and descriptions, see
`.agents/skills/github-workflow/SKILL.md`" with an explicit instruction telling
agents to consult the GitHub workflow skill when creating or reviewing
issues/PRs (e.g., "When creating or reviewing issues or PRs, consult the GitHub
workflow skill `.agents/skills/github-workflow/SKILL.md` for the detailed
issue/PR policy and required steps"); update the sentence so it makes the
handoff explicit and actionable, referencing the skill path
`.agents/skills/github-workflow/SKILL.md` and the contexts "creating" and
"reviewing" issues/PRs to ensure discoverability from AGENTS.md.
ℹ️ Review info
⚙️ Run configuration
Configuration used: Repository UI
Review profile: CHILL
Plan: Pro
Run ID: 06f3b698-c836-4082-be3f-4eb23e97bc8e
📒 Files selected for processing (2)
.agents/skills/github-workflow/SKILL.mdAGENTS.md
- Remove duplicate "Issues and PRs MUST be written in English" from "Docs and command snippets" (kept in "Issue and PR Rules"). - Promote "### Skills" to "## Skills" so it is a top-level section rather than incorrectly nested under Quick Decision Matrix. - Add "Creating issues or PRs" row to the decision matrix pointing to the github-workflow skill. - Fix leading space on "Before finishing" matrix row. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
joechenrh
changed the title
…n pattern The guidance previously said "do not enumerate every file or function touched", which could be read as "never include a list". Clarify that the problem is listing changes *instead of* explaining motivation. A summary paragraph followed by a scannable detail list is good practice. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
ti-chi-bot
bot
removed
do-not-merge/needs-linked-issue
do-not-merge/needs-triage-completed
labels
There was a problem hiding this comment.
Actionable comments posted: 1
🧹 Nitpick comments (1)
.agents/skills/github-workflow/SKILL.md (1)
33-36: Make the “good example” render as an actual summary plus bullet list.Right now the example explains the intended structure, but the inline
Specifically: - ... - ...format does not read like the scannable pattern you want contributors to copy.Proposed doc update
- Bad example (list without motivation): "Rename function A to B. Remove function C. Add parameter X to function D. Update callers E, F, G." -- this restates the diff without explaining why. -- Good example (summary + details): "Callers of A need both X and Y, but A only returns X, so every caller has to compute Y separately with duplicated logic. Combine both into A so callers get everything in one call. Specifically: - Merged computeX and computeY into A. - Updated callers in pkg/foo and pkg/bar to use the new signature." -- this explains the problem first, then lists notable changes for scannability. +- Good example (summary + details): + "Callers of A need both X and Y, but A only returns X, so every caller has to compute Y separately with duplicated logic. Combine both into A so callers get everything in one call." + - Merged `computeX` and `computeY` into `A`. + - Updated callers in `pkg/foo` and `pkg/bar` to use the new signature. + -- this explains the problem first, then lists notable changes for scannability.Based on learnings: Applies to **/*.md : Keep guidance executable and concrete; avoid ambiguous phrasing in documentation
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In @.agents/skills/github-workflow/SKILL.md around lines 33 - 36, Update the "Good example" block so it is an actual two-part structure: start with a 1-2 sentence summary sentence explaining the motivation (replace the inline "Specifically:" fragment with a standalone summary sentence), then insert a real markdown bullet list on the next line(s) with the notable specifics (each item prefixed with "-" on its own line) so the example reads as "summary" followed by a scannable list; edit the "Good example" paragraph that currently contains `Specifically: - Merged computeX... - Updated callers...` to separate the summary and the bullets accordingly.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In @.agents/skills/github-workflow/SKILL.md:
- Around line 8-29: Add a clear English-only requirement to both the "Issue
Rules" and "PR Requirements" sections: under "Issue Rules" (near the
`.github/ISSUE_TEMPLATE/` reference) add a line requiring that issue titles and
descriptions be written in English, and under "PR Requirements" (near
`.github/pull_request_template.md` and the title/description bullets) add a
matching sentence that PR titles and descriptions must be in English; ensure the
wording is explicit (e.g., "Titles and descriptions must be written in English")
so it applies to both issues and PRs.
---
Nitpick comments:
In @.agents/skills/github-workflow/SKILL.md:
- Around line 33-36: Update the "Good example" block so it is an actual two-part
structure: start with a 1-2 sentence summary sentence explaining the motivation
(replace the inline "Specifically:" fragment with a standalone summary
sentence), then insert a real markdown bullet list on the next line(s) with the
notable specifics (each item prefixed with "-" on its own line) so the example
reads as "summary" followed by a scannable list; edit the "Good example"
paragraph that currently contains `Specifically: - Merged computeX... - Updated
callers...` to separate the summary and the bullets accordingly.
ℹ️ Review info
⚙️ Run configuration
Configuration used: Repository UI
Review profile: CHILL
Plan: Pro
Run ID: e81af3a5-91bd-451a-8b67-0b3d23609e85
📒 Files selected for processing (1)
.agents/skills/github-workflow/SKILL.md
![pantheon-ai[bot]](https://avatars.githubusercontent.com/in/2265341?s=60&v=4){kind=small}
Address CodeRabbit review: the skill is the canonical detailed guide for issues/PRs but was missing the English-only requirement that exists in AGENTS.md. Add it to both Issue Rules and PR Requirements sections. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
|
[APPROVALNOTIFIER] This PR is APPROVED This pull-request has been approved by: winoros The full list of commands accepted by this bot can be found here. The pull request process is described here DetailsNeeds approval from an approver in each of these files:
Approvers can indicate their approval by writing |
ti-chi-bot
bot
added
approved
needs-1-more-lgtm
[LGTM Timeline notifier]Timeline:
|
|
But there's a question about whether we should put all the related docs into Before we create the |
|
Suppose we want to use |
From my point of view, maybe we can treat |
|
oh! I found a regression. |
2 participants
What problem does this PR solve?
Issue Number: ref #63847
Problem Summary:
AGENTS.mdis loaded into every agent conversation regardless of task. The issue/PR writing guidance (labeling rules, description style, good/bad examples) is only useful when an agent is actually creating or reviewing issues and PRs — a small fraction of sessions. Including it unconditionally wastes context tokens and makes AGENTS.md harder to scan for the structural rules that apply to every task.What changed and how does it work?
Detailed issue/PR guidance now lives in
.agents/skills/github-workflow/SKILL.mdso it loads on demand instead of every session. AGENTS.md retains only the hard mechanical rules (title format,Issue Number:line, HTML comments) with a pointer to the skill. Specifically:.agents/skills/github-workflow/SKILL.mdwith full issue rules, PR requirements, labeling guidance, and description writing examples.### Skillsto a top-level## Skillssection (was incorrectly nested under Quick Decision Matrix).Check List
Tests
Side effects
Documentation
Release note
Summary by CodeRabbit