Skill Creator (Microsoft)

tl;dr: the meta-procedure for writing a good SKILL.md in the microsoft/skills style. It’s opinionated and Azure-SDK-shaped: token budgets per section (1,100 target, 1,500 absolute max), a strict section order, mandatory DefaultAzureCredential rules for Python skills, anti-patterns that cause context rot, and a Vally eval gate. The skill itself is the source of truth for every other page in the microsoft/skills bundle — cloud-solution-architect, podcast-generation, and all 39 -py Azure SDK skills were authored against it.

What it actually does

The skill’s stated purpose: “Guide for creating skills that extend AI agent capabilities, with emphasis on Azure SDKs and Microsoft Foundry.” It is both a how-to-author-a-skill guide and a linter for finished skills. The fetched SKILL.md runs ~17 KB (truncated above 16,960 bytes this session) and covers, in order:

1. Core principles — concise-is-key, fresh-docs-first (Azure SDKs change constantly), degrees of freedom (high/medium/low), progressive disclosure (metadata → SKILL.md body → references).
2. Skill structure — SKILL.md (required, <500 lines) plus optional scripts/, references/, assets/ directories.
3. Creating Azure SDK skills — token budget table per section, reference-extraction guide (signals for move → /references/), core workflow discipline (single vs. multiple hero workflows), the required seven-section order.
4. Required Authentication & Lifecycle callout (Python only) — a verbatim callout block that every Python Azure SDK skill must paste under ## Authentication & Lifecycle to make the two DefaultAzureCredential + context-manager rules visible.
5. Authentication patterns for every language — Python, C#, Java, TypeScript, Go, Rust. Each shows the production-safe credential (ManagedIdentityCredential / WorkloadIdentityCredential / AZURE_TOKEN_CREDENTIALS=prod) plus the local-dev shortcut.
6. Anti-patterns (REQUIRED reading before writing) — exhaustive API reference, multiple ways to solve one problem, beginner+intermediate+advanced mixed, restating official docs, verbose explanation when an example suffices.
7. Efficiency validation — section-level token counts, anti-pattern checklist, example-count audit, frontmatter validation, Vally lint + Vally eval (if a spec exists under tests/scenarios/<skill-name>/vally/).
8. Standard verb patterns — create / upsert / get / list / delete / begin (long-running).
9. Language-specific patterns — Python’s ItemPaged + LROPoller, .NET Response<T> + Pageable<T>, Go runtime.Pager / runtime.Poller, Rust cargo add + RequestContent::from.
10. Best-practice templates — required wording for the “Best Practices” section of every generated skill (sync/async separation, context managers, DefaultAzureCredential production guidance, RBAC for Rust).
11. Deprecated/rebranded SDK handling — migration notice at the top, show both legacy and recommended packages, when to update existing vs. create new.
12. Full example skill — a structure-only benchmark Azure SDK skill showing installation, env vars, the auth callout, core workflow, and a references table.

Token budget (REQUIRED)

Every Azure SDK skill MUST stay within these per-section limits, otherwise refactor into /references/:

The skill’s header annotates the measured count: <!-- Token Count: ~1180 (target: 1100, max: 1500) -->.

Reference extraction rules

Move content to /references/ when the signal matches:

Concrete destinations: batch-operations.md, error-handling.md, performance.md, workflows-comparison.md, streaming.md, auth-strategies.md, tools.md, migration.md.

Required section order

For an Azure SDK skill, the section order is non-negotiable:

1. Title — # SDK Name
2. Installation — pip install, npm install, cargo add, etc.
3. Environment Variables — including AZURE_TOKEN_CREDENTIALS when DefaultAzureCredential is in production.
4. Authentication & Lifecycle — Python skills MUST open with the standard callout block, verbatim.
5. Core Workflow — minimal viable example (single hero workflow = one complete example).
6. Feature Tables — 3–5 core methods, not the full API surface.
7. Best Practices — 6–8 numbered items; first two are the sync/async separation rule and the context-manager rule.
8. Reference Links — table linking to /references/*.md.

Install

microsoft/skills is a plugin bundle, not a single-skill npm package. The wizard picks skills; the README documents the manual path:

# Wizard — install the bundle, then choose from the picker
npx skills add microsoft/skills

# Manual — clone the repo, copy the single skill folder
git clone https://github.com/microsoft/skills
cp -r microsoft/skills/.github/skills/skill-creator \
  your-project/.github/skills/

# Multi-host: symlink so .claude/skills/ and .opencode/skills/ see it too
ln -s ../.github/skills .claude/skills
ln -s ../.github/skills .opencode/skills

Targets GitHub Copilot CLI / VS Code Copilot out of the box (the README’s directory is .github/skills/). For Claude Code, also symlink .claude/skills/ so the host picks it up.

Gotchas

• Refuses to proceed without an SDK reference. The skill’s REQUIRED step 1 says the user must supply SDK package name, Microsoft Learn docs URL, or repository. If they don’t, the agent should ask. This is not a generic “write me a skill” prompt.
• 1,500-token absolute max. Exceeding it is treated as a defect, not a feature — refactor into /references/, do not split into “Part 1 / Part 2” SKILL.md files.
• The auth callout is verbatim. The Python skill body must paste the two-rule DefaultAzureCredential block without paraphrasing; consistency across skills is the point. Editing the callout breaks the family contract.
• Anti-pattern #2 is the silent killer. Showing “five ways to paginate” inside SKILL.md is the most common violation. Use ItemPaged for the happy path; link alternatives in /references/.
• Don’t restate the official docs. The skill says: show the code, then link microsoft-docs MCP — don’t paste the parameter table from Microsoft Learn.
• Vally eval needs COPILOT_TOKEN. Without it, lint-only is acceptable per the workflow. With it, eval must pass.
• sandbox_test untested. We read the SKILL.md and README; we did not author a skill end-to-end against the seven-section template in the sandbox.

References (per SKILL.md)

• references/azure-sdk-patterns.md — language-specific patterns (Python ItemPaged, .NET Response<T>, Rust cargo add + RequestContent::from).
• .github/skills/<skill-name>/SKILL.md — example finished skills to mirror structure.
• tests/README.md — adding acceptance criteria and scenarios for new skills.
• Microsoft Learn (via microsoft-docs MCP) — the source the skill tells you to consult instead of duplicating.

Related

• Cloud Solution Architect (microsoft/skills) — same Microsoft Core bundle, written against this meta-skill.
• Podcast Generation (microsoft/skills) — same Microsoft Core bundle, the kind of audio skill this meta-skill helps you author.
• MCP Builder (microsoft/skills) — same Microsoft Core bundle, MCP-server side of the same authoring discipline.
• Refactoring UI Audit — different vendor, the operator-authored skill this catalog uses as the gold-quality bar; this microsoft skill is the meta-procedure for matching that bar.