squad-conventions

Core conventions and patterns used in the Squad codebase

Quality

63%

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 ./.copilot/skills/squad-conventions/SKILL.md

Quality

Content

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

The body is a strong, executable conventions document: every pattern is stated as a hard rule with concrete names, commands, and working code examples, and the Anti-Patterns section converts each rule into an explicit prohibition. Its only weaknesses are minor redundancy between Patterns and Anti-Patterns and the absence of a verification workflow (e.g., run the test suite before declaring a change done), which is only weakly implied.

Suggestions

Add a short "When done" step (e.g., "Run npm test — node --test test/ — and confirm all tests pass on the change") to give the conventions an explicit validation checkpoint.

Trim the overlap between Patterns and Anti-Patterns: state each rule once in Patterns, and keep Anti-Patterns as terse one-line reminders rather than re-explaining the rationale.

Consider folding the file-structure ownership table (user-owned vs Squad-owned) into a single compact list, since it is the densest section and reads as two overlapping lists.

Dimension	Reasoning	Score
Conciseness	The body is lean and assumes Claude's competence ("Tests use node:test and node:assert/strict — no test frameworks"), with no padding or explanations of known concepts. Scored 4 rather than 5 because the Anti-Patterns section restates rules already fully specified in Patterns (zero-dep, path separators, fatal(), color constants), a minor duplication that could be trimmed.	4 / 5
Actionability	Fully executable guidance throughout: concrete function names (fatal(msg), copyRecursive(src, target)), exact color constants (GREEN, RED, DIM, BOLD, RESET), runnable commands (npm test, node --test test/), and a copy-paste-ready JavaScript Examples block covering error handling, Windows-safe paths, and the skip-if-exists pattern. Matches anchor 5 — code covers the common cases.	5 / 5
Workflow Clarity	This is a conventions skill rather than a multi-step workflow, and each convention is unambiguous with clear ownership rules ("Never overwrite user state during init. The upgrade flow overwrites only Squad-owned files") plus a validation signal ("All tests must pass on all platforms"). Scored 4 not 5 because there is no explicit sequenced workflow with checkpoints — e.g., how to verify a change before shipping an upgrade — though no destructive/batch workflow is being taught that would trigger the cap.	4 / 5
Progressive Disclosure	No bundle files exist (references/, scripts/, assets/ are absent) and none are needed: the ~61-line body is self-contained with clean sections (Context, Patterns, Examples, Anti-Patterns), no nested references, and no bulk content that belongs in a separate file. This fits the well-organized self-contained structure of anchor 5.	5 / 5
	Total	18 / 20 Passed

Description

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

The description is concise and domain-scoped but under-specified: it says nothing about what the conventions actually cover (zero-dep, fatal(), path.join(), init idempotency) and gives no "Use when" trigger guidance. A user or Claude would not reliably know when to load this skill.

Suggestions

Enumerate the concrete capability areas in the description, e.g., "Covers zero-dependency constraints, the fatal() error pattern, ANSI color constants, Windows-safe path handling, and init idempotency rules in the Squad codebase."

Add an explicit trigger clause: "Use when modifying Squad source code, adding tests, or changing init/upgrade behavior in the create-squad CLI."

Include natural trigger terms users would actually say — "Squad CLI", "create-squad", "Squad conventions", "Squad coding standards" — to improve both trigger quality and completeness.

Dimension	Reasoning	Score
Specificity	"Core conventions and patterns used in the Squad codebase" names a specific domain but lists no concrete actions or capabilities — "conventions and patterns" is generic. It does not reach anchor 3 because no concrete actions (e.g., error handling, testing, file structure conventions) are enumerated.	2 / 5
Completeness	It has a vague "what" (which conventions? for what tasks?) and no "when" trigger guidance at all — no "Use when..." or equivalent clause. This matches anchor 2 exactly (vague what, no when) and the missing-trigger cap of 3 applies regardless.	2 / 5
Trigger Term Quality	"conventions", "patterns", and "Squad codebase" are terms a developer might naturally say, but coverage is thin — missing obvious variations like "Squad CLI", "create-squad", "coding standards", or "project rules". Matches anchor 3: some relevant keywords but missing common variations.	3 / 5
Distinctiveness Conflict Risk	Scoping to "the Squad codebase" gives it a clear niche unlikely to fire for unrelated skills, with only minor overlap risk against other project-conventions skills in the same repo. Not 5 because the description itself doesn't state distinct triggers that would fully disambiguate it.	4 / 5
	Total	11 / 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
frontmatter_unknown_keys	Unknown frontmatter key(s) found; consider removing or moving to metadata	Warning

	Total	15 / 16 Passed

Repository: bradygaster/squad
Path: .copilot/skills/squad-conventions/SKILL.md
Commit: 29e69f5

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.