maintaining-binary-log-compatibility

Guides changes to MSBuild binary log infrastructure. Consult when modifying BinaryLogger or BinaryLogReplayEventSource, adding new BuildEventArgs types, changing event serialization/deserialization, modifying ProjectImportsCollector, adjusting message importance levels, or making changes that affect .binlog content. Also applies when verifying that behavioral changes are properly reflected in binary log output.

Quality

93%

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

87%

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

A dense, actionable, well-structured single-file skill that assumes competence and points to exactly one deeper resource. Its only meaningful gap is the missing inline validation checkpoint in the serialization-change workflow, which the checklist compensates for but does not satisfy inline.

Suggestions

Add an explicit validation checkpoint inside the 'Adding New Build Event Types' sequence (e.g. 'Run the round-trip test; only proceed if events reconstruct correctly') so the fragile serialization workflow has an inline validate→fix→retry loop rather than relying on the checklist.

Make the backward-compatible field-addition code pattern more copy-paste ready by showing where newFieldVersion is defined (the binlog version constant) rather than leaving it as a placeholder.

Link the 'Testing Binlog Changes' section explicitly into the event-type workflow so verification is sequenced, not appended.

Dimension	Reasoning	Score
Conciseness	Lean, assumes Claude's competence — it does not explain what MSBuild or a binlog is, and the architecture diagram, file paths, and tables earn their tokens; it stays clear of the level-2 'mostly efficient but includes some unnecessary explanation' anchor save a single brief framing line.	3 / 3
Actionability	Provides concrete source-file paths, an executable C# backward-compatibility pattern, real env vars/switches, named event types, and a programmatic test hook via BinaryLogReplayEventSource — matching the fully-executable anchor rather than the pseudocode level-2 anchor.	3 / 3
Workflow Clarity	The 'Adding New Build Event Types' section gives a clear numbered 5-step sequence, but this fragile serialization-format workflow lacks an inline validate→fix→retry checkpoint, so per the destructive/batch-operations guideline it is capped at 2; it is above level 1 because the sequence is explicit.	2 / 3
Progressive Disclosure	A single well-organized file with clearly-signaled, one-level-deep external reference to Binary-Log.md and no nested/deep references, meeting the simple-skill top anchor; it avoids the inline-bloat and multi-level-reference anchors at 1–2.	3 / 3
	Total	11 / 12 Passed

Description

100%

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 concrete actions and explicit use-when triggers in third person, with strong natural-keyword coverage and low conflict risk. It hits the top anchor on every dimension with no verbosity or over-claiming.

Dimension	Reasoning	Score
Specificity	Lists multiple specific concrete actions — modifying BinaryLogger/BinaryLogReplayEventSource, adding BuildEventArgs types, changing serialization/deserialization, modifying ProjectImportsCollector, and adjusting importance levels — matching the 'lists multiple specific concrete actions' anchor; it is not the level-2 anchor because coverage is comprehensive rather than partial.	3 / 3
Completeness	Explicitly answers what ('Guides changes to MSBuild binary log infrastructure') and when ('Consult when modifying...', 'Also applies when verifying...'), satisfying the explicit-trigger anchor and avoiding the missing-'when' cap at 2.	3 / 3
Trigger Term Quality	Includes natural terms an MSBuild contributor would actually say — 'binary log', '.binlog', 'BinaryLogger', 'event serialization', 'message importance levels' — giving good coverage rather than the sparse level-2 set.	3 / 3
Distinctiveness Conflict Risk	The narrow MSBuild binary-log niche and distinct technical triggers make it unlikely to fire for unrelated skills; it is far more specific than the overlapping level-2 'Works with document files' style anchor.	3 / 3
	Total	12 / 12 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
frontmatter_unknown_keys	Unknown frontmatter key(s) found; consider removing or moving to metadata	Warning
relative_links	Relative link issues: 1 suspicious	Warning

	Total	14 / 16 Passed

Repository: dotnet/msbuild
Path: .github/skills/maintaining-binary-log-compatibility/SKILL.md
Commit: c88db8e

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