azure/azure-sdk-for-java/create-package-skill

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.

Guardrails

Content:

• Every line must be non-obvious and package-specific. No generic Java/SDK patterns.
• 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, etc.) and the generate-sdk-locally shared skill — 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.
• Never redefine how generation, building, or testing works — reference the existing tools instead (e.g., "Run tsp-client update", not custom generation steps).
• If a workflow step is already handled by an MCP tool or shared skill, just reference it — don't re-document it.

Structure:

• Skill directory: sdk/<service>/<package>/.github/skills/<skill-name>/
• Directory name MUST match name field in frontmatter (vally lint enforces this).
• 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, linters, or checkstyle rules.
• Never instruct agents to edit generated files directly — always route through customizations.

Key Principles (from eval data)

Our eval showed that skill structure matters more than volume:

References (load on demand)

• references/skill-template.md -- SKILL.md template with required sections
• references/validation-tools.md -- vally lint, CI workflow setup