Core Principles

1. Concise is Key

The context window is a shared resource. Challenge each piece: "Does this justify its token cost?"

For domain/procedural skills: Agents are already capable. Only add what they don't already know.

For SDK/API skills: Users MUST provide SDK package name, documentation URL, or repository reference. The skill cannot be created without this context.

2. Fresh Documentation First

Azure SDKs change constantly. Skills should instruct agents to verify documentation:

## Before Implementation

Search `microsoft-docs` MCP for current API patterns:

- Query: "[SDK name] [operation] python"
- Verify: Parameters match your installed SDK version

3. Degrees of Freedom

Match specificity to implementation constraints. High freedom when approaches vary; low freedom when precise execution is required:

Freedom	When	Example
High	Multiple valid approaches	Text guidelines
Medium	Preferred pattern with variation	Pseudocode
Low	Must be exact	Specific scripts

4. Progressive Disclosure

Skills load in three levels:

1. Metadata (~100 words) — Always in context
2. SKILL.md body (<5k words) — When skill triggers
3. References (unlimited) — As needed

Keep SKILL.md under 500 lines. Split into reference files when approaching this limit.