review-maintainability
Maintainability and design review instructions for the expert agent
Install with Tessl CLI
npx tessl i github:athal7/dotfiles --skill review-maintainability77
Quality
46%
Does it follow best practices?
Impact
99%
1.45xAverage score across 6 eval scenarios
Optimize this skill with Tessl
npx tessl skill review --optimize ./dot_config/opencode/skill/review-maintainability/SKILL.mdDiscovery
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 critically underdeveloped. It provides no concrete actions, no natural trigger terms users would say, and no guidance on when Claude should select this skill. It reads more like an internal label than a functional skill description.
Suggestions
Add specific concrete actions the skill performs (e.g., 'Reviews code for SOLID principles, identifies code smells, suggests refactoring patterns').
Include a 'Use when...' clause with natural trigger terms (e.g., 'Use when the user asks for code review, architecture feedback, refactoring suggestions, or mentions code quality').
Clarify the scope to distinguish from other review-related skills (e.g., specify if this is for Python, TypeScript, or general code; whether it covers security, performance, or only maintainability).
| 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. | 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 explicit trigger guidance. | 1 / 3 |
Trigger Term Quality | The terms 'maintainability', 'design review', and 'expert agent' are technical jargon that users would rarely naturally say. No common user-facing keywords are included. | 1 / 3 |
Distinctiveness Conflict Risk | The description is extremely generic and could overlap with any code review, architecture, or quality-related skill. 'Design review' and 'maintainability' are broad concepts without clear boundaries. | 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 guidance for maintainability reviews with excellent workflow structure including mandatory exploration phases and verification steps. The content is appropriately concise for its complexity, though the length suggests some content (like the full scope list or output schema) could be split into reference files for better progressive disclosure.
Suggestions
Consider moving the detailed JSON output schema to a separate SCHEMA.md file and referencing it, keeping only a brief example inline
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The skill is lean and efficient, assuming Claude's competence as a code reviewer. Every section serves a purpose with no unnecessary explanations of basic concepts like what diffs are or how code review works. | 3 / 3 |
Actionability | Provides concrete, executable guidance with specific scope items to check, exact output JSON format, explicit exploration steps, and clear examples of what constitutes valid findings vs escalations. | 3 / 3 |
Workflow Clarity | Excellent multi-step workflow with mandatory Phase 1 exploration before Phase 2 findings. Includes explicit validation checkpoints (exploration log requirement, git blame verification) and clear feedback loops for confirming issues before reporting. | 3 / 3 |
Progressive Disclosure | Content is well-organized with clear sections, but the skill is somewhat long (~100 lines) and could benefit from splitting detailed examples or the full scope list into a reference file. The inline JSON schema and exploration log format could be external references. | 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.
- 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.