Name: api-proposal
Rating: 71.2 (1 reviews)
Author: dotnet

api-proposal

Create prototype-backed API proposals for dotnet/runtime. Use when asked to draft an API proposal, write an api-suggestion issue, refine a vague API idea into a complete proposal, or improve a proposal marked api-needs-work. Covers the full pipeline from research through prototyping, ref source generation, and publishing. DO NOT USE FOR bug fixes, code review, performance benchmarking, or internal API changes that don't affect public surface area.

Quality

88%

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

Quality

Content

85%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.

A highly actionable, well-sequenced multi-phase workflow with strong validation checkpoints and concrete executable commands. The main weakness is progressive disclosure: two referenced reference files are missing from the bundle and much of the content lives inline in SKILL.md.

Suggestions

Add the missing reference files (references/proposal-examples.md and references/api-proposal-checklist.md) to the bundle, or remove the references/ pointers from Phase 1 so navigation is not broken.

Move the detailed proposal-structure guidance (Phase 4, sections 1–6) and the adoption-catalog format into a references file, keeping SKILL.md as a concise phase overview that links one level deep.

Trim the 'Common Pitfalls' and Phase 2 cataloging prose to bullet essentials to tighten the token budget.

Dimension	Reasoning	Score
Conciseness	Largely efficient and avoids explaining concepts Claude already knows, but runs ~388 lines with some prose that could be tightened (e.g., the cataloging instructions and 'Common Pitfalls' entries), so minor trimming opportunities remain.	4 / 5
Actionability	Provides copy-paste-ready commands ('dotnet msbuild /t:GenerateReferenceAssemblySource', 'gh pr comment <pr-number> --body-file proposal.md', 'gh issue create --label api-suggestion'), concrete branch naming, specific file paths, and compilable csharp API declaration examples covering the common cases.	5 / 5
Workflow Clarity	The 6 phases are clearly sequenced with explicit validation checkpoints: Phase 2 'Prototype Validation (all steps required)', Phase 3 marked 'BLOCKING' with 'All errors and warnings must be fixed before proceeding', and Phase 6 re-runs full Phase 2 validation and Phase 3 review before proceeding — a proper validate→fix→retry feedback loop.	5 / 5
Progressive Disclosure	Phase headers and navigation are well organized, but the body points to 'references/proposal-examples.md' and 'references/api-proposal-checklist.md' that do not exist in the bundle (no references/ directory), and a large amount of procedural content is inlined in SKILL.md rather than split out.	3 / 5
	Total	17 / 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, third-person description that clearly states what the skill does and when to use it, with explicit trigger phrases and a negative-scope boundary to avoid misfires. The only minor gap is missing synonym/file-extension variants in trigger terms.

Dimension	Reasoning	Score
Specificity	Lists multiple concrete actions — 'Create prototype-backed API proposals', 'draft an API proposal', 'write an api-suggestion issue', 'refine a vague API idea', 'improve a proposal marked api-needs-work' — plus pipeline coverage (research, prototyping, ref source generation, publishing), giving comprehensive coverage of concrete capabilities.	5 / 5
Completeness	Explicitly answers both 'what' ('Create prototype-backed API proposals... Covers the full pipeline from research through prototyping, ref source generation, and publishing') and 'when' ('Use when asked to draft an API proposal, write an api-suggestion issue, refine a vague API idea...') with concrete trigger phrases.	5 / 5
Trigger Term Quality	Includes natural phrases users would actually say ('write an API proposal', 'draft an api-suggestion', 'improve a proposal marked api-needs-work') and the api-suggestion/api-needs-work labels, but lacks synonym variants and file extensions that would push it to comprehensive.	4 / 5
Distinctiveness Conflict Risk	Targets a clear niche (dotnet/runtime API proposals) with distinct triggers and an explicit 'DO NOT USE FOR bug fixes, code review, performance benchmarking, or internal API changes' boundary that minimizes conflict with adjacent skills.	5 / 5
	Total	19 / 20 Passed

Validation

87%

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 — 14 / 16 Passed

Validation for skill structure

Criteria	Description	Result
relative_links	Relative link issues: 2 missing	Warning
referenced_paths_exist	Referenced path issues: 4 missing	Warning

	Total	14 / 16 Passed

Repository: dotnet/runtime
Path: .github/skills/api-proposal/SKILL.md
Commit: b030ed4

Reviewed: 2 days 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.