skill-creator-ms

Skill Creator

Guide for creating skills that extend AI agent capabilities, with emphasis on Azure SDKs and Microsoft Foundry.

Required Context: When creating SDK or API skills, users MUST provide the SDK package name, documentation URL, or repository reference for the skill to be based on.

About Skills

Skills are modular knowledge packages that transform general-purpose agents into specialized experts:

1. Procedural knowledge — Multi-step workflows for specific domains
2. SDK expertise — API patterns, authentication, error handling for Azure services
3. Domain context — Schemas, business logic, company-specific patterns
4. Bundled resources — Scripts, references, templates for complex tasks

---

Core Principles

1. Concise is Key

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

Default assumption: Agents are already capable. Only add what they don't already know.

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 task fragility:

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.

---

Skill Structure

skill-name/
├── SKILL.md (required)
│   ├── YAML frontmatter (name, description)
│   └── Markdown instructions
└── Bundled Resources (optional)
    ├── scripts/      — Executable code
    ├── references/   — Documentation loaded as needed
    └── assets/       — Output resources (templates, images)