From c79725c4d2c4b58a6533213e0471735121a1c541 Mon Sep 17 00:00:00 2001 From: Keegan Carruthers-Smith Date: Fri, 31 Jul 2026 10:00:58 +0200 Subject: [PATCH 1/3] docs/agents: explain reusable guidance and skills Deep Search and Agentic Batch Changes already support organization-specific instructions, but users have no reference for configuring or structuring them. Document the shared model and its product-specific boundaries so teams can adopt it without assuming guidance is discovered automatically. Amp-Thread-ID: https://ampcode.com/threads/T-019fb4d3-5d60-7116-9ad2-f8bbf81426ad Co-authored-by: Amp --- docs/agentic-batch-changes/index.mdx | 21 ++++++++++-- docs/deep-search/index.mdx | 48 ++++++++++++++++++++++++++++ 2 files changed, 66 insertions(+), 3 deletions(-) diff --git a/docs/agentic-batch-changes/index.mdx b/docs/agentic-batch-changes/index.mdx index f8d71f282..0db7bf904 100644 --- a/docs/agentic-batch-changes/index.mdx +++ b/docs/agentic-batch-changes/index.mdx @@ -52,10 +52,25 @@ We recommend encoding guidance that works for your organization via [agent custo ### Customization -Most organizations will also have specific conventions, technologies, and preferences. The agent may discover some of these conventions in its research, but you can also improve performance by customizing the agent with skills and `AGENTS.md`-style guidance, available on a per-user, per-organization, or global level in settings: +Most organizations have specific conventions, technologies, and workflows. The agent may discover some of these conventions in its research, but you can improve performance by providing durable `AGENTS.md` guidance and task-specific skills. -- **User settings → Batch Changes → Agent** -- **Administration → Batch Changes → Agent** + + Agent customization is currently experimental. Guidance and skills are + loaded by the coordinating Agentic Batch Changes agent only. Coding agents + used by [coding agent steps](#coding-agent-steps), such as Claude Code and + Codex, do not receive this customization. + + +Customization is available globally, for an organization, or for an individual user: + +- **User settings → Batch Changes → Agents** +- **Administration → Batch Changes → Agents** + +Organization administrators can configure the `batchChangeAgents.guidance` setting in organization settings. Settings are combined in this order: global, organization, then personal. If multiple skills have the same name (case-insensitive), the later setting wins. + +You can add customization directly in settings or load it from a repository source. A source can contain an `AGENTS.md` file and skills under `.agents/skills//SKILL.md` or `skills//SKILL.md`. `AGENTS.md` guidance is included in every agent run, while the agent loads a skill's full instructions only when its name and description indicate that the skill is relevant. + +Repository sources must be added explicitly; the agent does not automatically load guidance from every repository it plans to change. For the expected repository layout, `SKILL.md` format, source options, and precedence details, see [Customizing Deep Search with guidance and skills](/deep-search#customizing-deep-search-with-guidance-and-skills). Agentic Batch Changes uses the same guidance and skill format. ### Changeset hooks diff --git a/docs/deep-search/index.mdx b/docs/deep-search/index.mdx index f9ff24d13..d1d8fe5f9 100644 --- a/docs/deep-search/index.mdx +++ b/docs/deep-search/index.mdx @@ -35,6 +35,54 @@ The answer is formatted in Markdown and can include links to relevant files, dir - Provide reasonably scoped questions. The agent will perform much better if it does not have to read the entire codebase at once. - Check the list of sources. This is extremely useful for debugging and understanding where the answer came from. Ask a follow-up question and mention the missing source if something is missing. +## Customizing Deep Search with guidance and skills + +Agent customization is currently experimental. + +You can customize Deep Search with organization-specific conventions, architecture details, and workflows. Customization can be configured globally, for an organization, or for an individual user. Deep Search supports three kinds of customization: + +- **`AGENTS.md` guidance** provides durable instructions that are included in every Deep Search run. Use it for conventions that should always apply, such as which repositories are authoritative or how answers should cite internal systems. +- **Skills** provide instructions for a particular task or workflow. Deep Search sees each skill's name and description, then loads the full instructions only when the skill is relevant. This avoids adding unrelated instructions to every search. +- **Sources** load an `AGENTS.md` file and skills from a repository on Sourcegraph. A source can use the repository root or a specific path and branch. + +To configure personal customization, go to **User settings → Deep Search → Agents**. Site administrators can configure global customization under **Administration → Deep Search → Agents**. Organization administrators can configure the `deepSearch.guidance` setting in organization settings. + +Settings are combined in this order: global, organization, then personal. All `AGENTS.md` guidance is appended in that order. If multiple skills have the same name (case-insensitive), the later setting wins, so a personal skill can override an organization or global skill. + +### Loading guidance and skills from a repository + +Add a **Source** to reuse customization stored in a repository. Specify the repository name and, optionally, a path and branch. The default branch and repository root are used when those fields are omitted. The configured location can have this structure: + +```text +AGENTS.md +.agents/ +└── skills/ + └── investigate-incident/ + ├── SKILL.md + └── references/ + └── services.md +``` + +The `AGENTS.md` file must be directly inside the configured location. Skills can be placed at either `.agents/skills//SKILL.md` or `skills//SKILL.md`. Only `SKILL.md` is loaded automatically; it can direct the agent to supporting files in the same skill directory when they are needed. + +A `SKILL.md` file can use [Agent Skills](https://agentskills.io/home) frontmatter to give the agent enough information to decide when to load it: + +```markdown +--- +name: investigate-incident +description: Trace an incident from a service name or alert to the responsible code. +--- + +# Investigate an incident + +Start with the service catalog in `references/services.md`, then identify the +entry point, owners, and recent changes to the relevant code. +``` + +The directory name is used as the skill name when `name` is omitted. A concise, specific `description` helps Deep Search select the skill for the right questions. + +Repository sources are not discovered automatically from the repositories in a query or search context. Add each source explicitly in settings. The latest content at the configured branch or revision is loaded when a Deep Search run starts, so updates do not require changing the Sourcegraph setting. + ## Using search contexts You can reuse the same [search contexts](/code-search/working/search-contexts) you already use in Code Search when creating a new Deep Search query. Click **Set scope** in the composer to select a search context and limit Deep Search to that repository scope. Deep Search automatically pre-selects your default search context. From 54513f0181e46e267c11adefe94c7f856405a77c Mon Sep 17 00:00:00 2001 From: Keegan Carruthers-Smith Date: Fri, 31 Jul 2026 10:29:16 +0200 Subject: [PATCH 2/3] docs/agents: present customization as generally available Agent customization is not experimental, so avoid setting the wrong expectation while retaining the important coordinator-only limitation for Agentic Batch Changes. Amp-Thread-ID: https://ampcode.com/threads/T-019fb4d3-5d60-7116-9ad2-f8bbf81426ad Co-authored-by: Amp --- docs/agentic-batch-changes/index.mdx | 7 +++---- docs/deep-search/index.mdx | 2 -- 2 files changed, 3 insertions(+), 6 deletions(-) diff --git a/docs/agentic-batch-changes/index.mdx b/docs/agentic-batch-changes/index.mdx index 0db7bf904..34e23caf0 100644 --- a/docs/agentic-batch-changes/index.mdx +++ b/docs/agentic-batch-changes/index.mdx @@ -55,10 +55,9 @@ We recommend encoding guidance that works for your organization via [agent custo Most organizations have specific conventions, technologies, and workflows. The agent may discover some of these conventions in its research, but you can improve performance by providing durable `AGENTS.md` guidance and task-specific skills. - Agent customization is currently experimental. Guidance and skills are - loaded by the coordinating Agentic Batch Changes agent only. Coding agents - used by [coding agent steps](#coding-agent-steps), such as Claude Code and - Codex, do not receive this customization. + Guidance and skills are loaded by the coordinating Agentic Batch Changes + agent only. Coding agents used by [coding agent steps](#coding-agent-steps), + such as Claude Code and Codex, do not receive this customization. Customization is available globally, for an organization, or for an individual user: diff --git a/docs/deep-search/index.mdx b/docs/deep-search/index.mdx index d1d8fe5f9..c6d870a8c 100644 --- a/docs/deep-search/index.mdx +++ b/docs/deep-search/index.mdx @@ -37,8 +37,6 @@ The answer is formatted in Markdown and can include links to relevant files, dir ## Customizing Deep Search with guidance and skills -Agent customization is currently experimental. - You can customize Deep Search with organization-specific conventions, architecture details, and workflows. Customization can be configured globally, for an organization, or for an individual user. Deep Search supports three kinds of customization: - **`AGENTS.md` guidance** provides durable instructions that are included in every Deep Search run. Use it for conventions that should always apply, such as which repositories are authoritative or how answers should cite internal systems. From a9b0c862a1fd861b3855ced9c36573f745dae6e7 Mon Sep 17 00:00:00 2001 From: Keegan Carruthers-Smith Date: Fri, 31 Jul 2026 10:38:11 +0200 Subject: [PATCH 3/3] docs/deep-search: keep customization guidance lightweight Match the concise Agentic Batch Changes treatment and point users to the settings pages that will be exposed in the product, without duplicating implementation details in the overview. Amp-Thread-ID: https://ampcode.com/threads/T-019fb4d3-5d60-7116-9ad2-f8bbf81426ad Co-authored-by: Amp --- docs/agentic-batch-changes/index.mdx | 20 ++---------- docs/deep-search/index.mdx | 47 +++------------------------- 2 files changed, 7 insertions(+), 60 deletions(-) diff --git a/docs/agentic-batch-changes/index.mdx b/docs/agentic-batch-changes/index.mdx index 34e23caf0..f8d71f282 100644 --- a/docs/agentic-batch-changes/index.mdx +++ b/docs/agentic-batch-changes/index.mdx @@ -52,24 +52,10 @@ We recommend encoding guidance that works for your organization via [agent custo ### Customization -Most organizations have specific conventions, technologies, and workflows. The agent may discover some of these conventions in its research, but you can improve performance by providing durable `AGENTS.md` guidance and task-specific skills. +Most organizations will also have specific conventions, technologies, and preferences. The agent may discover some of these conventions in its research, but you can also improve performance by customizing the agent with skills and `AGENTS.md`-style guidance, available on a per-user, per-organization, or global level in settings: - - Guidance and skills are loaded by the coordinating Agentic Batch Changes - agent only. Coding agents used by [coding agent steps](#coding-agent-steps), - such as Claude Code and Codex, do not receive this customization. - - -Customization is available globally, for an organization, or for an individual user: - -- **User settings → Batch Changes → Agents** -- **Administration → Batch Changes → Agents** - -Organization administrators can configure the `batchChangeAgents.guidance` setting in organization settings. Settings are combined in this order: global, organization, then personal. If multiple skills have the same name (case-insensitive), the later setting wins. - -You can add customization directly in settings or load it from a repository source. A source can contain an `AGENTS.md` file and skills under `.agents/skills//SKILL.md` or `skills//SKILL.md`. `AGENTS.md` guidance is included in every agent run, while the agent loads a skill's full instructions only when its name and description indicate that the skill is relevant. - -Repository sources must be added explicitly; the agent does not automatically load guidance from every repository it plans to change. For the expected repository layout, `SKILL.md` format, source options, and precedence details, see [Customizing Deep Search with guidance and skills](/deep-search#customizing-deep-search-with-guidance-and-skills). Agentic Batch Changes uses the same guidance and skill format. +- **User settings → Batch Changes → Agent** +- **Administration → Batch Changes → Agent** ### Changeset hooks diff --git a/docs/deep-search/index.mdx b/docs/deep-search/index.mdx index c6d870a8c..9d8e75f34 100644 --- a/docs/deep-search/index.mdx +++ b/docs/deep-search/index.mdx @@ -35,51 +35,12 @@ The answer is formatted in Markdown and can include links to relevant files, dir - Provide reasonably scoped questions. The agent will perform much better if it does not have to read the entire codebase at once. - Check the list of sources. This is extremely useful for debugging and understanding where the answer came from. Ask a follow-up question and mention the missing source if something is missing. -## Customizing Deep Search with guidance and skills +## Customization -You can customize Deep Search with organization-specific conventions, architecture details, and workflows. Customization can be configured globally, for an organization, or for an individual user. Deep Search supports three kinds of customization: +Most organizations will also have specific conventions, technologies, and preferences. Deep Search may discover some of these conventions in its research, but you can also improve performance by customizing it with skills and `AGENTS.md`-style guidance, available on a per-user, per-organization, or global level in settings: -- **`AGENTS.md` guidance** provides durable instructions that are included in every Deep Search run. Use it for conventions that should always apply, such as which repositories are authoritative or how answers should cite internal systems. -- **Skills** provide instructions for a particular task or workflow. Deep Search sees each skill's name and description, then loads the full instructions only when the skill is relevant. This avoids adding unrelated instructions to every search. -- **Sources** load an `AGENTS.md` file and skills from a repository on Sourcegraph. A source can use the repository root or a specific path and branch. - -To configure personal customization, go to **User settings → Deep Search → Agents**. Site administrators can configure global customization under **Administration → Deep Search → Agents**. Organization administrators can configure the `deepSearch.guidance` setting in organization settings. - -Settings are combined in this order: global, organization, then personal. All `AGENTS.md` guidance is appended in that order. If multiple skills have the same name (case-insensitive), the later setting wins, so a personal skill can override an organization or global skill. - -### Loading guidance and skills from a repository - -Add a **Source** to reuse customization stored in a repository. Specify the repository name and, optionally, a path and branch. The default branch and repository root are used when those fields are omitted. The configured location can have this structure: - -```text -AGENTS.md -.agents/ -└── skills/ - └── investigate-incident/ - ├── SKILL.md - └── references/ - └── services.md -``` - -The `AGENTS.md` file must be directly inside the configured location. Skills can be placed at either `.agents/skills//SKILL.md` or `skills//SKILL.md`. Only `SKILL.md` is loaded automatically; it can direct the agent to supporting files in the same skill directory when they are needed. - -A `SKILL.md` file can use [Agent Skills](https://agentskills.io/home) frontmatter to give the agent enough information to decide when to load it: - -```markdown ---- -name: investigate-incident -description: Trace an incident from a service name or alert to the responsible code. ---- - -# Investigate an incident - -Start with the service catalog in `references/services.md`, then identify the -entry point, owners, and recent changes to the relevant code. -``` - -The directory name is used as the skill name when `name` is omitted. A concise, specific `description` helps Deep Search select the skill for the right questions. - -Repository sources are not discovered automatically from the repositories in a query or search context. Add each source explicitly in settings. The latest content at the configured branch or revision is loaded when a Deep Search run starts, so updates do not require changing the Sourcegraph setting. +- **User settings → Deep Search → Agents** +- **Administration → Deep Search → Agents** ## Using search contexts