Core conventions and patterns used in the Squad codebase
61
43%
Does it follow best practices?
Impact
93%
1.27xAverage score across 3 eval scenarios
Passed
No known issues
Optimize this skill with Tessl
npx tessl skill review --optimize ./.squad/skills/squad-conventions/SKILL.mdQuality
Discovery
7%Based on the skill's description, can an agent find and select it at the right time? Clear, specific descriptions lead to better discovery.
This description is extremely vague and provides almost no actionable information for skill selection. It fails to list specific capabilities, lacks trigger terms users would naturally use, and has no explicit guidance on when Claude should select this skill. The only slight positive is the project-specific reference to 'Squad codebase.'
Suggestions
List specific concrete actions the skill covers, e.g., 'Applies naming conventions, file structure patterns, error handling idioms, and code style rules used in the Squad codebase.'
Add an explicit 'Use when...' clause, e.g., 'Use when writing or reviewing code in the Squad project, or when the user asks about Squad coding standards, style, or architecture patterns.'
Include natural trigger terms a user might say, such as 'Squad style guide', 'Squad code review', 'Squad project conventions', or 'Squad architecture'.
| Dimension | Reasoning | Score |
|---|---|---|
Specificity | The description uses vague, abstract language ('conventions and patterns') without listing any concrete actions. It does not describe what the skill actually does—no specific capabilities are mentioned. | 1 / 3 |
Completeness | The description weakly addresses 'what' (conventions and patterns) and completely omits 'when' — there is no 'Use when...' clause or any explicit trigger guidance. | 1 / 3 |
Trigger Term Quality | The only potentially useful keyword is 'Squad codebase,' which is project-specific but not a natural trigger term a user would say. 'Conventions and patterns' are overly generic and not actionable trigger terms. | 1 / 3 |
Distinctiveness Conflict Risk | The mention of 'Squad codebase' provides some specificity to a particular project, which reduces conflict with generic coding skills. However, 'conventions and patterns' is broad enough to overlap with any coding style or standards skill. | 2 / 3 |
Total | 5 / 12 Passed |
Implementation
79%Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.
This is a strong conventions skill that is concise, actionable, and well-structured. It correctly assumes Claude's competence with Node.js while teaching project-specific patterns. The main areas for improvement are around workflow clarity for the init/upgrade distinction and potentially linking to deeper reference material for complex subsystems.
Suggestions
Consider adding a brief decision flow or table clarifying which files are user-owned vs Squad-owned and what happens to each during init vs upgrade operations.
If there are separate docs for testing patterns or the upgrade flow, add one-level-deep references (e.g., 'See TESTING.md for test conventions') to improve progressive disclosure.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | Every section earns its place — no explanations of what Node.js built-ins are or how path.join works. The content is dense with project-specific conventions Claude wouldn't know, and avoids padding. | 3 / 3 |
Actionability | Provides executable code examples for the fatal() pattern, path construction, and skip-if-exists pattern. The anti-patterns section gives concrete do/don't guidance. Commands like `npm test` and `node --test test/` are copy-paste ready. | 3 / 3 |
Workflow Clarity | This is a conventions/patterns skill rather than a multi-step workflow, so explicit sequencing is less critical. However, the init vs upgrade flow could benefit from a clearer decision tree — the distinction between user-owned and Squad-owned files during init vs upgrade is mentioned but not sequenced with validation checkpoints. | 2 / 3 |
Progressive Disclosure | The content is well-organized with clear sections (Patterns, Examples, Anti-Patterns), but everything is inline in a single file. The file structure section hints at related files (templates/, .squad/) but doesn't link to any deeper documentation. For a conventions skill this is acceptable but could benefit from linking to e.g., a testing guide or upgrade flow details. | 2 / 3 |
Total | 10 / 12 Passed |
Validation
90%Checks the skill against the spec for correct structure and formatting. All validation checks must pass before discovery and implementation can be scored.
Validation — 10 / 11 Passed
Validation for skill structure
| Criteria | Description | Result |
|---|---|---|
frontmatter_unknown_keys | Unknown frontmatter key(s) found; consider removing or moving to metadata | Warning |
Total | 10 / 11 Passed | |
9bf8669
Table of Contents
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.