Azure · xiangyan99 · May 5, 2026 · Apr 24, 2026 · Apr 24, 2026 · Apr 24, 2026
@@ -0,0 +1,81 @@
+---
+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.'
+---
+
+# Create Package Skill Wizard
+
+> **Minimal beats comprehensive. Human-written beats auto-generated. Scaffold and iterate.**
+
+> Skills encode tribal knowledge — the "I wish someone had told me" stuff that's hard to learn from just reading code. Focus on what's non-obvious and package-specific.
+
+## Interaction Protocols
+
+**CONFIRM Protocol** (asset-producing steps — creating files):
+1. PRESENT the proposed assets and explain why.
+2. ASK exactly one question: "Create now (recommended), edit first, or skip?"
+3. ACT immediately. Create → write files this turn. Edit → refine, re-ask. Skip → move on.
+
+**DECIDE Protocol** (informational/correction steps — no files created):
+1. PRESENT the information or findings.
+2. ASK one specific question appropriate to the decision.
+3. PROCEED based on the answer.
+
+One question at a time. Respect "skip" — never re-ask or defer.
+
+## Wizard Flow
+
+Run each phase in order. **Progressive loading:** Read only the current phase file.
+
+| Phase | Description | Instructions |
+|---|---|---|
+| **Phase 0** | 🧭 Scan Package — detect architecture, customizations, key files | [phases/00-scan-package.md](phases/00-scan-package.md) |
+| **Phase 1** | 📝 Scaffold SKILL.md — generate skill with step-by-step post-regen workflow (Option A) or reference-manual structure (Option B) | [phases/01-scaffold-skill.md](phases/01-scaffold-skill.md) |
+| **Phase 2** | 📚 Generate References — create customizations.md (required) and optionally architecture.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) |
+
+## Guardrails
+
+**Content:**
+- Every line must be non-obvious and package-specific. No generic Python/SDK boilerplate.
+- SKILL.md should be under 500 tokens (soft limit). Move details to references/.
+- References under 1000 tokens each. Split if larger.
+- Never duplicate what's already in `.github/copilot-instructions.md` or shared skills.
+
+**Relationship to existing SDK tools:**
+- Package skills **complement** the Azure SDK MCP tools (`azsdk_package_generate_code`, `azsdk_package_build_code`, `azsdk_customized_code_update`, etc.) — they do NOT replace them.
+- MCP tools handle deterministic operations (generate, build, test). Package skills provide the reasoning context an agent needs to use those tools correctly for a specific package, plus the package-specific verification commands the tools do not know about.
+- Reference the existing tools for the overall workflow (e.g., "Run `tsp-client update` or `azsdk_package_generate_code`"), but DO include the copy-pasteable verification commands an agent needs: import smoke tests (`python -c "from ... import ..."`), `ApiVersion` reconciliation (`grep`, `python -c "import json; ..."`), diff commands (`git diff --name-only | grep ...`), and the package validation invocation (`azsdk_package_run_check with checkType="All"`).
+- Never paraphrase an MCP tool's entire contract. Do include the one-line invocations the agent will run.
+
+**Structure:**
+- Skill directory: `sdk/<service>/<package-name>/.github/skills/<package-name>/`
+- Directory name MUST match `name` field in frontmatter (vally lint enforces this).
+- `name` is the distribution package name, e.g. `azure-search-documents`, `azure-ai-projects`, `azure-mgmt-appconfiguration`.
+- Use semicolons to separate trigger phrases in description (YAML-safe).
+
+**Security:**
+- Never embed secrets or credentials in skill content.
+- Never instruct agents to bypass CI, pylint, mypy, pyright, or other gating tools.
+- Never instruct agents to edit files inside `_generated/` (or any file with the `"Code generated by Microsoft (R) Python Code Generator"` header) — always route through `_patch.py` or sibling hand-written modules.
+
+## Key Principles (from eval data)
+
+Our eval showed that skill **structure** matters more than **volume**:
+
+| Pattern | Impact |
+|---|---|
+| Numbered step-by-step post-regen workflow (Option A) | Agent executes verification top-to-bottom without inventing steps |
+| Copy-pasteable verification commands (import smoke tests, `ApiVersion` reconciliation, git diff of generated operations/models) | Agent actually runs the checks instead of guessing whether customizations still work |
+| "Expose new generated methods through `_patch.py`" step (mixin inheritance / override / polymorphic / create-or-update / list / `__all__` re-export) | Agent wires new generated operations into the public surface instead of leaving them unreachable |
+| "Check `_patch.py` FIRST" directives | Changes agent default from "fix the error location" to "check the customization layer" |
+| Per-file `Depends On` / `Defines` / `After Regeneration, Verify` inventory in `customizations.md` | Agent can pinpoint exactly which generated symbol a breakage maps to |
+| Generated-file detection guidance (directory OR header comment) | Agent correctly identifies auto-generated files under both `_generated/` and inline layouts |
+| Async parity checklist | Agent remembers to mirror sync changes into `aio/` |
+| CHANGELOG / README update step | Prevents "silent" releases that ship new operations without docs |
+
+## References (load on demand)
+
+- [references/skill-template.md](references/skill-template.md) -- SKILL.md template with required sections
+- [references/validation-tools.md](references/validation-tools.md) -- vally lint, CI workflow setup
@@ -0,0 +1,93 @@
+# Phase 0: Scan Package 🧭
+
+> 📍 **Phase 0 — Scan Package** | Detect the package's architecture, customization patterns, and key files.
+
+## Step 1 — Identify the Package
+
+Ask the user: "Which SDK package should I create a skill for?"
+
+The user should provide either:
+- A package name (e.g., `azure-search-documents`, `azure-ai-projects`, `azure-mgmt-appconfiguration`)
+- A path (e.g., `sdk/search/azure-search-documents`, `sdk/ai/azure-ai-projects`)
+
+Resolve to the package root directory. Verify it exists and contains at least one of: `pyproject.toml`, `setup.py`, `tsp-location.yaml`, or a `swagger/README.md` (legacy autorest).
+
+## Step 2 — Scan the Package
+
+Scan the package using the checklist below. Use file_search / grep_search / read_file tools.
+
+### Scan Checklist
+
+1. **Code generation toolchain**:
+   - `tsp-location.yaml` → TypeSpec-generated package. Note the spec directory and commit SHA.
+   - `_metadata.json` → if present, record that `apiVersion` lives here (the skill will reconcile it against the hand-maintained `ApiVersion` enum).
+   - `swagger/README.md` → legacy autorest-generated (mgmt packages typically).
+   - Neither → hand-written package (rare).
+
+2. **Namespace root**: Derive from the package name by replacing `-` with `/` (e.g., `azure-ai-projects` → `<package-path>/azure/ai/projects`). Verify the directory exists.
+
+3. **Generated layout detection**:
+   - If `<namespace-root>/_generated/` exists → **nested layout**. Generated files are confined to `_generated/`; everything else is hand-written/customization.
+   - If `_generated/` is absent → **inline layout** (newer pattern). Generated files are identified by the header comment `"Code generated by Microsoft (R) Python Code Generator"` at the top of each file.
+
+4. **Customizations** (`_patch.py` at each level):
+   - `<namespace-root>/_patch.py` — top-level client customization
+   - `<namespace-root>/models/_patch.py` — model customization
+   - `<namespace-root>/operations/_patch.py` — sync operations customization
+   - `<namespace-root>/aio/_patch.py` — async client customization
+   - `<namespace-root>/aio/operations/_patch.py` — async operations customization
+
+   For each, check if it is **empty** (only copyright header, default docstring, empty `__all__`, empty `patch_sdk()`) or **non-empty** (defines classes/functions, or `__all__` has entries). Record the non-empty patches.
+
+5. **Hand-written utility modules**: Glob all `.py` files under `<namespace-root>` excluding `_generated/`, `__init__.py`, `_version.py`, `_patch.py`. Classify each as generated (has the header) or custom. For custom utility modules, read the first few lines to get a one-line purpose.
+
+6. **Public API surface**: Read each `__init__.py` (top-level, `models/`, `operations/`, `aio/`, `aio/operations/`). Note re-exports from `_patch.py` and any renames/omissions vs `_generated/__init__.py` (when nested layout).
+
+7. **Async parity**: For each non-empty sync customization file, check whether the async counterpart exists under `aio/`. Record `identical`, `equivalent`, `divergent`, `sync-only`, or `async-only`.
+
+8. **Service API versions**: Search for an `ApiVersion` enum or `api_version` constants under `<namespace-root>` (often inside `_patch.py` itself, not `_generated/`). Record the source file path, but do **not** hard-code the list of versions into the skill — point to the source file.
+
+9. **Hand-authored named classes**: Grep for `class .*Buffered|class .*Batching|class .*Sender|class .*Paged|class .*PageIterator` under `<namespace-root>`. These are hand-authored utilities that the skill must name in its Customization Patterns Reference.
+
+10. **Top public symbols (for import smoke tests)**: Read the top-level `__init__.py` and `aio/__init__.py`. Record up to 3–5 most important public names (clients, senders, key models/enums) so Phase 1 can generate accurate `python -c "from <ns> import <X>"` commands.
+
+11. **Tests**: Check `tests/` directory. Look for `conftest.py`, `*test_base*.py`, `assets.json` (recorded tests via Test Proxy), `testpreparer*.py`. Note whether tests are live, recorded, or both.
+
+12. **Documentation surfaces**: Check for `CHANGELOG.md` and `README.md` at the package root. Both are near-universal; the skill's Step 7 (Update Documentation and Samples) will reference them.
+
+13. **Management vs data plane**: If package name starts with `azure-mgmt-` → management-plane rules apply (see copilot-instructions). Otherwise data-plane.
+
+## Step 3 — Present Package Profile
+
+Print a concise summary:
+
+📋 **Package Profile**
+
+| Field | Value |
+|---|---|
+| Package | `<package-name>` (e.g., `azure-ai-projects`) |
+| Path | `sdk/<service>/<package-name>` |
+| Plane | data / mgmt |
+| Generated | TypeSpec (`tsp-location.yaml`) / autorest (`swagger/README.md`) / hand-written |
+| Metadata | `_metadata.json` present: Y/N |
+| Layout | nested (`_generated/`) / inline (header-based) |
+| Non-empty `_patch.py` files | List which levels have customizations (top / models / operations / aio / aio/operations / indexes…) |
+| Custom utility modules | N hand-written `.py` files outside `_patch.py` |
+| Hand-authored named classes | e.g., `SearchIndexingBufferedSender`, `SearchItemPaged` (or `none`) |
+| Top public symbols | List of 3–5 names used for Phase 1 import smoke tests |
+| Public API surface | Notes on re-exports, renames, omissions |
+| Async parity | summary (identical / divergent / sync-only / async-only) |
+| `ApiVersion` enum | source file + present Y/N |
+| Tests | Unit: Y, Live: Y/N, Recorded (assets.json): Y/N |
+| Docs | `CHANGELOG.md`: Y/N, `README.md`: Y/N |
+| Suggested structure | Option A (step-by-step) / Option B (reference manual) |
+
+## Step 4 — DECIDE
+
+Question: "Does this profile look right? Anything to add or correct?"
+
+📍 **Phase 0 complete** | Package scanned | Next: Phase 1
+
+---
+## → Next: Phase 1 — Scaffold SKILL.md
+Read [01-scaffold-skill.md](01-scaffold-skill.md) and begin immediately.