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):
- PRESENT the proposed assets and explain why.
- ASK exactly one question: "Create now (recommended), edit first, or skip?"
- ACT immediately. Create → write files this turn. Edit → refine, re-ask. Skip → move on.
DECIDE Protocol (informational/correction steps — no files created):
- PRESENT the information or findings.
- ASK one specific question appropriate to the decision.
- 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 |
| 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 |
| Phase 2 |
📚 Generate References — create customizations.md (required) and optionally architecture.md |
phases/02-generate-references.md |
| Phase 3 |
Validate -- run vally lint |
phases/03-validate.md |
| Phase 4 |
📋 Finalize — confirm discoverable location, summarize |
phases/04-finalize.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 -- SKILL.md template with required sections
- references/validation-tools.md -- vally lint, CI workflow setup
1---2name: create-package-skill3description: '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.'4metadata:5 source: https://skillmd.com/skills/azure-azure-sdk-for-python/create-package-skill6---78# Create Package Skill Wizard910> **Minimal beats comprehensive. Human-written beats auto-generated. Scaffold and iterate.**1112> 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.1314## Interaction Protocols1516**CONFIRM Protocol** (asset-producing steps — creating files):171. PRESENT the proposed assets and explain why.182. ASK exactly one question: "Create now (recommended), edit first, or skip?"193. ACT immediately. Create → write files this turn. Edit → refine, re-ask. Skip → move on.2021**DECIDE Protocol** (informational/correction steps — no files created):221. PRESENT the information or findings.232. ASK one specific question appropriate to the decision.243. PROCEED based on the answer.2526One question at a time. Respect "skip" — never re-ask or defer.2728## Wizard Flow2930Run each phase in order. **Progressive loading:** Read only the current phase file.3132| Phase | Description | Instructions |33|---|---|---|34| **Phase 0** | 🧭 Scan Package — detect architecture, customizations, key files | [phases/00-scan-package.md](phases/00-scan-package.md) |35| **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) |36| **Phase 2** | 📚 Generate References — create customizations.md (required) and optionally architecture.md | [phases/02-generate-references.md](phases/02-generate-references.md) |37| **Phase 3** | Validate -- run vally lint | [phases/03-validate.md](phases/03-validate.md) |38| **Phase 4** | 📋 Finalize — confirm discoverable location, summarize | [phases/04-finalize.md](phases/04-finalize.md) |3940## Guardrails4142**Content:**43- Every line must be non-obvious and package-specific. No generic Python/SDK boilerplate.44- SKILL.md should be under 500 tokens (soft limit). Move details to references/.45- References under 1000 tokens each. Split if larger.46- Never duplicate what's already in `.github/copilot-instructions.md` or shared skills.4748**Relationship to existing SDK tools:**49- 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.50- 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.51- 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"`).52- Never paraphrase an MCP tool's entire contract. Do include the one-line invocations the agent will run.5354**Structure:**55- Skill directory: `sdk/<service>/<package-name>/.github/skills/<package-name>/`56- Directory name MUST match `name` field in frontmatter (vally lint enforces this).57- `name` is the distribution package name, e.g. `azure-search-documents`, `azure-ai-projects`, `azure-mgmt-appconfiguration`.58- Use semicolons to separate trigger phrases in description (YAML-safe).5960**Security:**61- Never embed secrets or credentials in skill content.62- Never instruct agents to bypass CI, pylint, mypy, pyright, or other gating tools.63- 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.6465## Key Principles (from eval data)6667Our eval showed that skill **structure** matters more than **volume**:6869| Pattern | Impact |70|---|---|71| Numbered step-by-step post-regen workflow (Option A) | Agent executes verification top-to-bottom without inventing steps |72| 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 |73| "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 |74| "Check `_patch.py` FIRST" directives | Changes agent default from "fix the error location" to "check the customization layer" |75| Per-file `Depends On` / `Defines` / `After Regeneration, Verify` inventory in `customizations.md` | Agent can pinpoint exactly which generated symbol a breakage maps to |76| Generated-file detection guidance (directory OR header comment) | Agent correctly identifies auto-generated files under both `_generated/` and inline layouts |77| Async parity checklist | Agent remembers to mirror sync changes into `aio/` |78| CHANGELOG / README update step | Prevents "silent" releases that ship new operations without docs |7980## References (load on demand)8182- [references/skill-template.md](references/skill-template.md) -- SKILL.md template with required sections83- [references/validation-tools.md](references/validation-tools.md) -- vally lint, CI workflow setup