create-package-skill

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, 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

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
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