review-maintainability
Maintainability and design review instructions for the expert agent
56
46%
Does it follow best practices?
Impact
Pending
No eval scenarios have been run
Passed
No known issues
Optimize this skill with Tessl
npx tessl skill review --optimize ./dot_config/opencode/skill/review-maintainability/SKILL.mdQuality
Discovery
0%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 lacks concrete actions, natural trigger terms, explicit 'when to use' guidance, and any distinguishing details that would help Claude choose it over other skills.
Suggestions
List specific concrete actions the skill performs, e.g., 'Reviews code for maintainability issues, identifies design pattern violations, suggests refactoring opportunities, and flags code smells.'
Add an explicit 'Use when...' clause with natural trigger terms, e.g., 'Use when the user asks for a code review, wants to improve code quality, mentions refactoring, or asks about design patterns and SOLID principles.'
Clarify the scope and niche to reduce conflict risk, e.g., specify the languages, frameworks, or types of codebases this applies to, and distinguish it from general code review or linting skills.
| Dimension | Reasoning | Score |
|---|---|---|
Specificity | The description uses vague, abstract language ('maintainability and design review instructions') without listing any concrete actions. It does not specify what the skill actually does—no verbs like 'analyze', 'review', 'generate', or 'flag'. | 1 / 3 |
Completeness | The description fails to answer both 'what does this do' and 'when should Claude use it'. There is no 'Use when...' clause or any explicit trigger guidance, and the 'what' is extremely vague. | 1 / 3 |
Trigger Term Quality | The terms 'maintainability', 'design review', and 'expert agent' are abstract and jargon-heavy. Users are unlikely to naturally say 'maintainability review instructions' when requesting help; common terms like 'code review', 'refactor', or 'clean code' are absent. | 1 / 3 |
Distinctiveness Conflict Risk | The description is so generic that it could overlap with any code quality, code review, architecture, or design-related skill. 'Design review' and 'maintainability' are broad concepts with no clear niche or distinct triggers. | 1 / 3 |
Total | 4 / 12 Passed |
Implementation
92%Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.
This is a high-quality skill that provides clear, actionable instructions for maintainability review. Its strengths are the explicit exploration phase with verification steps, well-defined scope boundaries, and a concrete output schema. The only minor weakness is that the content is moderately dense in a single file, though this is acceptable given the skill's complexity.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | Every section earns its place. No unnecessary explanations of what code review is or how git works. The skill assumes Claude's competence and focuses exclusively on domain-specific instructions that Claude wouldn't know without being told. | 3 / 3 |
Actionability | Highly actionable with specific grep-based verification steps, concrete examples of bad naming patterns, explicit output JSON schema, and clear severity levels. Each scope item is specific enough to act on directly. | 3 / 3 |
Workflow Clarity | Phase 1 exploration is clearly sequenced with 9 numbered steps that must be completed before findings. The workflow includes validation checkpoints (grep to confirm patterns before flagging DRY, git blame to confirm origin, reading conventions files before citing violations). The escalation mechanism provides a clear feedback loop for out-of-scope issues. | 3 / 3 |
Progressive Disclosure | The content is well-organized with clear sections (Phase 1, Scope, Escalations, Rules, Output), but it's a moderately long single file (~70 lines of content) where some sections like the detailed Scope list could potentially be split out. However, for a skill of this complexity, keeping it in one file is reasonable. The lack of any external references is a minor missed opportunity. | 2 / 3 |
Total | 11 / 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 — 11 / 11 Passed
Validation for skill structure
No warnings or errors.
- Repository
- athal7/dotfiles
- Commit
07d79b6
- Reviewed
Table of Contents
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.