versioning-policy

Semver versioning rules for Squad SDK and CLI — prevents prerelease version incidents

Quality

64%

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

Fix and improve this skill with Tessl

tessl review fix ./.squad/skills/versioning-policy/SKILL.md

Quality

Content

72%

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

The content is a well-structured, actionable versioning policy with concrete examples, named enforcement mechanisms, and clear ownership rules. Its main weaknesses are redundant incident retelling and the lack of an explicit step-by-step validation workflow for version-bump operations.

Suggestions

Collapse the duplicate PR #640 narrative: keep the full incident in §8 and have §4 reference it briefly rather than retelling it.

Add a short numbered 'When bumping a version' workflow with an explicit validate→fix→retry loop (e.g., bump three package.json files → run CI guard → fix and re-run if it blocks).

Trim the general semver-spec explanation in §4 to the essential one-line footgun statement, trusting Claude's existing semver knowledge.

Dimension	Reasoning	Score
Conciseness	The body is mostly efficient (tables, a lifecycle diagram, a Quick Reference), but it retells the PR #640 incident in both §4 and §8 and explains semver-spec prerelease matching that Claude largely already knows, so it could be tightened.	2 / 3
Actionability	Provides concrete, specific, actionable guidance: exact valid/invalid version examples, explicit decision rules ('reject the PR', 'revert to the clean release version'), the named CI gate 'prerelease-version-guard', the 'skip-version-check' label, and a clear ownership table.	3 / 3
Workflow Clarity	The lifecycle diagram in §6 sequences the phases and the CI gate in §7 acts as a checkpoint, but there is no explicit numbered validate→fix→retry workflow for an agent bumping or cleaning a version, leaving checkpoints partly implicit.	2 / 3
Progressive Disclosure	A self-contained single-file skill with no bundle directories; content is well-organized into clearly headed sections plus a Quick Reference table for easy navigation, with no nested multi-level references.	3 / 3
	Total	10 / 12 Passed

Description

57%

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

The description is specific and distinctively scoped to the Squad SDK/CLI versioning niche, but it functions as a policy label rather than a usage-triggered capability statement. Adding an explicit 'Use when...' clause and a few more concrete actions would lift it to the top level.

Suggestions

Append an explicit trigger clause, e.g. 'Use when bumping versions, opening release PRs, or seeing prerelease (-build.N) versions in package.json diffs.'

Expand the action list beyond a single preventive outcome, e.g. 'enforces SDK/CLI version sync, rejects prerelease PRs, guides version bumps'.

Add common natural terms like 'version bump', 'release', and 'npm publish' to improve trigger coverage.

Dimension	Reasoning	Score
Specificity	Names the domain ('Semver versioning rules for Squad SDK and CLI') and a preventive outcome ('prevents prerelease version incidents'), but does not list multiple concrete actions; it is a policy statement rather than a multi-action capability list.	2 / 3
Completeness	Clearly answers what the skill does, but provides no 'Use when...' clause or equivalent explicit trigger guidance for when Claude should invoke it, which caps completeness at 2.	2 / 3
Trigger Term Quality	Includes relevant terms ('semver', 'versioning', 'prerelease', 'Squad SDK and CLI') a user might say, but omits common variations such as 'version bump', 'release', or 'npm publish' that would broaden natural triggering.	2 / 3
Distinctiveness Conflict Risk	Tied to specific named packages (@bradygaster/squad-sdk and squad-cli) and a narrow prerelease-versioning niche, making it clearly distinguishable and unlikely to trigger for the wrong skill.	3 / 3
	Total	9 / 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
referenced_paths_exist	Referenced path issues: 1 missing	Warning

	Total	14 / 16 Passed

Repository: bradygaster/squad
Path: .squad/skills/versioning-policy/SKILL.md
Commit: e23dd92

Reviewed: 1 day 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.