تعزيز تعليمات الإعداد لوكيل الترميز#17
Conversation
Expanded agent onboarding instructions to improve efficiency and reduce errors for coding agents. Added detailed sections on goals, limitations, build instructions, project layout, and steps to follow.
✅ Deploy Preview for resilient-mermaid-3e3f4f ready!
To edit notification comments on pull requests, go to your Netlify project configuration. |
📝 WalkthroughWalkthroughAdded a new GitHub agent configuration file that instructs an AI agent to generate repository onboarding 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 |
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: bb4fd5658f
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
| # For format details, see: https://gh.io/customagents/config | ||
|
|
||
| name: | ||
| description: |
There was a problem hiding this comment.
The YAML frontmatter leaves description empty, which parses as null instead of a string; GitHub’s custom agent schema marks description as a required string, so this profile can fail validation and not be loadable as a custom agent. Add a non-empty description value so the agent is discoverable and usable.
Useful? React with 👍 / 👎.
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 3
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In @.github/agents/my-agent.agent.md:
- Line 14: Update the product name casing in the documentation by replacing the
incorrect instance on line 14 of .github/agents/my-agent.agent.md with the
official "GitHub" capitalization; search for the current string (e.g., "Github"
or "github") in that file and replace it with "GitHub" to ensure consistency and
professionalism across the agent onboarding text.
- Around line 85-86: A duplicated trailing bullet ("- Document any errors
encountered as well as the steps taken to work-around them.") exists after the
closing </StepsToFollow> tag; remove that trailing line so the instruction only
appears inside the StepsToFollow section and ensure the closing tag
</StepsToFollow> directly follows the final intended bullet; look for the
StepsToFollow block and delete the repeated bullet outside it.
- Around line 7-8: The agent metadata file has empty name and description
fields; set meaningful values for the name and description keys in
.github/agents/my-agent.agent.md (populate the name field with a concise
human-readable agent name and the description field with a one-sentence summary
of the agent's purpose) to improve discoverability and follow GitHub
conventions.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: ASSERTIVE
Plan: Pro
Run ID: 965ebdd9-858f-40f8-a3c9-3da942ff78a1
📒 Files selected for processing (1)
.github/agents/my-agent.agent.md
| name: | ||
| description: |
There was a problem hiding this comment.
🧹 Nitpick | 🔵 Trivial
🧩 Analysis chain
🌐 Web query:
For GitHub custom agents configuration files, are nameanddescription in frontmatter required to be non-empty values?
💡 Result:
No, name is not required to be non-empty (optional string, defaults to filename without extension if unset). description is required but official GitHub docs do not explicitly state it must be non-empty; however, it is consistently provided as a non-empty string in all examples, and creation instructions emphasize writing a "brief description explaining what your agent does". In VS Code custom agent validation tools, empty description triggers only a warning, not a failure. No sources confirm enforcement of non-empty values or report errors for empty strings.
Citations:
- 1: https://docs.github.com/en/copilot/reference/custom-agents-configuration
- 2: https://docs.github.com/en/copilot/how-tos/use-copilot-agents/coding-agent/create-custom-agents
- 3: https://docs.github.com/en/copilot/concepts/agents/coding-agent/about-custom-agents
- 4: https://code.visualstudio.com/docs/copilot/customization/custom-agents
Consider populating name and description for clarity and consistency.
Empty name and description fields are technically permitted by the schema (name defaults to the filename if unset, and description has no explicit non-empty validation). However, GitHub's examples and creation guidance consistently show these fields populated with meaningful values. Filling them improves agent discoverability and follows established conventions.
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In @.github/agents/my-agent.agent.md around lines 7 - 8, The agent metadata file
has empty name and description fields; set meaningful values for the name and
description keys in .github/agents/my-agent.agent.md (populate the name field
with a concise human-readable agent name and the description field with a
one-sentence summary of the agent's purpose) to improve discoverability and
follow GitHub conventions.
There was a problem hiding this comment.
Pull request overview
Adds a new GitHub Copilot custom agent definition intended to guide an “onboarding” flow for coding agents by describing what information to capture for .github/copilot-instructions.md.
Changes:
- Added
.github/agents/my-agent.agent.mdwith YAML front matter and a long-form prompt/template (Goals, Limitations, BuildInstructions, ProjectLayout, StepsToFollow). - Included guidance for collecting build/validation steps and project layout details to reduce future agent exploration.
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| name: | ||
| description: |
There was a problem hiding this comment.
description is required for custom agent configs, but it's currently empty/null in the YAML front matter. This will likely make the agent invalid/not load; set a non-empty description string (and optionally a name) before merging.
| name: | |
| description: | |
| name: My Agent | |
| description: "Onboards this repository to Copilot by guiding creation of .github/copilot-instructions.md" |
| Describe what your agent does here. | ||
| Your task is to "onboard" this repository to Copilot coding agent by adding a .github/copilot-instructions.md file in the repository that contains information describing how a coding agent seeing it for the first time can work most efficiently. | ||
|
|
||
| You will do this task only one time per repository and doing a good job can SIGNIFICANTLY improve the quality of the agent's work, so take your time, think carefully, and search thoroughly before writing the instructions. |
There was a problem hiding this comment.
The PR description says onboarding instructions were expanded, but this change only adds a custom agent template under .github/agents/ and does not add/update .github/copilot-instructions.md itself. If the intent is to provide repository onboarding instructions, those should live in .github/copilot-instructions.md (or the PR description should be adjusted to reflect that this is an agent definition).
| - Finally, fill in any remaining space with detailed lists of the following, in order of priority: the list of files in the repo root, the | ||
| contents of the README, the contents of any key source files, the list of files in the next level down of directories, giving priority to the more structurally important and snippets of code from key source files, such as the one containing the main method. |
There was a problem hiding this comment.
The <Limitations> section requires the generated instructions to be "no longer than 2 pages", but later guidance suggests including large inventories (root file lists, README contents, snippets from key source files). These requirements conflict and will push agents to violate the 2-page constraint; please tighten the guidance to fit within the stated limit (e.g., summarize and link/point to files instead of reproducing contents).
| - Finally, fill in any remaining space with detailed lists of the following, in order of priority: the list of files in the repo root, the | |
| contents of the README, the contents of any key source files, the list of files in the next level down of directories, giving priority to the more structurally important and snippets of code from key source files, such as the one containing the main method. | |
| - Finally, within the 2-page limit, add concise summaries of where to find important resources (for example: key entry-point files, main README and docs locations, primary configuration directories), and briefly describe what they contain instead of listing every file or copying large contents. When helpful, reference paths (like `src/main/...`, `docs/`, or specific config files) rather than reproducing their full contents. |
| - A description of the major architectural elements of the project, including the relative paths to the main project files, the location | ||
| of configuration files for linting, compilation, testing, and preferences. | ||
| - A description of the checks run prior to check in, including any GitHub workflows, continuous integration builds, or other validation pipelines. | ||
| - Document the steps so that the agent can replicate these itself. | ||
| - Any explicit validation steps that the agent can consider to have further confidence in its changes. | ||
| - Dependencies that aren't obvious from the layout or file structure. | ||
| - Finally, fill in any remaining space with detailed lists of the following, in order of priority: the list of files in the repo root, the | ||
| contents of the README, the contents of any key source files, the list of files in the next level down of directories, giving priority to the more structurally important and snippets of code from key source files, such as the one containing the main method. | ||
| </ProjectLayout> | ||
| </WhatToAdd> | ||
|
|
||
| <StepsToFollow> | ||
| - Perform a comprehensive inventory of the codebase. Search for and view: | ||
| - README.md, CONTRIBUTING.md, and all other documentation files. | ||
| - Search the codebase for build steps and indications of workarounds like 'HACK', 'TODO', etc. | ||
| - All scripts, particularly those pertaining to build and repo or environment setup. | ||
| - All build and actions pipelines. | ||
| - All project files. | ||
| - All configuration and linting files. | ||
| - For each file: | ||
| - think: are the contents or the existence of the file information that the coding agent will need to implement, build, test, validate, or demo a code change? | ||
| - If yes: | ||
| - Document the command or information in detail. | ||
| - Explicitly indicate which commands work and which do not and the order in which commands should be run. | ||
| - Document any errors encountered as well as the steps taken to workaround them. | ||
| - Document any other steps or information that the agent can use to reduce time spent exploring or trying and failing to run bash commands. | ||
| - Finally, explicitly instruct the agent to trust the instructions and only perform a search if the information in the instructions is incomplete or found to be in error. | ||
| </StepsToFollow> | ||
| - Document any errors encountered as well as the steps taken to work-around them. |
There was a problem hiding this comment.
Markdown list formatting is broken in a few places (e.g., this bullet wraps onto the next line without indentation), which makes the rendered instructions harder to read. Consider re-wrapping/indenting continuation lines so they stay part of the same list item.
| - A description of the major architectural elements of the project, including the relative paths to the main project files, the location | |
| of configuration files for linting, compilation, testing, and preferences. | |
| - A description of the checks run prior to check in, including any GitHub workflows, continuous integration builds, or other validation pipelines. | |
| - Document the steps so that the agent can replicate these itself. | |
| - Any explicit validation steps that the agent can consider to have further confidence in its changes. | |
| - Dependencies that aren't obvious from the layout or file structure. | |
| - Finally, fill in any remaining space with detailed lists of the following, in order of priority: the list of files in the repo root, the | |
| contents of the README, the contents of any key source files, the list of files in the next level down of directories, giving priority to the more structurally important and snippets of code from key source files, such as the one containing the main method. | |
| </ProjectLayout> | |
| </WhatToAdd> | |
| <StepsToFollow> | |
| - Perform a comprehensive inventory of the codebase. Search for and view: | |
| - README.md, CONTRIBUTING.md, and all other documentation files. | |
| - Search the codebase for build steps and indications of workarounds like 'HACK', 'TODO', etc. | |
| - All scripts, particularly those pertaining to build and repo or environment setup. | |
| - All build and actions pipelines. | |
| - All project files. | |
| - All configuration and linting files. | |
| - For each file: | |
| - think: are the contents or the existence of the file information that the coding agent will need to implement, build, test, validate, or demo a code change? | |
| - If yes: | |
| - Document the command or information in detail. | |
| - Explicitly indicate which commands work and which do not and the order in which commands should be run. | |
| - Document any errors encountered as well as the steps taken to workaround them. | |
| - Document any other steps or information that the agent can use to reduce time spent exploring or trying and failing to run bash commands. | |
| - Finally, explicitly instruct the agent to trust the instructions and only perform a search if the information in the instructions is incomplete or found to be in error. | |
| </StepsToFollow> | |
| - Document any errors encountered as well as the steps taken to work-around them. | |
| - A description of the major architectural elements of the project, including the relative paths to the main project files, the location of configuration files for linting, compilation, testing, and preferences. | |
| - A description of the checks run prior to check in, including any GitHub workflows, continuous integration builds, or other validation pipelines. | |
| - Document the steps so that the agent can replicate these itself. | |
| - Any explicit validation steps that the agent can consider to have further confidence in its changes. | |
| - Dependencies that aren't obvious from the layout or file structure. | |
| - Finally, fill in any remaining space with detailed lists of the following, in order of priority: the list of files in the repo root, the contents of the README, the contents of any key source files, the list of files in the next level down of directories, giving priority to the more structurally important and snippets of code from key source files, such as the one containing the main method. | |
| </ProjectLayout> | |
| </WhatToAdd> | |
| <StepsToFollow> | |
| - Perform a comprehensive inventory of the codebase. Search for and view: | |
| - README.md, CONTRIBUTING.md, and all other documentation files. | |
| - Search the codebase for build steps and indications of workarounds like 'HACK', 'TODO', etc. | |
| - All scripts, particularly those pertaining to build and repo or environment setup. | |
| - All build and actions pipelines. | |
| - All project files. | |
| - All configuration and linting files. | |
| - For each file: | |
| - Think: are the contents or the existence of the file information that the coding agent will need to implement, build, test, validate, or demo a code change? | |
| - If yes: | |
| - Document the command or information in detail. | |
| - Explicitly indicate which commands work and which do not and the order in which commands should be run. | |
| - Document any errors encountered as well as the steps taken to workaround them. | |
| - Document any other steps or information that the agent can use to reduce time spent exploring or trying and failing to run bash commands. | |
| - Finally, explicitly instruct the agent to trust the instructions and only perform a search if the information in the instructions is incomplete or found to be in error. | |
| </StepsToFollow> |
Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com>
|
@copilot apply changes based on the comments in this thread |
…dance, fix list formatting Agent-Logs-Url: https://github.com/Abdullah9990/Aa12/sessions/be9c7828-d839-4daa-bc24-6ebeea615f0e Co-authored-by: Abdullah9990 <56370218+Abdullah9990@users.noreply.github.com>
Applied all the review feedback in commit
|
|
There was a problem hiding this comment.
Actionable comments posted: 3
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In @.github/agents/my-agent.agent.md:
- Line 33: The document .github/agents/my-agent.agent.md contains unhyphenated
compound adjectives and a wordy phrase; update the phrases "high level details"
to "high-level details", "High level repository" to "High-level repository", and
"prior to check in" to "before check-in" (or "prior to check-in") wherever they
appear (e.g., around the strings visible at line 33, 37, and 60) to improve
grammar and consistency in the agent documentation.
- Line 13: Replace the template placeholder string "Describe what your agent
does here." in .github/agents/my-agent.agent.md with a concise, meaningful
description of the onboarding agent (e.g., "This agent generates comprehensive
repository onboarding documentation for Copilot coding agents.") so the file
documents the agent's purpose; locate the placeholder text and update it to a
clear one-line summary that describes the agent's behavior and intended output.
- Line 14: The long 88-word run-on sentence in .github/agents/my-agent.agent.md
(the paragraph at line 14) should be split into two or three shorter sentences
for readability; edit that paragraph to separate independent clauses into clear
sentences, keeping the same meaning and any key instructions for onboarding, and
ensure punctuation and capitalization are corrected so the resulting text is
concise and easier for a coding agent to parse.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: ASSERTIVE
Plan: Pro
Run ID: 66f4981d-b622-4714-8148-dc48d45702ad
📒 Files selected for processing (1)
.github/agents/my-agent.agent.md
|
|
||
| # My Agent | ||
|
|
||
| Describe what your agent does here. |
There was a problem hiding this comment.
Replace placeholder text with actual agent description.
Line 13 still contains the template placeholder "Describe what your agent does here." This should be replaced with a meaningful description of what this onboarding agent does, such as "This agent generates comprehensive repository onboarding documentation for Copilot coding agents."
📝 Suggested description
-Describe what your agent does here.
+This agent performs a one-time analysis of the repository to generate comprehensive onboarding documentation (`.github/copilot-instructions.md`) that enables coding agents to work efficiently with minimal exploration and command failures.📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| Describe what your agent does here. | |
| This agent performs a one-time analysis of the repository to generate comprehensive onboarding documentation (`.github/copilot-instructions.md`) that enables coding agents to work efficiently with minimal exploration and command failures. |
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In @.github/agents/my-agent.agent.md at line 13, Replace the template
placeholder string "Describe what your agent does here." in
.github/agents/my-agent.agent.md with a concise, meaningful description of the
onboarding agent (e.g., "This agent generates comprehensive repository
onboarding documentation for Copilot coding agents.") so the file documents the
agent's purpose; locate the placeholder text and update it to a clear one-line
summary that describes the agent's behavior and intended output.
| # My Agent | ||
|
|
||
| Describe what your agent does here. | ||
| Your task is to "onboard" this repository to Copilot coding agent by adding a .github/copilot-instructions.md file in the repository that contains information describing how a coding agent seeing it for the first time can work most efficiently. |
There was a problem hiding this comment.
🧹 Nitpick | 🔵 Trivial
Consider breaking the long sentence for readability.
Line 14 contains an 88-word run-on sentence. Breaking it into smaller sentences would improve clarity and make the instructions easier to follow.
✂️ Proposed refactor
-Your task is to "onboard" this repository to Copilot coding agent by adding a .github/copilot-instructions.md file in the repository that contains information describing how a coding agent seeing it for the first time can work most efficiently.
+Your task is to "onboard" this repository to Copilot coding agent. You will create a `.github/copilot-instructions.md` file containing information that enables a coding agent seeing the repository for the first time to work most efficiently.📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| Your task is to "onboard" this repository to Copilot coding agent by adding a .github/copilot-instructions.md file in the repository that contains information describing how a coding agent seeing it for the first time can work most efficiently. | |
| Your task is to "onboard" this repository to Copilot coding agent. You will create a `.github/copilot-instructions.md` file containing information that enables a coding agent seeing the repository for the first time to work most efficiently. |
🧰 Tools
🪛 LanguageTool
[uncategorized] ~14-~14: The official name of this software platform is spelled with a capital “H”.
Context: ...ry to Copilot coding agent by adding a .github/copilot-instructions.md file in the rep...
(GITHUB)
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In @.github/agents/my-agent.agent.md at line 14, The long 88-word run-on
sentence in .github/agents/my-agent.agent.md (the paragraph at line 14) should
be split into two or three shorter sentences for readability; edit that
paragraph to separate independent clauses into clear sentences, keeping the same
meaning and any key instructions for onboarding, and ensure punctuation and
capitalization are corrected so the resulting text is concise and easier for a
coding agent to parse.
|
|
||
| <WhatToAdd> | ||
|
|
||
| Add the following high level details about the codebase to reduce the amount of searching the agent has to do to understand the codebase each time: |
There was a problem hiding this comment.
🧹 Nitpick | 🔵 Trivial
Consider grammar improvements for professional documentation.
Static analysis identified several compound adjectives that should be hyphenated, and a wordy phrase:
- Line 33: "high level details" → "high-level details"
- Line 37: "High level repository" → "High-level repository"
- Line 60: "prior to check in" → "before check-in" or "prior to check-in"
While these are minor style issues, addressing them improves readability and professionalism.
📐 Proposed grammar fixes
-Add the following high level details about the codebase to reduce the amount of searching the agent has to do to understand the codebase each time:
+Add the following high-level details about the codebase to reduce the amount of searching the agent has to do to understand the codebase each time:-- High level repository information, such as the size of the repo, the type of the project, the languages, frameworks, or target runtimes in use.
+- High-level repository information, such as the size of the repo, the type of the project, the languages, frameworks, or target runtimes in use.-- A description of the checks run prior to check in, including any GitHub workflows, continuous integration builds, or other validation pipelines.
+- A description of the checks run before check-in, including any GitHub workflows, continuous integration builds, or other validation pipelines.Also applies to: 37-37, 60-60
🧰 Tools
🪛 LanguageTool
[grammar] ~33-~33: Use a hyphen to join words.
Context: ...ns> Add the following high level details about the codebase to redu...
(QB_NEW_EN_HYPHEN)
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In @.github/agents/my-agent.agent.md at line 33, The document
.github/agents/my-agent.agent.md contains unhyphenated compound adjectives and a
wordy phrase; update the phrases "high level details" to "high-level details",
"High level repository" to "High-level repository", and "prior to check in" to
"before check-in" (or "prior to check-in") wherever they appear (e.g., around
the strings visible at line 33, 37, and 60) to improve grammar and consistency
in the agent documentation.
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 01e8901335
ℹ️ About Codex in GitHub
Codex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".
| - For each file: | ||
| - Think: are the contents or the existence of the file information that the coding agent will need to implement, build, test, validate, or demo a code change? | ||
| - If yes: |
There was a problem hiding this comment.
The list items starting at Think: and If yes: are aligned with For each file: instead of being nested beneath it, so Markdown parses them as sibling bullets rather than per-file substeps. In practice this weakens the instruction from "repeat for every file" to a one-off checklist, which can cause the onboarding agent to miss file-by-file evaluation and produce less complete copilot-instructions.md output.
Useful? React with 👍 / 👎.
⚡ Quickly spin up Copilot coding agent tasks from anywhere on your macOS or Windows machine with Raycast.