new-control-api

Instructions for adding new public APIs (properties, methods, events, delegates) to existing WinForms controls or components. Covers API issue tracking, PublicAPI file maintenance, property/event conventions, CodeDOM serialization, design-time attributes, and XML documentation.

Quality

83%

Does it follow best practices?

Run evals on this skill

Adds up to 20 points to the overall score

View guide

Securityby

Passed

No findings from the security scan

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 body of repo-specific rules with strong validation checkpoints, explicit error-recovery guidance, and a closing checklist — essentially everything needed to execute is concrete. Its weakness is that all reference-grade material is packed into the single SKILL.md with no progressive disclosure into bundled reference files.

Suggestions

Move the catalogue-style material — the PublicAPI entry-format examples (2.3), the design-time attribute and SR.resx key tables, and the XML-doc formatting rules — into a references/ file, keeping SKILL.md as a concise overview with well-signaled one-level-deep links.

Trim illustrative examples that duplicate a rule already stated, e.g. replace the full CornerRadius implementation in 7.3 with a short snippet showing an un-guarded member.

Move the final pre-submit checklist (Section 8) earlier or link to it from the top "Golden rule" callout so the validation sequence is visible before the detailed rules.

Dimension	Reasoning	Score
Conciseness	Nearly all content is repo-specific knowledge Claude does not have (PropertyStore rationale, Roslyn PublicAPI format, RS0016/CI behavior, WFO5xxx diagnostics) with no generic-concept padding, but a few passages could be tightened — e.g. the full CornerRadius property implementation in 7.3 exists mainly to illustrate "no version guards". Efficient with minor over-explanation, so 4 rather than 5, and clearly above the 3 anchor.	4 / 5
Actionability	The body gives fully executable, copy-paste-ready guidance: exact file paths ("src\\System.Windows.Forms\\PublicAPI.Unshipped.txt"), complete code patterns for PropertyStore properties, ShouldSerialize/Reset, event add/remove accessors, XML doc examples, and concrete commands ("build.cmd", "ArgumentNullException.ThrowIfNull"). This matches the anchor for fully executable, copy-paste-ready coverage of common cases.	5 / 5
Workflow Clarity	Sections 1–8 follow the real sequence (issue → PublicAPI tracking → conventions → XML docs → stability → checklist) with explicit validation checkpoints and feedback loops: "If any information is missing, stop and ask the user", "Always re-verify API tracking with build.cmd" (with the note that CI errors where a plain dotnet build may not), and a closing checklist plus the API-issue status checklist. This matches the anchor for clear sequencing with explicit validation and error-recovery loops; not 4 because both checkpoints and checklists are present throughout.	5 / 5
Progressive Disclosure	The skill has no references/ scripts/ or assets/ bundle — all reference-grade material (the full PublicAPI entry-format catalogue in 2.3, XML-doc conventions in 6.x, SR.resx key tables in 9.1) is inlined in a single ~630-line file. Numbered sections and internal links provide reasonable structure, but content that would serve better as a separate reference file is inline, which matches the anchor for "some structure but content that should be separate is inline"; not 2 because the file is well-organized and navigable, and not 4 because no detail is offloaded to separate files at all.	3 / 5
	Total	17 / 20 Passed

Description

75%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 specific, well-scoped description that names the domain and enumerates six concrete capability areas with minimal conflict risk. Its main weakness is the absence of any explicit "Use when..." trigger clause, leaving the activation conditions implicit and capping completeness.

Suggestions

Append an explicit trigger clause, e.g. "Use when adding new public or protected members (properties, methods, events, delegates) to an existing WinForms control or component, or when updating PublicAPI files for such a change."

Include a few more natural trigger synonyms users would actually say (e.g. ".NET", "WinForms designer", "API proposal", "api-suggestion") to strengthen trigger-term coverage.

Briefly state the boundary against the coding-standards skill (new members on existing controls vs. new controls or general standards) in the description itself to reduce mis-triggering.

Dimension	Reasoning	Score
Specificity	The description enumerates concrete capability areas — "API issue tracking, PublicAPI file maintenance, property/event conventions, CodeDOM serialization, design-time attributes, and XML documentation" — plus explicit member types (properties, methods, events, delegates), which matches the anchor for multiple specific concrete actions with comprehensive coverage; not 4 because there are no meaningful coverage gaps.	5 / 5
Completeness	It has a clear "what" (instructions for adding public APIs to WinForms controls) but no "Use when..." clause or equivalent explicit trigger guidance — usage is only weakly implied by "when adding new public APIs... to existing WinForms controls", which caps completeness at 3; not 4 because the trigger guidance is entirely implicit.	3 / 5
Trigger Term Quality	Good natural keyword coverage ("new public APIs", "WinForms controls", "properties, methods, events, delegates", "CodeDOM"), but a few natural phrasings users would say are missing (e.g. ".NET", "designer", "add an API to a control"), placing it between the 3 and 5 anchors, closer to 4.	4 / 5
Distinctiveness Conflict Risk	"Adding new public APIs... to existing WinForms controls or components" is a clear niche with distinct domain-specific triggers (PublicAPI files, CodeDOM serialization), giving minimal conflict risk with other skills.	5 / 5
	Total	17 / 20 Passed

Validation

93%

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

Validation for skill structure

Criteria	Description	Result
skill_md_line_count	SKILL.md is long (639 lines); consider splitting into references/ and linking	Warning

	Total	15 / 16 Passed

Repository: dotnet/winforms
Path: .github/skills/new-control-api/SKILL.md
Commit: a84cf1f

Reviewed: 9 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.