Document that custom agents work from both .github and .github-private repos (#61338)

Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>

Author: joshjohanning

content/copilot/how-tos/administer-copilot/manage-for-organization/prepare-for-custom-agents.md

@@ -22,12 +22,19 @@ You should understand what {% data variables.copilot.copilot_custom_agents %} ar
 
 ## Preparing your organization for {% data variables.copilot.custom_agents_short %}
 
+Organization-level {% data variables.copilot.custom_agents_short %} are stored in the `/agents` directory of your organization's `.github` or `.github-private` repository. Both work the same way and make the {% data variables.copilot.custom_agents_short %} available to all members of the organization, regardless of whether they have access to the repository itself.
+
+For more information on `.github` and `.github-private` repositories, see [AUTOTITLE](/organizations/collaborating-with-groups-in-organizations/customizing-your-organizations-profile).
+
+If you don't already have a suitable repository, follow the steps below to create one. These steps describe creating a `.github-private` repository, but you can also create a `.github` repository by naming it `.github` instead.
+
 1. Create your {% data variables.copilot.copilot_custom_agent_short %} repository using [{% data variables.product.github %}'s template repository](https://github.com/docs/custom-agents-template?ref_product=copilot&ref_type=engagement&ref_style=text). The template includes a README and the file structure you need.
 1. In the **Choose an owner** {% octicon "triangle-down" aria-hidden="true" aria-label="triangle-down" %} dropdown menu, choose your organization.
 1. Name the repository `.github-private` and write a brief description.
-1. In the visibility dropdown menu, choose one of the following options:
-     * Click {% octicon "organization" aria-hidden="true" aria-label="organization" %} **Internal** to grant read access to all members of your organization or enterprise.
-     * Click {% octicon "lock" aria-hidden="true" aria-label="lock" %} **Private** to manually grant access after creation or if internal visibility is not an option.
+1. In the visibility dropdown menu, click {% octicon "lock" aria-hidden="true" aria-label="lock" %} **Private**.
+     * Organization members will still be able to use {% data variables.copilot.custom_agents_short %} stored in this repository, regardless of whether they have direct access to the repository itself. Keeping the repository private also avoids conflicts with other features that require `.github-private` to be private, such as the organization member-only profile README.
+    * If you want organization members to view and collaborate on the {% data variables.copilot.agent_profiles %} directly, consider using a `.github` repository with {% octicon "organization" aria-hidden="true" aria-label="organization" %} **Internal** visibility. If you are an open source organization and want to share the {% data variables.copilot.custom_agents_short %} publicly, select {% octicon "globe" aria-hidden="true" aria-label="globe" %} **Public** visibility.
+
 {% data reusables.repositories.create-repo %}
 1. Update the template README. Include any creation guidelines for {% data variables.copilot.custom_agents_short %} or compliance considerations specific to your organization.
 

content/copilot/how-tos/copilot-cli/use-copilot-cli/invoke-custom-agents.md

@@ -51,15 +51,16 @@ The AI model being used by the CLI can choose to delegate a task to a subsidiary
 
 You can define your own {% data variables.copilot.custom_agents_short %} using Markdown files, called {% data variables.copilot.agent_profiles %}, that specify what expertise the agent should have, what tools it can use, and any specific instructions for how it should respond.
 
-You can define {% data variables.copilot.custom_agents_short %} at the user, repository, or organization/enterprise level:
+You can define {% data variables.copilot.custom_agents_short %} at the user, repository, organization, or enterprise level:
 
 | Type | Location | Scope |
 | --- | --- | --- |
 | User-level {% data variables.copilot.copilot_custom_agent_short %} | local `~/.copilot/agents` directory | All projects |
 | Repository-level {% data variables.copilot.copilot_custom_agent_short %} | `.github/agents` directory in your local and remote repositories | Current project |
-| Organization and Enterprise-level {% data variables.copilot.copilot_custom_agent_short %} | `/agents` directory in the `.github-private` repository in an organization or enterprise | All projects under your organization and enterprise account |
+| Organization-level {% data variables.copilot.copilot_custom_agent_short %} | `/agents` directory in the organization's `.github` or `.github-private` repository | All projects within the organization |
+| Enterprise-level {% data variables.copilot.copilot_custom_agent_short %} | `/agents` directory in the `.github-private` repository of an organization designated in enterprise settings. For more information, see [AUTOTITLE](/copilot/how-tos/administer-copilot/manage-for-enterprise/manage-agents/prepare-for-custom-agents#enabling-and-protecting-custom-agents-in-your-enterprise). | All projects under the enterprise account |
 
-In the case of naming conflicts, a system-level agent overrides a repository-level agent, and the repository-level agent would override an organization-level agent.
+In the case of naming conflicts (where agents share the same filename), a user-level agent overrides a repository-level agent, a repository-level agent overrides an organization-level agent, and an organization-level agent overrides an enterprise-level agent.
 
 {% data variables.copilot.custom_agents_caps_short %} can be used in three ways:
 

content/copilot/how-tos/copilot-on-github/customize-copilot/customize-cloud-agent/create-custom-agents.md

@@ -25,7 +25,7 @@ redirect_from:
 1. Using the dropdown menu in the prompt box, select the repository you want to create the {% data variables.copilot.copilot_custom_agent_short %} profile in.
 
    > [!NOTE]
-   > Organization and enterprise owners can create organization and enterprise-level {% data variables.copilot.custom_agents_short %} in a `.github-private` repository that are available across all repositories within their organization or enterprise. For more information, see [AUTOTITLE](/copilot/how-tos/administer-copilot/manage-for-enterprise/manage-agents/prepare-for-custom-agents) and [AUTOTITLE](/copilot/how-tos/administer-copilot/manage-for-organization/prepare-for-custom-agents).
+   > Organization owners can create organization-level {% data variables.copilot.custom_agents_short %} in the organization's `.github` or `.github-private` repository that are available across all repositories within their organization. Enterprise owners can create enterprise-level {% data variables.copilot.custom_agents_short %} in the `.github-private` repository of an organization designated in enterprise settings, available across all organizations in the enterprise. For more information, see [AUTOTITLE](/copilot/how-tos/administer-copilot/manage-for-organization/prepare-for-custom-agents) and [AUTOTITLE](/copilot/how-tos/administer-copilot/manage-for-enterprise/manage-agents/prepare-for-custom-agents).
 
 1. Optionally, select the branch you want to create the {% data variables.copilot.agent_profile %} in. The default is the main branch.
 1. Click {% octicon "copilot" aria-label="Select a custom agent" %}, then click **{% octicon "plus" aria-label="Plus button" %} Create an agent**. This will open a template agent profile called `my-agent.agent.md` in the `.github/agents` directory of your target repository.

content/copilot/reference/customization-cheat-sheet.md

@@ -19,7 +19,7 @@ This table shows what each customization feature is and where it lives.
 |---------|-----------|-------------------|
 | [Custom instructions](/copilot/concepts/prompting/response-customization) | Always-on context that automatically applies to every interaction within its defined scope | `.github/copilot-instructions.md` (repo-wide), `.github/instructions/*.instructions.md` (path-specific), `AGENTS.md` (third-party agents), or personal/org settings via UI on {% data variables.product.github %} |
 | [Prompt files](/copilot/concepts/prompting/response-customization?tool=vscode#about-prompt-files) | Reusable, standalone prompt template with input variables | `.github/prompts/*.prompt.md` |
-| [{% data variables.copilot.custom_agents_caps_short %}](/copilot/concepts/agents/cloud-agent/about-custom-agents) | Specialist persona with its own instructions, tool restrictions, and context | `.github/agents/AGENT-NAME.md` (repo), `agents/AGENT-NAME.md` in `.github-private` repo (org/enterprise), or user profile |
+| [{% data variables.copilot.custom_agents_caps_short %}](/copilot/concepts/agents/cloud-agent/about-custom-agents) | Specialist persona with its own instructions, tool restrictions, and context | `.github/agents/AGENT-NAME.md` (repository), `/agents/AGENT-NAME.md` in the organization's `.github` or `.github-private` repository (org-level), `/agents/AGENT-NAME.md` in a designated `.github-private` repository (enterprise-level), or user profile |
 | [{% data variables.copilot.subagents_caps_short %}](/copilot/how-tos/chat-with-copilot/chat-in-ide#using-subagents) | Separate agent spawned by the main agent to handle delegated work in an isolated context | N/A (runtime process, not a user-configured file) |
 | [Agent skills](/copilot/concepts/agents/about-agent-skills) | Folder of instructions, scripts, and resources that {% data variables.product.prodname_copilot_short %} loads when relevant to a task | `.github/skills/<skill-name>/SKILL.md`, `.claude/skills/<skill-name>/SKILL.md`, or `.agents/skills/<skill-name>/SKILL.md` (project); `~/.copilot/skills/<skill-name>/SKILL.md` or `~/.agents/skills/<skill-name>/SKILL.md` (personal) |
 | [Hooks](/copilot/concepts/agents/hooks) | Custom shell commands that execute deterministically at specific points in an agent's workflow | `.github/hooks/*.json` |

data/reusables/copilot/copilot-cli/custom-agents-about-details.md

@@ -35,6 +35,7 @@ Focus on the following instructions:
 You can define {% data variables.copilot.agent_profiles %} at different levels:
 
 * **Repository level**: Create `.github/agents/CUSTOM-AGENT-NAME.md` in your repository for project-specific agents.
-* **Organization or enterprise level**: Create `/agents/CUSTOM-AGENT-NAME.md` in a `.github-private` repository for broader availability.
+* **Organization level**: Create `/agents/CUSTOM-AGENT-NAME.md` in the organization's `.github` or `.github-private` repository for broader availability within the organization.
+* **Enterprise level**: Create `/agents/CUSTOM-AGENT-NAME.md` in the `.github-private` repository of an organization that an enterprise owner has designated in enterprise settings for availability across all repositories in the enterprise.
 
 For more information, see [AUTOTITLE](/copilot/how-tos/administer-copilot/manage-for-organization/prepare-for-custom-agents) and [AUTOTITLE](/copilot/how-tos/administer-copilot/manage-for-enterprise/manage-agents/prepare-for-custom-agents).