skill-creator

Files (7)

• SKILL.md
• azure-sdk-patterns.md · references/
• output-patterns.md · references/
• workflows.md · references/
• init_skill.py · scripts/
• package_skill.py · scripts/
• quick_validate.py · scripts/

SKILL.md (first lines)

# 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?"

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

```markdown
## 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.

---

## Skill Structure

**Quick reference:**

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

For Azure SDK skills, follow the **Skill Section Order** below. For domain skills, use your judgment to organize logically.

### SKILL.md Essentials

- **Frontmatter**: `name` and `description` (description triggers the skill)
- **Body**: Keep under 500 lines; split large skills into reference files

### Bundled Resources (Optional)

| Type          | When to Include                          | Examples                                                   |
| ------------- | ---------------------------------------- | ---------------------------------------------------------- |
| `scripts/`    | Reused code patterns                     | Auth setup, CLI scripts                                    |
| `references/` | Feature deep-dives and overflow examples | `capabilities.md` index, `non-hero-scenarios.md`, API docs |
| `assets/`     | Output templates                         | Boilerplate code, images                                   |

---

## Creating Azure SDK Skills

When creating skills for Azure SDKs, follow these patterns consistently.

### Token Budget Guidelines (REQUIRED)

Every Azure SDK skill MUST stay within these token limits:

| Section                       | Target           | Absolute Max     |
| ----------------------------- | ---------------- | ---------------- |
| Installation + Env Vars       | 100 tokens       | 150              |
| Authentication & Lifecycle    | 200 tokens       | 300              |
| Core Workflow (1 example)     | 300 tokens       | 400              |
| Feature Tables                | 200 tokens       | 300              |
| Best Practices (6-8 items)    | 200 tokens       | 250              |
| References (reference/ links) | 100 tokens       | 150              |
| **Total SKILL.md**            | **~1100 tokens** | **~1500 tokens** |

**Enforcement**:

- Exceeding max limit → refactor into `/references/` subdirectories
- When approaching 500 lines → move entire sections to reference files
- Annotate with `<!-- Token Count: ~XXXX (target: 1100, max: 1500) -->` immediately below the skill's H1

---

From microsoft/skills, MIT.

More from microsoft/skills