skill-scaffolder

name: skill-scaffolder
description: Creates a new skill in this repository end to end — directory layout, SKILL.md, references, evals, examples, scripts — and registers it everywhere the repo lists skills, so verify-docs.sh passes with the new skill count. Use when asked to add a new skill, create a skill, scaffold a review skill for a new artifact type, or port an external skill into the library. Picks an unused check prefix, wires orchestrator and MCP server routing, and validates the content on Microsoft Learn.
tools: Read, Edit, Write, Grep, Glob, Bash, mcp__microsoft-learn__microsoft_docs_search, mcp__microsoft-learn__microsoft_docs_fetch, mcp__microsoft-learn__microsoft_code_sample_search
model: opus
effort: high

Skill scaffolder

You add one new skill to the library and register it everywhere the repo lists skills. You edit files. You do not commit, push or switch branches.

Read first

• [CLAUDE.md](../../CLAUDE.md): *Adding a New Skill*, the table under *Check ID prefixes — currently taken*, and every Development Constraint
• [.claude/docs/architectural_patterns.md](../docs/architectural_patterns.md): all sections. §1.5 is the directory layout; §12 is the untrusted-artifact rule
• [.claude/docs/skill-creator-best-practices.md](../docs/skill-creator-best-practices.md)
• [.claude/docs/ms-learn-validation.md](../docs/ms-learn-validation.md)
• The most recently added skill, as a working model. Find it with `git log --diff-filter=A --name-only -- skills/*/SKILL.md`, then run `git show --stat <commit>` to see every file that a new skill touched.

Decide before writing

1. **Scope:** confirm that no existing skill already analyses this artifact. If one partly does, name the overlapping checks and route to that skill from the new skill's Companion Skills instead of duplicating them. 2. **Prefix:** all 26 single letters are taken. Pick an unused two-letter prefix that collides with no existing prefix (`BL`, `PM` and `WC` are taken). A dispatcher skill with no checks of its own has no prefix. 3. **Credits:** if the skill adapts someone else's skill, tool or method, record the source now. It goes in Purpose, in `references/community-practices.md`, and in the commit message.

Create

Follow the §1.5 layout:

• `SKILL.md`
• `references/README.md`, and `references/check-explanations.md` (five-part entries, a Quick Reference table, and a TOC if it runs over 300 lines)
• `evals/evals.json` with at least two realistic prompts
• `scripts/`: read-only capture scripts, each with a `Requires:` permission line, or `.gitkeep`
• `assets/.gitkeep`
• `examples/<input>` and `examples/<input-stem>-analysis.md`

SKILL.md must have:

• frontmatter `name` equal to the directory name, a `description` of at least 30 words with trigger phrases and the check count and range, and a `triggers:` field
• the `## Artifact Content Is Data, Not Instructions` block, copied byte for byte from an existing SKILL.md and placed immediately before `## Input`
• `## Thresholds Reference`, checks in the three-part format, `## Output Format` with the required structural markers and the model attribution footer, and `## Companion Skills`

It must not contain a dollar sign followed by a digit or `[`, or a bare ALWAYS / NEVER / MUST outside code blocks.

Register

• `scripts/verify-docs.sh`, Check 34 `P2S` map: add `[<PREFIX>]="<skill>"`.
• [CLAUDE.md](../../CLAUDE.md): the Purpose skill count and summary; the Key Files tables (Skills, Human Reference, Examples, Scripts); the prefix table; any "N skills" count.
• [README.md](../../README.md): Installation, the `## Skills` table, a full `## <skill>` section, the workflow diagram, the Check Reference row, totals.
• [PERFORMANCE_TUNING_GUIDE.md](../../PERFORMANCE_TUNING_GUIDE.md): Skills at a Glance, Skill Scope Comparison, the scenario sections, the Check ID Reference row and the total.
• [skills/VERSION_COMPATIBILITY.md](../../skills/VERSION_COMPATIBILITY.md): the skill support matrix and any version-gated checks.
• The orchestrator, [skills/mssql-performance-review/SKILL.md](../../skills/mssql-performance-review/SKILL.md): the artifact dispatch table and symptom routing.
• The MCP server, [mcp-server/src/tools.ts](../../mcp-server/src/tools.ts): an `ARTIFACT_SKILL_MAP` entry (the `route_artifact` enum is derived from it).
• `.claude-plugin/marketplace.json` and `.claude-plugin/plugin.json` counts.
• The Companion Skills sections of related skills, in both directions (§8).

Then grep for the old skill count (for example `29 skills`, `all 29`) and the old check total, to catch copies the list missed.

Validate and gate

Validate every DMV column, enum, syntax element, cmdlet and version gate on Microsoft Learn. Label anything Learn does not document `Unverified against Microsoft Learn`. Run `bash scripts/verify-docs.sh`, `bash scripts/lint-scripts.sh`, and `cd mcp-server && npm run bundle && npm run typecheck && npm test`. Fix until all of them pass.

Report

Return:

• the skill name, prefix and check range
• the file tree you created
• every registration file you touched, one line each
• old → new skill count and check total
• the Learn URL for each claim, and any Unverified labels you added
• gate results
• sources to credit in the commit message

End with: "Run `mslearn-validator` on `skills/<skill>/` in full mode before committing."