From cdaa41d3bab465a376ff41d458ab13c76eea9154 Mon Sep 17 00:00:00 2001
From: Sameeksha Vaity <savaity@microsoft.com>
Date: Tue, 31 Mar 2026 14:36:00 -0700
Subject: [PATCH 1/3] Add find-package-skill registry for package-specific
 skills
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Add the find-package-skill discovery skill at .github/skills/, matching the
pattern established in azure-sdk-for-js, azure-sdk-for-python, and
azure-sdk-for-net. This skill serves as a routing table that tells AI agents
to check for package-specific domain knowledge before modifying any SDK package.

The package skills table is currently empty — package teams can register their
skills here as they create them (e.g., azure-search-documents).

Related PRs:
- JS: https://github.com/Azure/azure-sdk-for-js/pull/37484
- Python: https://github.com/Azure/azure-sdk-for-python/pull/45972
- .NET: https://github.com/Azure/azure-sdk-for-net/pull/57580

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
---
 .github/skills/find-package-skill/SKILL.md | 24 ++++++++++++++++++++++
 1 file changed, 24 insertions(+)
 create mode 100644 .github/skills/find-package-skill/SKILL.md

diff --git a/.github/skills/find-package-skill/SKILL.md b/.github/skills/find-package-skill/SKILL.md
new file mode 100644
index 000000000000..c5032106ff47
--- /dev/null
+++ b/.github/skills/find-package-skill/SKILL.md
@@ -0,0 +1,24 @@
+---
+name: find-package-skill
+description: '**UTILITY SKILL** — Must be consulted before making any changes to packages under sdk/. Provides package-specific domain knowledge that prevents common mistakes. WHEN: add feature to package; fix bug in package; modify package code; regenerate from typespec; change client library.'
+---
+
+# Find Package Skill
+
+Before modifying any SDK package in this monorepo, check this registry to see
+if a package-specific skill exists. Package skills contain tribal knowledge
+(architecture, data flows, type mappings, pitfalls) that prevents common mistakes.
+
+Always check this registry before modifying any SDK package — even if you think
+you already know the package well.
+
+## How to Use
+
+1. Find the package you're modifying in the table below.
+2. Read the SKILL.md at the listed path using the Read tool. Then read all files under the `references/` directory next to it for additional context.
+3. If the package isn't listed, no package-specific skill exists yet — proceed normally.
+
+## Package Skills
+
+| Package                    | Path                                                                                              |
+| -------------------------- | ------------------------------------------------------------------------------------------------- |

From 47b0e27af97cfa3c7c39947890c8946585d366ae Mon Sep 17 00:00:00 2001
From: Sameeksha Vaity <savaity@microsoft.com>
Date: Wed, 1 Apr 2026 11:56:50 -0700
Subject: [PATCH 2/3] Add search-documents placeholder skill with scaffolded
 sections

Add a placeholder package skill for azure-search-documents with headings
matching the pattern from JS, Python, and .NET search skills. Sections
are TODO stubs for domain experts to fill in:
- Common Pitfalls, Architecture, Regeneration Workflow, Key Files,
  Service Version Management, Post-Regeneration Customizations,
  Type Mappings, Testing Notes
- references/architecture.md and references/customizations.md placeholders
- Registered in find-package-skill table

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
---
 .github/skills/find-package-skill/SKILL.md    |  1 +
 .../.github/skills/search-documents/SKILL.md  | 71 +++++++++++++++++++
 .../references/architecture.md                |  4 ++
 .../references/customizations.md              |  4 ++
 4 files changed, 80 insertions(+)
 create mode 100644 sdk/search/azure-search-documents/.github/skills/search-documents/SKILL.md
 create mode 100644 sdk/search/azure-search-documents/.github/skills/search-documents/references/architecture.md
 create mode 100644 sdk/search/azure-search-documents/.github/skills/search-documents/references/customizations.md

diff --git a/.github/skills/find-package-skill/SKILL.md b/.github/skills/find-package-skill/SKILL.md
index c5032106ff47..e364f2706758 100644
--- a/.github/skills/find-package-skill/SKILL.md
+++ b/.github/skills/find-package-skill/SKILL.md
@@ -22,3 +22,4 @@ you already know the package well.
 
 | Package                    | Path                                                                                              |
 | -------------------------- | ------------------------------------------------------------------------------------------------- |
+| `azure-search-documents`   | `sdk/search/azure-search-documents/.github/skills/search-documents/SKILL.md`                      |
diff --git a/sdk/search/azure-search-documents/.github/skills/search-documents/SKILL.md b/sdk/search/azure-search-documents/.github/skills/search-documents/SKILL.md
new file mode 100644
index 000000000000..0785f986a3e5
--- /dev/null
+++ b/sdk/search/azure-search-documents/.github/skills/search-documents/SKILL.md
@@ -0,0 +1,71 @@
+---
+name: search-documents
+description: 'Post-regeneration customization guide for azure-search-documents Java SDK. After running tsp-client update, consult this skill to re-apply search-specific customizations and produce a production-ready SDK. WHEN: regenerate search SDK; search tsp-client update; fix search customization errors; search API version update; search SDK release; update search service version.'
+---
+
+# azure-search-documents — Package Skill (Java)
+
+<!-- TODO: Domain experts should fill in the sections below with tribal knowledge
+     specific to this package. See the @azure/search-documents skill in azure-sdk-for-js
+     and azure-search-documents skill in azure-sdk-for-python as references. -->
+
+## Common Pitfalls
+
+<!-- TODO: List the most dangerous mistakes an agent can make with this package.
+     Put these BEFORE the workflow — agents read them first. -->
+
+## Architecture
+
+<!-- TODO: High-level layout. Where does generated code live? What's hand-authored?
+     How do they interact? Document the customizations/ directory and SearchCustomizations.java. -->
+
+### Source Layout
+
+<!-- TODO: Show the directory tree. Mark files as GENERATED vs hand-written. -->
+
+### Generated vs Custom Code
+
+<!-- TODO: Explain the @Generated annotation. Methods WITH @Generated are auto-updated
+     by the generator. Methods WITHOUT @Generated in generated files are hand-written
+     convenience wrappers that need manual updates after regeneration. -->
+
+## Regeneration Workflow
+
+<!-- TODO: The exact commands to regenerate. What breaks after regeneration?
+     What needs manual fixup? Include gated phases. -->
+
+## Key Files
+
+<!-- TODO: The files an agent should read before making changes, and what each one does.
+     Include tsp-location.yaml, SearchCustomizations.java, pom.xml, CHANGELOG.md. -->
+
+## Service Version Management
+
+<!-- TODO: How SearchServiceVersion enum works. How includeOldApiVersions() customization
+     adds backward-compat versions. Dedup guard needed. -->
+
+## Post-Regeneration Customizations
+
+<!-- TODO: Document each customization method in SearchCustomizations.java:
+     - hideGeneratedSearchApis
+     - addSearchAudienceScopeHandling
+     - includeOldApiVersions
+     - removeGetApis
+     - hideWithResponseBinaryDataApis (the most fragile one) -->
+
+## Type Mappings
+
+<!-- TODO: Property name differences between public API and wire format,
+     any type conversions, null handling patterns. -->
+
+## Testing Notes
+
+<!-- TODO: How to run tests, recorded test setup with assets.json,
+     environment requirements for live tests. -->
+
+## References
+
+| File | Contents |
+|------|----------|
+| [references/architecture.md](references/architecture.md) | Source layout, package map, dependencies |
+| [references/customizations.md](references/customizations.md) | JavaParser AST patterns, per-customization update guidance |
diff --git a/sdk/search/azure-search-documents/.github/skills/search-documents/references/architecture.md b/sdk/search/azure-search-documents/.github/skills/search-documents/references/architecture.md
new file mode 100644
index 000000000000..e8e034087b72
--- /dev/null
+++ b/sdk/search/azure-search-documents/.github/skills/search-documents/references/architecture.md
@@ -0,0 +1,4 @@
+# azure-search-documents SDK Architecture (Java)
+
+<!-- TODO: Document the full source layout, generated vs custom split,
+     package map, service version rules, and dependency information. -->
diff --git a/sdk/search/azure-search-documents/.github/skills/search-documents/references/customizations.md b/sdk/search/azure-search-documents/.github/skills/search-documents/references/customizations.md
new file mode 100644
index 000000000000..70a4f1c4dcd9
--- /dev/null
+++ b/sdk/search/azure-search-documents/.github/skills/search-documents/references/customizations.md
@@ -0,0 +1,4 @@
+# azure-search-documents — Customization Guide (Java)
+
+<!-- TODO: Document JavaParser AST patterns, SearchCustomizations.java methods,
+     per-customization update guidance, and common customization patterns. -->

From 3de677d47a6f6460d654d50145b51ed2febfe0a1 Mon Sep 17 00:00:00 2001
From: Sameeksha Vaity <savaity@microsoft.com>
Date: Wed, 1 Apr 2026 12:00:40 -0700
Subject: [PATCH 3/3] Clean up search skill placeholder: remove (Java) tags, JS
 refs, Type Mappings section

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
---
 .../.github/skills/search-documents/SKILL.md         | 12 +++---------
 .../search-documents/references/architecture.md      |  2 +-
 .../search-documents/references/customizations.md    |  2 +-
 3 files changed, 5 insertions(+), 11 deletions(-)

diff --git a/sdk/search/azure-search-documents/.github/skills/search-documents/SKILL.md b/sdk/search/azure-search-documents/.github/skills/search-documents/SKILL.md
index 0785f986a3e5..8e4f72d5f40b 100644
--- a/sdk/search/azure-search-documents/.github/skills/search-documents/SKILL.md
+++ b/sdk/search/azure-search-documents/.github/skills/search-documents/SKILL.md
@@ -1,13 +1,12 @@
 ---
 name: search-documents
-description: 'Post-regeneration customization guide for azure-search-documents Java SDK. After running tsp-client update, consult this skill to re-apply search-specific customizations and produce a production-ready SDK. WHEN: regenerate search SDK; search tsp-client update; fix search customization errors; search API version update; search SDK release; update search service version.'
+description: 'Post-regeneration customization guide for azure-search-documents SDK. After running tsp-client update, consult this skill to re-apply search-specific customizations and produce a production-ready SDK. WHEN: regenerate search SDK; search tsp-client update; fix search customization errors; search API version update; search SDK release; update search service version.'
 ---
 
-# azure-search-documents — Package Skill (Java)
+# azure-search-documents — Package Skill
 
 <!-- TODO: Domain experts should fill in the sections below with tribal knowledge
-     specific to this package. See the @azure/search-documents skill in azure-sdk-for-js
-     and azure-search-documents skill in azure-sdk-for-python as references. -->
+     specific to this package. -->
 
 ## Common Pitfalls
 
@@ -53,11 +52,6 @@ description: 'Post-regeneration customization guide for azure-search-documents J
      - removeGetApis
      - hideWithResponseBinaryDataApis (the most fragile one) -->
 
-## Type Mappings
-
-<!-- TODO: Property name differences between public API and wire format,
-     any type conversions, null handling patterns. -->
-
 ## Testing Notes
 
 <!-- TODO: How to run tests, recorded test setup with assets.json,
diff --git a/sdk/search/azure-search-documents/.github/skills/search-documents/references/architecture.md b/sdk/search/azure-search-documents/.github/skills/search-documents/references/architecture.md
index e8e034087b72..49393c38d070 100644
--- a/sdk/search/azure-search-documents/.github/skills/search-documents/references/architecture.md
+++ b/sdk/search/azure-search-documents/.github/skills/search-documents/references/architecture.md
@@ -1,4 +1,4 @@
-# azure-search-documents SDK Architecture (Java)
+# azure-search-documents SDK Architecture
 
 <!-- TODO: Document the full source layout, generated vs custom split,
      package map, service version rules, and dependency information. -->
diff --git a/sdk/search/azure-search-documents/.github/skills/search-documents/references/customizations.md b/sdk/search/azure-search-documents/.github/skills/search-documents/references/customizations.md
index 70a4f1c4dcd9..eaa28fb33c05 100644
--- a/sdk/search/azure-search-documents/.github/skills/search-documents/references/customizations.md
+++ b/sdk/search/azure-search-documents/.github/skills/search-documents/references/customizations.md
@@ -1,4 +1,4 @@
-# azure-search-documents — Customization Guide (Java)
+# azure-search-documents — Customization Guide
 
 <!-- TODO: Document JavaParser AST patterns, SearchCustomizations.java methods,
      per-customization update guidance, and common customization patterns. -->