| 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. Use when this capability is needed. |
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.
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:
| Pattern | Impact |
|---|
| "Common Pitfalls" section at the TOP | Agent reads pitfalls before analyzing errors → correct diagnosis |
| "Check X FIRST" directives | Changes agent default from "fix the error location" to "check the customization layer" |
| Error categorization tables | Gives agent a decision framework, not just procedures |
@Generated annotation guidance | Agent distinguishes auto-updated vs hand-written methods in generated files |
References (load on demand)
Source: Azure/azure-sdk-for-java — distributed by TomeVault.
