From 78bb70863bc6ee303067f8f6b802c5986dda3771 Mon Sep 17 00:00:00 2001 From: samvaity Date: Thu, 11 Jun 2026 15:47:55 -0700 Subject: [PATCH] [Skills] Directory-based package skill discovery (drop registry table) Switch package-specific skill discovery from a hand-maintained registry table to directory-based discovery, mirroring the approach in azure-sdk-for-js#38913 and azure-sdk-for-net. Changes: - find-package-skill/SKILL.md: replace registry table with directory-based discovery instructions (check for .github/skills/ inside the package dir) - create-package-skill/SKILL.md: update description, Phase 4 label - phases/03-validate.md: update Phase 4 reference wording - phases/04-register.md -> 04-finalize.md: no central table to update, placement is registration Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- .github/skills/create-package-skill/SKILL.md | 4 +- .../phases/03-validate.md | 6 +-- .../phases/04-finalize.md | 47 +++++++++++++++++++ .../phases/04-register.md | 41 ---------------- .github/skills/find-package-skill/SKILL.md | 34 ++++++++------ 5 files changed, 72 insertions(+), 60 deletions(-) create mode 100644 .github/skills/create-package-skill/phases/04-finalize.md delete mode 100644 .github/skills/create-package-skill/phases/04-register.md diff --git a/.github/skills/create-package-skill/SKILL.md b/.github/skills/create-package-skill/SKILL.md index 151e5f197b8b..82e5d6046f11 100644 --- a/.github/skills/create-package-skill/SKILL.md +++ b/.github/skills/create-package-skill/SKILL.md @@ -1,6 +1,6 @@ --- name: create-package-skill -description: 'Interactive wizard that walks service teams through creating a package-specific skill for their Azure SDK package. Scans the package, detects customization patterns, scaffolds a SKILL.md with references, validates with vally lint, and registers in find-package-skill. WHEN: create package skill; add service skill; bootstrap skill for package; new package skill; skill for my SDK package; write skill for search; write skill for cosmos.' +description: 'Interactive wizard that walks service teams through creating a package-specific skill for their Azure SDK package. Scans the package, detects customization patterns, scaffolds a SKILL.md with references, and validates with vally lint. The skill is placed inside the package''s .github/skills/ directory so find-package-skill discovers it automatically. WHEN: create package skill; add service skill; bootstrap skill for package; new package skill; skill for my SDK package; write skill for search; write skill for cosmos.' --- # Create Package Skill Wizard @@ -33,7 +33,7 @@ Run each phase in order. **Progressive loading:** Read only the current phase fi | **Phase 1** | 📝 Scaffold SKILL.md — generate skill with common pitfalls, architecture, workflow | [phases/01-scaffold-skill.md](phases/01-scaffold-skill.md) | | **Phase 2** | 📚 Generate References — create architecture.md and customizations.md | [phases/02-generate-references.md](phases/02-generate-references.md) | | **Phase 3** | Validate -- run vally lint | [phases/03-validate.md](phases/03-validate.md) | -| **Phase 4** | 📋 Register — add to find-package-skill table | [phases/04-register.md](phases/04-register.md) | +| **Phase 4** | 📋 Finalize — confirm discoverable location, summarize | [phases/04-finalize.md](phases/04-finalize.md) | ## Guardrails diff --git a/.github/skills/create-package-skill/phases/03-validate.md b/.github/skills/create-package-skill/phases/03-validate.md index 82367fade642..e9fff332043f 100644 --- a/.github/skills/create-package-skill/phases/03-validate.md +++ b/.github/skills/create-package-skill/phases/03-validate.md @@ -34,7 +34,7 @@ If over budget, split content into additional reference files. ## Step 3 — DECIDE Present validation results. If all pass: -Question: "Validation passed. Proceed to register the skill?" +Question: "Validation passed. Proceed to finalize the skill?" If failures exist, present them and ask: Question: "These issues need fixing. Fix now, or skip validation?" @@ -42,5 +42,5 @@ Question: "These issues need fixing. Fix now, or skip validation?" 📍 **Phase 3 complete** | Validation: pass/fail | Next: Phase 4 --- -## → Next: Phase 4 — Register -Read [04-register.md](04-register.md) and begin immediately. +## → Next: Phase 4 — Finalize +Read [04-finalize.md](04-finalize.md) and begin immediately. diff --git a/.github/skills/create-package-skill/phases/04-finalize.md b/.github/skills/create-package-skill/phases/04-finalize.md new file mode 100644 index 000000000000..9167fe1d6229 --- /dev/null +++ b/.github/skills/create-package-skill/phases/04-finalize.md @@ -0,0 +1,47 @@ +# Phase 4: Finalize 📋 + +> 📍 **Phase 4 — Finalize** | Confirm the skill is in its discoverable location and summarize. + +## Step 1 — Confirm discoverable location + +Package skills are discovered automatically by `find-package-skill`, which looks +for a `.github/skills/` directory **inside the package directory**. There is no +central registry to update — placement *is* registration. + +Verify the skill lives at: + +``` +sdk///.github/skills//SKILL.md +``` + +If it's there, it will be discovered for that package. No further wiring needed. + +## Step 2 — Summary + +Print a summary of everything created: + +📋 **Package Skill Created** + +| Item | Path | Status | +|---|---|---| +| SKILL.md | `sdk///.github/skills//SKILL.md` | Created | +| architecture.md | `...references/architecture.md` | Created/Skipped | +| customizations.md | `...references/customizations.md` | Created/Skipped | +| find-package-skill | discovers automatically via package `.github/skills/` | No action | +| vally lint | 3/3 checks | Passed | + +**Next steps for the service team:** +1. Fill in any `` sections with domain-specific knowledge +2. Test the skill by asking an agent to regenerate your package +3. Iterate: agent gets something wrong -> update skill -> test again +4. Submit a PR + +**Maintaining your skill:** +- When your package's customizations change, update the skill +- Keep content static -- no version numbers or release-specific info + +## Step 3 — CONFIRM + +Question: "The skill is in place and will be discovered automatically. Anything else to adjust?" + +📍 **Phase 4 complete** | Skill in place and discoverable | Wizard done 🎉 diff --git a/.github/skills/create-package-skill/phases/04-register.md b/.github/skills/create-package-skill/phases/04-register.md deleted file mode 100644 index 485ac8dce234..000000000000 --- a/.github/skills/create-package-skill/phases/04-register.md +++ /dev/null @@ -1,41 +0,0 @@ -# Phase 4: Register 📋 - -> 📍 **Phase 4 — Register** | Add the skill to the find-package-skill discovery table. - -## Step 1 — Update find-package-skill - -Add a row to `.github/skills/find-package-skill/SKILL.md` in the **Package Skills** table: - -```markdown -| `` | `sdk///.github/skills//SKILL.md` | -``` - -## Step 2 — Summary - -Print a summary of everything created: - -📋 **Package Skill Created** - -| Item | Path | Status | -|---|---|---| -| SKILL.md | `sdk///.github/skills//SKILL.md` | Created | -| architecture.md | `...references/architecture.md` | Created/Skipped | -| customizations.md | `...references/customizations.md` | Created/Skipped | -| find-package-skill | `.github/skills/find-package-skill/SKILL.md` | Updated | -| vally lint | 3/3 checks | Passed | - -**Next steps for the service team:** -1. Fill in any `` sections with domain-specific knowledge -2. Test the skill by asking an agent to regenerate your package -3. Iterate: agent gets something wrong -> update skill -> test again -4. Submit a PR - -**Maintaining your skill:** -- When your package's customizations change, update the skill -- Keep content static -- no version numbers or release-specific info - -## Step 3 — CONFIRM - -Question: "Register the skill in find-package-skill now (recommended), or skip?" - -📍 **Phase 4 complete** | Skill registered | Wizard done 🎉 diff --git a/.github/skills/find-package-skill/SKILL.md b/.github/skills/find-package-skill/SKILL.md index 0306b1b7be5b..5a4293e40484 100644 --- a/.github/skills/find-package-skill/SKILL.md +++ b/.github/skills/find-package-skill/SKILL.md @@ -1,25 +1,31 @@ --- 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.' +description: '**UTILITY SKILL** — Must be consulted before making any changes to packages under sdk/. Discovers and loads 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. +Some SDK packages in this monorepo have **package-specific skills** — tribal +knowledge (architecture, data flows, type mappings, pitfalls) that prevents +common mistakes. Before modifying any SDK package, check whether a skill exists +for it using the steps below. -Always check this registry before modifying any SDK package — even if you think -you already know the package well. +## How to Discover Package Skills -## How to Use +1. **Determine the package directory.** If you already know the file path you're + modifying, extract the package directory from it (e.g., a file at + `sdk/search/azure-search-documents/src/main/java/com/azure/search/documents/SearchClient.java` + belongs to the package at `sdk/search/azure-search-documents/`). If you only + have a package name, search for a matching directory under `sdk/` (package + directories are named after the Maven artifactId, e.g., + `com.azure:azure-search-documents` → `sdk/search/azure-search-documents/`). -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. +2. **Check for a `.github/skills/` directory** inside the package directory. For + example, check whether `sdk/search/azure-search-documents/.github/skills/` exists. -## Package Skills +3. **If it exists**, read every `SKILL.md` found under that directory. If a + `references/` subdirectory exists next to a `SKILL.md`, read all files in it + too for additional context. -| Package | Path | -| -------------------------- | ------------------------------------------------------------------------------------------------- | -| `azure-search-documents` | `sdk/search/azure-search-documents/.github/skills/azure-search-documents/SKILL.md` | +4. **If no `.github/skills/` directory exists** for the package, no + package-specific skill has been created yet — proceed normally.