Add agent dev skill for search by xiangyan99 · Pull Request #45972 · Azure/azure-sdk-for-python

xiangyan99 · 2026-03-27T21:48:34Z

Description

Add an agent dev skill for the search-documents package

Please add an informative description that covers that changes made by the pull request and link all relevant issues.

If an SDK is being regenerated based on a new API spec, a link to the pull request containing these API spec changes should be included above.

All SDK Contribution checklist:

The pull request does not introduce [breaking changes]
CHANGELOG is updated for new features, bug fixes or other significant changes.
I have read the contribution guidelines.

General Guidelines and Best Practices

Title of the pull request is clear and informative.
There are a small number of commits, each of which have an informative message. This means that previously merged commits do not appear in the history of the PR. For more information on cleaning up the commits in your PR, see this page.

Testing Guidelines

Pull request includes test coverage for the included changes.

Copilot

Pull request overview

Adds a package-specific “agent dev skill” for azure-search-documents to guide post-TypeSpec-regeneration validation and re-application of hand-authored _patch.py customizations, and registers it in the repo-wide package skill registry.

Changes:

Added a search-documents skill (SKILL.md) describing regeneration verification steps and customization patterns.
Added a references/customizations.md inventory of _patch.py customizations and their generated-code dependencies.
Updated the central find-package-skill registry to include azure-search-documents.

Reviewed changes

Copilot reviewed 3 out of 3 changed files in this pull request and generated 2 comments.

File	Description
`sdk/search/azure-search-documents/.github/skills/search-documents/references/customizations.md`	New checklist documenting each customization file’s defined symbols and regeneration verification points.
`sdk/search/azure-search-documents/.github/skills/search-documents/SKILL.md`	New skill guide for post-`tsp-client update` regeneration verification and customization re-checks.
`.github/skills/find-package-skill/SKILL.md`	Registers the `azure-search-documents` package skill in the central skill lookup table.

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

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: Azure/azure-sdk-for-js#37484 - Python: Azure/azure-sdk-for-python#45972 - .NET: Azure/azure-sdk-for-net#57580 Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

@efrainretana

) ## What This PR adds support for **package-specific skills** — tribal knowledge that agents load before modifying SDK packages. Two files: 1. **`.github/skills/find-package-skill/SKILL.md`** — a discovery skill that teaches agents how to find package-specific skills by checking for `.github/skills/` inside the package directory they're modifying. No hardcoded lookup table — the directory structure IS the source of truth. 2. **`sdk/search/Azure.Search.Documents/.github/skills/search-documents/SKILL.md`** — placeholder skill for Search with scaffolded sections for domain experts to fill in. ## Related PRs - Azure/azure-sdk-for-js#37484 - Azure/azure-sdk-for-python#45972 ## Callouts - @efrainretana is working on the contents of the Search skill for dotnet — this placeholder provides the hook for it to be picked up correctly. - Other language repos (JS, Python) currently use a registry table approach. If directory inference works well here, we could bring it to those repos too.

…nts/references/customizations.md Co-authored-by: McCoy Patiño <39780829+mccoyp@users.noreply.github.com>

hizixin · 2026-04-14T20:35:40Z

I also have a skill for this package in my branch that covers the end-to-end release workflow (phases 0–7: regen, sync patch files, tests, lint, changelog, samples, versioning). I'll send a follow-up PR after this merges to integrate the two.

@generated

Adds the infrastructure for service teams to create, validate, and maintain package-specific Copilot skills -- the tribal knowledge that helps AI agents work correctly on their SDK packages. ## What's included ### 1. find-package-skill (discovery registry) Routes agents to package-specific skills before modifying any SDK package. Matches the pattern from JS, Python, and .NET repos. ### 2. create-package-skill (bootstrap wizard) Interactive wizard that walks service teams through creating a skill: - Phase 0: Scan package (detect architecture, customizations, key files) - Phase 1: Scaffold SKILL.md (common pitfalls, error categorization, patterns) - Phase 2: Generate references (architecture.md, customizations.md) - Phase 3: Validate (vally lint + anchor checker) - Phase 4: Register in find-package-skill table ### 3. azure-search-documents (first package skill) Created using the wizard as a dogfood. Covers: - Error categorization table (generated/@generated vs hand-written) - SearchCustomizations.java fragility patterns - ServiceVersion dedup guards - Breaking change detection - Clear MCP tool handoff (activates after generate-sdk-locally shared skill) ### 4. validate_skill_anchors.py (staleness checker) Extracts code references from skill markdown and verifies they still exist in the codebase. Catches renamed methods, deleted files, cross-language pollution. Tested: 22/22 anchors pass for search skill. ## Key design decisions - Skill name = Maven artifactId (azure-search-documents, not search-documents) - No version numbers in skills -- keep content static - TypeSpec-first customization guardrail - Skills activate after MCP tools have been tried -- no duplication - Based on eval data: 1/3 -> 4/4 correct fix locations with skill ## Related - JS: Azure/azure-sdk-for-js#37484 - Python: Azure/azure-sdk-for-python#45972 - .NET: Azure/azure-sdk-for-net#57580 - Gist: https://gist.github.com/samvaity/4981de850ce51a29fdeb7a7d063ebddc Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

@generated

Adds the infrastructure for service teams to create, validate, and maintain package-specific Copilot skills -- the tribal knowledge that helps AI agents work correctly on their SDK packages. ## What's included ### 1. find-package-skill (discovery registry) Routes agents to package-specific skills before modifying any SDK package. Matches the pattern from JS, Python, and .NET repos. ### 2. create-package-skill (bootstrap wizard) Interactive wizard that walks service teams through creating a skill: - Phase 0: Scan package (detect architecture, customizations, key files) - Phase 1: Scaffold SKILL.md (common pitfalls, error categorization, patterns) - Phase 2: Generate references (architecture.md, customizations.md) - Phase 3: Validate (vally lint) - Phase 4: Register in find-package-skill table ### 3. azure-search-documents (first package skill) Created using the wizard as a dogfood. Covers: - Error categorization table (generated/@generated vs hand-written) - SearchCustomizations.java fragility patterns - ServiceVersion dedup guards - Breaking change detection - Clear MCP tool handoff (activates after generate-sdk-locally shared skill) ## Key design decisions - Skill name = Maven artifactId (azure-search-documents) - No version numbers in skills -- keep content static - TypeSpec-first customization guardrail - Skills activate after MCP tools have been tried -- no duplication - Based on eval data: 1/3 -> 4/4 correct fix locations with skill ## Related - JS: Azure/azure-sdk-for-js#37484 - Python: Azure/azure-sdk-for-python#45972 - .NET: Azure/azure-sdk-for-net#57580 Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

@generated

Adds the infrastructure for service teams to create, validate, and maintain package-specific Copilot skills -- the tribal knowledge that helps AI agents work correctly on their SDK packages. ## What's included ### 1. find-package-skill (discovery registry) Routes agents to package-specific skills before modifying any SDK package. Matches the pattern from JS, Python, and .NET repos. ### 2. create-package-skill (bootstrap wizard) Interactive wizard that walks service teams through creating a skill: - Phase 0: Scan package (detect architecture, customizations, key files) - Phase 1: Scaffold SKILL.md (common pitfalls, error categorization, patterns) - Phase 2: Generate references (architecture.md, customizations.md) - Phase 3: Validate (vally lint) - Phase 4: Register in find-package-skill table ### 3. azure-search-documents (first package skill) Created using the wizard as a dogfood. Covers: - Error categorization table (generated/@generated vs hand-written) - SearchCustomizations.java fragility patterns - ServiceVersion dedup guards - Breaking change detection - Clear MCP tool handoff (activates after generate-sdk-locally shared skill) ## Key design decisions - Skill name = Maven artifactId (azure-search-documents) - No version numbers in skills -- keep content static - TypeSpec-first customization guardrail - Skills activate after MCP tools have been tried -- no duplication - Based on eval data: 1/3 -> 4/4 correct fix locations with skill ## Related - JS: Azure/azure-sdk-for-js#37484 - Python: Azure/azure-sdk-for-python#45972 - .NET: Azure/azure-sdk-for-net#57580 Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

@generated

Adds the infrastructure for service teams to create, validate, and maintain package-specific Copilot skills -- the tribal knowledge that helps AI agents work correctly on their SDK packages. ## What's included ### 1. find-package-skill (discovery registry) Routes agents to package-specific skills before modifying any SDK package. Matches the pattern from JS, Python, and .NET repos. ### 2. create-package-skill (bootstrap wizard) Interactive wizard that walks service teams through creating a skill: - Phase 0: Scan package (detect architecture, customizations, key files) - Phase 1: Scaffold SKILL.md (common pitfalls, error categorization, patterns) - Phase 2: Generate references (architecture.md, customizations.md) - Phase 3: Validate (vally lint) - Phase 4: Register in find-package-skill table ### 3. azure-search-documents (first package skill) Created using the wizard as a dogfood. Covers: - Error categorization table (generated/@generated vs hand-written) - SearchCustomizations.java fragility patterns - ServiceVersion dedup guards - Breaking change detection - Clear MCP tool handoff (activates after generate-sdk-locally shared skill) ## Key design decisions - Skill name = Maven artifactId (azure-search-documents) - No version numbers in skills -- keep content static - TypeSpec-first customization guardrail - Skills activate after MCP tools have been tried -- no duplication - Based on eval data: 1/3 -> 4/4 correct fix locations with skill ## Related - JS: Azure/azure-sdk-for-js#37484 - Python: Azure/azure-sdk-for-python#45972 - .NET: Azure/azure-sdk-for-net#57580 Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

@generated

Adds the infrastructure for service teams to create, validate, and maintain package-specific Copilot skills -- the tribal knowledge that helps AI agents work correctly on their SDK packages. ## What's included ### 1. find-package-skill (discovery registry) Routes agents to package-specific skills before modifying any SDK package. Matches the pattern from JS, Python, and .NET repos. ### 2. create-package-skill (bootstrap wizard) Interactive wizard that walks service teams through creating a skill: - Phase 0: Scan package (detect architecture, customizations, key files) - Phase 1: Scaffold SKILL.md (common pitfalls, error categorization, patterns) - Phase 2: Generate references (architecture.md, customizations.md) - Phase 3: Validate (vally lint) - Phase 4: Register in find-package-skill table ### 3. azure-search-documents (first package skill) Created using the wizard as a dogfood. Covers: - Error categorization table (generated/@generated vs hand-written) - SearchCustomizations.java fragility patterns - ServiceVersion dedup guards - Breaking change detection - Clear MCP tool handoff (activates after generate-sdk-locally shared skill) ## Key design decisions - Skill name = Maven artifactId (azure-search-documents) - No version numbers in skills -- keep content static - TypeSpec-first customization guardrail - Skills activate after MCP tools have been tried -- no duplication - Based on eval data: 1/3 -> 4/4 correct fix locations with skill ## Related - JS: Azure/azure-sdk-for-js#37484 - Python: Azure/azure-sdk-for-python#45972 - .NET: Azure/azure-sdk-for-net#57580 Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

@generated

Adds the infrastructure for service teams to create, validate, and maintain package-specific Copilot skills -- the tribal knowledge that helps AI agents work correctly on their SDK packages. ## What's included ### 1. find-package-skill (discovery registry) Routes agents to package-specific skills before modifying any SDK package. Matches the pattern from JS, Python, and .NET repos. ### 2. create-package-skill (bootstrap wizard) Interactive wizard that walks service teams through creating a skill: - Phase 0: Scan package (detect architecture, customizations, key files) - Phase 1: Scaffold SKILL.md (common pitfalls, error categorization, patterns) - Phase 2: Generate references (architecture.md, customizations.md) - Phase 3: Validate (vally lint) - Phase 4: Register in find-package-skill table ### 3. azure-search-documents (first package skill) Created using the wizard as a dogfood. Covers: - Error categorization table (generated/@generated vs hand-written) - SearchCustomizations.java fragility patterns - ServiceVersion dedup guards - Breaking change detection - Clear MCP tool handoff (activates after generate-sdk-locally shared skill) ## Key design decisions - Skill name = Maven artifactId (azure-search-documents) - No version numbers in skills -- keep content static - TypeSpec-first customization guardrail - Skills activate after MCP tools have been tried -- no duplication - Based on eval data: 1/3 -> 4/4 correct fix locations with skill ## Related - JS: Azure/azure-sdk-for-js#37484 - Python: Azure/azure-sdk-for-python#45972 - .NET: Azure/azure-sdk-for-net#57580 Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

@generated

Adds the infrastructure for service teams to create, validate, and maintain package-specific Copilot skills -- the tribal knowledge that helps AI agents work correctly on their SDK packages. ## What's included ### 1. find-package-skill (discovery registry) Routes agents to package-specific skills before modifying any SDK package. Matches the pattern from JS, Python, and .NET repos. ### 2. create-package-skill (bootstrap wizard) Interactive wizard that walks service teams through creating a skill: - Phase 0: Scan package (detect architecture, customizations, key files) - Phase 1: Scaffold SKILL.md (common pitfalls, error categorization, patterns) - Phase 2: Generate references (architecture.md, customizations.md) - Phase 3: Validate (vally lint) - Phase 4: Register in find-package-skill table ### 3. azure-search-documents (first package skill) Created using the wizard as a dogfood. Covers: - Error categorization table (generated/@generated vs hand-written) - SearchCustomizations.java fragility patterns - ServiceVersion dedup guards - Breaking change detection - Clear MCP tool handoff (activates after generate-sdk-locally shared skill) ## Key design decisions - Skill name = Maven artifactId (azure-search-documents) - No version numbers in skills -- keep content static - TypeSpec-first customization guardrail - Skills activate after MCP tools have been tried -- no duplication - Based on eval data: 1/3 -> 4/4 correct fix locations with skill ## Related - JS: Azure/azure-sdk-for-js#37484 - Python: Azure/azure-sdk-for-python#45972 - .NET: Azure/azure-sdk-for-net#57580 Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

@generated

Adds the infrastructure for service teams to create, validate, and maintain package-specific Copilot skills -- the tribal knowledge that helps AI agents work correctly on their SDK packages. ## What's included ### 1. find-package-skill (discovery registry) Routes agents to package-specific skills before modifying any SDK package. Matches the pattern from JS, Python, and .NET repos. ### 2. create-package-skill (bootstrap wizard) Interactive wizard that walks service teams through creating a skill: - Phase 0: Scan package (detect architecture, customizations, key files) - Phase 1: Scaffold SKILL.md (common pitfalls, error categorization, patterns) - Phase 2: Generate references (architecture.md, customizations.md) - Phase 3: Validate (vally lint) - Phase 4: Register in find-package-skill table ### 3. azure-search-documents (first package skill) Created using the wizard as a dogfood. Covers: - Error categorization table (generated/@generated vs hand-written) - SearchCustomizations.java fragility patterns - ServiceVersion dedup guards - Breaking change detection - Clear MCP tool handoff (activates after generate-sdk-locally shared skill) ## Key design decisions - Skill name = Maven artifactId (azure-search-documents) - No version numbers in skills -- keep content static - TypeSpec-first customization guardrail - Skills activate after MCP tools have been tried -- no duplication - Based on eval data: 1/3 -> 4/4 correct fix locations with skill ## Related - JS: Azure/azure-sdk-for-js#37484 - Python: Azure/azure-sdk-for-python#45972 - .NET: Azure/azure-sdk-for-net#57580 Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

@generated

Adds the infrastructure for service teams to create, validate, and maintain package-specific Copilot skills -- the tribal knowledge that helps AI agents work correctly on their SDK packages. ## What's included ### 1. find-package-skill (discovery registry) Routes agents to package-specific skills before modifying any SDK package. Matches the pattern from JS, Python, and .NET repos. ### 2. create-package-skill (bootstrap wizard) Interactive wizard that walks service teams through creating a skill: - Phase 0: Scan package (detect architecture, customizations, key files) - Phase 1: Scaffold SKILL.md (common pitfalls, error categorization, patterns) - Phase 2: Generate references (architecture.md, customizations.md) - Phase 3: Validate (vally lint) - Phase 4: Register in find-package-skill table ### 3. azure-search-documents (first package skill) Created using the wizard as a dogfood. Covers: - Error categorization table (generated/@generated vs hand-written) - SearchCustomizations.java fragility patterns - ServiceVersion dedup guards - Breaking change detection - Clear MCP tool handoff (activates after generate-sdk-locally shared skill) ## Key design decisions - Skill name = Maven artifactId (azure-search-documents) - No version numbers in skills -- keep content static - TypeSpec-first customization guardrail - Skills activate after MCP tools have been tried -- no duplication - Based on eval data: 1/3 -> 4/4 correct fix locations with skill ## Related - JS: Azure/azure-sdk-for-js#37484 - Python: Azure/azure-sdk-for-python#45972 - .NET: Azure/azure-sdk-for-net#57580 Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

* Add agent dev skill for search * Update .github/skills/find-package-skill/SKILL.md Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> * update * Update sdk/search/azure-search-documents/.github/skills/search-documents/references/customizations.md Co-authored-by: McCoy Patiño <39780829+mccoyp@users.noreply.github.com> * updates * shorten the description * updates * clean up for 12.0.0 --------- Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> Co-authored-by: McCoy Patiño <39780829+mccoyp@users.noreply.github.com>

Add agent dev skill for search

4ac7813

github-actions Bot added the Search label Mar 27, 2026

github-project-automation Bot added this to Azure SDK for Search Mar 27, 2026

github-project-automation Bot moved this to Untriaged in Azure SDK for Search Mar 27, 2026

xiangyan99 marked this pull request as ready for review March 27, 2026 22:27

xiangyan99 requested review from a team, benbp, l0lawrence and laiapat as code owners March 27, 2026 22:27

Copilot AI review requested due to automatic review settings March 27, 2026 22:27

Copilot started reviewing on behalf of xiangyan99 March 27, 2026 22:30 View session

Copilot AI reviewed Mar 27, 2026

View reviewed changes

Comment thread .github/skills/find-package-skill/SKILL.md Outdated

Comment thread sdk/search/azure-search-documents/.github/skills/azure-search-documents/SKILL.md

xiangyan99 and others added 2 commits March 27, 2026 15:57

Update .github/skills/find-package-skill/SKILL.md

d2b8a91

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

update

7cce202

laiapat reviewed Mar 28, 2026

View reviewed changes

Comment thread sdk/search/azure-search-documents/.github/skills/search-documents/SKILL.md Outdated

maorleger mentioned this pull request Mar 30, 2026

[search] Add package-specific skill support with directory-based discovery Azure/azure-sdk-for-net#57580

Merged

samvaity mentioned this pull request Mar 31, 2026

Add find-package-skill registry for package-specific skills Azure/azure-sdk-for-java#48657

Closed

laiapat reviewed Apr 1, 2026

View reviewed changes

xiangyan99 and others added 3 commits April 1, 2026 09:12

Update sdk/search/azure-search-documents/.github/skills/search-docume…

50e87f7

…nts/references/customizations.md Co-authored-by: McCoy Patiño <39780829+mccoyp@users.noreply.github.com>

updates

6d2cc0a

shorten the description

1f129c1

xiangyan99 requested review from laiapat and maorleger April 1, 2026 20:55

xiangyan99 marked this pull request as draft April 1, 2026 22:10

xiangyan99 added 2 commits April 6, 2026 13:51

updates

eafd8ea

clean up for 12.0.0

5f8bfc0

xiangyan99 marked this pull request as ready for review April 8, 2026 22:35

laiapat reviewed Apr 10, 2026

View reviewed changes

Comment thread .github/skills/find-package-skill/SKILL.md

hizixin approved these changes Apr 14, 2026

View reviewed changes

xiangyan99 merged commit 0b97526 into main Apr 14, 2026
23 checks passed

xiangyan99 deleted the search_agent_dev_skill branch April 14, 2026 20:35

github-project-automation Bot moved this from Untriaged to Done in Azure SDK for Search Apr 14, 2026

samvaity mentioned this pull request Apr 16, 2026

Add service-specific skills infrastructure (find-package-skill, create-package-skill wizard, search skill) Azure/azure-sdk-for-java#48833

Merged

2 tasks

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Add agent dev skill for search#45972

Add agent dev skill for search#45972
xiangyan99 merged 8 commits into
mainfrom
search_agent_dev_skill

xiangyan99 commented Mar 27, 2026

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

hizixin commented Apr 14, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

Uh oh!

Conversation

xiangyan99 commented Mar 27, 2026

Description

All SDK Contribution checklist:

General Guidelines and Best Practices

Testing Guidelines

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

hizixin commented Apr 14, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants