CtrlK
BlogDocsLog inGet started
Tessl Logo

testland/protobuf-versioning-strategy-reference

Pure-reference catalog of protobuf3 versioning and breaking-change rules: field-number reservation (reserve on delete; 1..536870911; 19000-19999 reserved), wire-safe vs wire-incompatible changes (add/remove safe with reservation; changing a field number always breaks), compatible type conversions (int32/uint32/int64/uint64/bool; sint32/sint64; string/bytes for UTF-8; enum/int), oneof + map constraints, and buf's four breaking categories (FILE/PACKAGE/WIRE_JSON/WIRE) with rule IDs. Use when designing a schema change or picking a buf breaking ruleset. This is the catalog of what is breaking and why, not a scanner; to detect changes in CI use buf-cli-lint-breaking-build, for the gRPC status-code vocabulary use grpc-status-code-mapping-reference, and for cross-service contract testing use protobuf-compat-checking.

76

Quality

95%

Does it follow best practices?

Run evals on this skill

Adds up to 20 points to the overall score

View guide

SecuritybySnyk

Passed

No findings from the security scan

Overview
Quality
Evals
Security
Files

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 well-structured, concrete reference catalog with strong progressive disclosure and dense tables. Its only weakness is workflow clarity: as a catalog it offers decision guidance rather than a sequenced, checkpointed process.

Suggestions

Add a short numbered decision workflow for choosing a buf breaking category (e.g. 1. Identify consumer type → 2. Pick FILE/PACKAGE/WIRE_JSON/WIRE → 3. Add to buf.yaml → 4. Run 'buf breaking --against main') with an explicit verify step.

Include a one-line validation checkpoint in the 'Common patterns' removal example, e.g. re-run 'buf breaking --against main' after reserving a field number to confirm no breakage.

Tighten the Overview's conceptual framing so it states the field-number binding rule once without re-quoting the spec verbatim, keeping it reference-focused.

DimensionReasoningScore

Conciseness

Dense, table-driven reference material (field-number ranges, wire-compatibility matrix, buf category table, anti-patterns) with minimal conceptual padding; the brief Overview framing and cited spec quotes earn their place rather than restating general programming knowledge.

3 / 3

Actionability

Provides copy-paste-ready proto snippets (reserved fields), worked diff patterns, a buf.yaml category config, and the concrete CI command 'buf breaking --against ".git#branch=main"', plus an anti-pattern table with explicit fixes.

3 / 3

Workflow Clarity

The 'Choosing the category' section offers deployment-model decision guidance but there is no sequenced multi-step process with validation checkpoints; as a pure reference catalog it lacks an explicit workflow with feedback loops.

2 / 3

Progressive Disclosure

SKILL.md is an overview that keeps core rules inline and defers full rule-ID tables and worked diffs to a clearly signaled, verified one-level-deep reference: [references/buf-breaking-rules.md](references/buf-breaking-rules.md).

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 high-quality reference-skill description: specific, third-person, with an explicit 'Use when' trigger and strong differentiation from sibling skills. Every dimension lands at the top anchor.

DimensionReasoningScore

Specificity

Lists multiple concrete capabilities with specifics: 'field-number reservation (reserve on delete; 1..536870911; 19000-19999 reserved)', 'compatible type conversions (int32/uint32/int64/uint64/bool; sint32/sint64; string/bytes for UTF-8; enum/int)', and 'buf's four breaking categories (FILE/PACKAGE/WIRE_JSON/WIRE) with rule IDs' — far beyond vague domain naming.

3 / 3

Completeness

Clearly answers both: what ('Pure-reference catalog of protobuf3 versioning and breaking-change rules...') and when ('Use when designing a schema change or picking a buf breaking ruleset').

3 / 3

Trigger Term Quality

Explicit trigger phrasing 'Use when designing a schema change or picking a buf breaking ruleset' plus natural domain terms ('protobuf3 versioning', 'breaking-change rules', 'buf breaking ruleset') that a developer needing this skill would actually say.

3 / 3

Distinctiveness Conflict Risk

Explicitly carves a clear niche ('the catalog of what is breaking and why, not a scanner') and redirects adjacent needs to buf-cli-lint-breaking-build, grpc-status-code-mapping-reference, and protobuf-compat-checking, making wrong-skill triggering unlikely.

3 / 3

Total

12

/

12

Passed

Validation

100%

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.

Reviewed

Table of Contents

DiscoveryImplementationValidation