Name: azure-ps-design-review
Rating: 67.2 (1 reviews)
Author: Azure

azure-ps-design-review

Conversational agent that guides developers through creating complete Azure PowerShell cmdlet design specifications. Walks through an interactive interview covering service release details, contacts, scenarios, cmdlet syntax, parameter sets, piping, test cases, and spec links. Validates against PowerShell design guidelines, pre-populates fields from TypeSpec, and files the design as a GitHub Issue in Azure/azure-powershell-cmdlet-review-pr. USE FOR: 'create PowerShell design', 'PS design review', 'cmdlet design', 'PowerShell cmdlet review', 'submit PS design'. DO NOT USE FOR: SDK generation, TypeSpec authoring, releasing packages.

Quality

80%

Does it follow best practices?

Run evals on this skill

Adds up to 20 points to the overall score

View guide

Securityby

Low

Low-risk findings worth noting

Fix and improve this skill with Tessl

tessl review fix ./.github/skills/azure-ps-design-review/SKILL.md

Quality

Content

67%Weight 40%Scale 1-5

Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.

The content is highly actionable with a well-sequenced workflow and good use of reference files for bulk material. The main weakness is conciseness: several blocks (MCP setup JSON, scratch-file rules) are repeated and could be consolidated.

Suggestions

De-duplicate the MCP setup JSON by stating it once and referencing it from Troubleshooting, and consolidate the repeated 'no multi-line content in chat' rules into a single canonical statement.

Move the large inline design-draft template into a reference file (e.g., references/design-draft-template.md) and link to it, reducing the inline weight of the SKILL.md body.

Standardize reference links (e.g., [design guidelines](references/design-guidelines-summary.md)) consistently so navigation signals are uniform across sections.

Dimension	Reasoning	Score
Conciseness	The body is mostly efficient operational guidance but repeats the MCP-setup JSON (MCP Tools and Troubleshooting) and the 'do not ask multi-line content in chat' rule multiple times, and re-explains the scratch-file convention across several sections — tightening these redundancies would improve token efficiency.	3 / 5
Actionability	It provides concrete MCP tool names, exact ref syntax, real search_code queries, a full copy-paste draft template, and exact issue title/label/telemetry formats — mostly executable guidance with only minor high-level spots like the PUT→New-/Set- derivation.	4 / 5
Workflow Clarity	Six numbered steps are clearly sequenced with a progress checklist, a PR-link-first directive, and an explicit validation gate (Step 4) with a fix-and-revalidate feedback loop before submission; a few intermediate checkpoints remain implicit, keeping it just below a 5.	4 / 5
Progressive Disclosure	It appropriately offloads the bulk guidelines and issue template to two real, one-level-deep reference files with clear signals and a MCP-based fallback for full guidelines, though the large inline draft template and inconsistent link formatting leave minor organization gaps.	4 / 5
	Total	15 / 20 Passed

Description

92%Weight 40%Scale 1-5

Based on the skill's description, can an agent find and select it at the right time? Clear, specific descriptions lead to better discovery.

A strong, specific description that clearly conveys both capability and trigger conditions with an explicit anti-trigger boundary. The only weakness is trigger-term breadth — adding concrete file/repo cues could round out the keywords.

Suggestions

Consider adding a natural concrete cue such as the target repo or 'azure-powershell' alongside the existing trigger phrases to broaden keyword coverage.

Optionally include a short file-type or artifact cue (e.g., 'cmdlet design issue', 'Az module') to mirror the specificity of the highest-anchor trigger examples.

Dimension	Reasoning	Score
Specificity	The description lists multiple concrete actions (interactive interview covering release details, contacts, scenarios, cmdlet syntax, parameter sets, piping, test cases, spec links; validating against guidelines; pre-populating from TypeSpec; filing a GitHub Issue), giving comprehensive coverage.	5 / 5
Completeness	It explicitly answers both 'what' (the full interview-to-issue workflow) and 'when' via an explicit 'USE FOR' clause plus a 'DO NOT USE FOR' boundary, matching the anchor that requires concrete trigger phrases for both.	5 / 5
Trigger Term Quality	It includes natural trigger phrases users would say ('create PowerShell design', 'PS design review', 'cmdlet design', 'PowerShell cmdlet review', 'submit PS design') with synonyms, but lacks analogous concrete file-extension cues that would push it to anchor 5.	4 / 5
Distinctiveness Conflict Risk	It occupies a clear niche (Azure PowerShell cmdlet design review) with an explicit 'DO NOT USE FOR' boundary (SDK generation, TypeSpec authoring, releasing packages), yielding minimal conflict risk.	5 / 5
	Total	19 / 20 Passed

Validation

100%

Warnings & errors only

Checks the skill against the spec for correct structure and formatting. All validation checks must pass before discovery and implementation can be scored.

Validation — 16 / 16 Passed

Validation for skill structure

No warnings or errors.

Repository: Azure/azure-rest-api-specs
Path: .github/skills/azure-ps-design-review/SKILL.md
Commit: 120cdc9

Reviewed: about 23 hours ago

Table of Contents

Discovery Implementation Validation

Is this your skill?

If you maintain this skill, you can claim it as your own. Once claimed, you can manage eval scenarios, bundle related skills, attach documentation or rules, and ensure cross-agent compatibility.