Use this skill to grade code, specifications, or design documents across four quality dimensions using a 1-5 scoring scale. In grade-and-fix mode, the skill auto-improves artifacts scoring below 5 without prompting. Invoke when you want consistent quality assessment on design, implementation, or specification with actionable feedback and self-healing improvements.
Use this skill to grade code, specifications, or design documents across four quality dimensions using a 1-5 scoring scale. In grade-and-fix mode, the skill auto-improves artifacts scoring below 5 without prompting. Invoke when you want consistent quality assessment on design, implementation, or specification with actionable feedback and self-healing improvements.
Quality Grading Skill
Evaluate and improve code, specifications, or design documents across four quality dimensions with calibrated scoring and auto-fix capabilities.
Overview
This skill provides a multi-dimensional quality grading system for any artifact type:
Designs: Architecture documents, system designs, technical specifications
It supports two invocation modes:
evaluate: Score the artifact and return structured JSON results
grade-and-fix: Score the artifact, then auto-fix dimensions scoring below 5, re-grade, and provide final results
The skill targets score 5+ as the quality bar. Auto-fix attempts are limited to 3 per dimension to keep improvements pragmatic and avoid unnecessary complexity.
Invocation
Load this skill when:
You want quality feedback on code or implementation
You want quality feedback on design or architecture documents
You want quality feedback on specifications or requirements
You want to improve artifacts scoring below 5 automatically
You need consistent, calibrated quality assessments
Input
artifact: Path to the file, directory, or snippet to grade (required)
mode: or (default: )
evaluate
grade-and-fix
evaluate
Process
Load artifact: Read the target file, all files in the directory, or parse the snippet
Detect artifact type: Determine if this is code, a specification, or a design document
Apply dimension rubrics: Score each of the four dimensions independently, adapting criteria to artifact type
Use calibration examples: Compare against few-shot examples for consistency
If grade-and-fix mode and score < 5: Apply targeted auto-fix, re-grade, repeat up to 3 times
Generate JSON output: Return structured results with scores, justifications, and suggestions
Grading Dimensions
1. Design Quality
Measures: Architecture clarity, scalability, and separation of concerns
For Code: Module structure, dependency management, separation of concerns
For Designs: Architecture clarity, module boundaries, scalability patterns, diagram quality
For Specifications: Logical organization, traceability, clarity of structure
What to look for:
Clear module boundaries and logical file organization
Proven scalability patterns appropriate to the problem
Strong separation of concerns (no intermingled responsibilities)
Clean dependency flow
Scoring Rubric:
Score
Descriptor
5
Exceptional architecture with clear module boundaries, proven scalability patterns, strong separation of concerns
4
Good architecture with clear modules, adequate scalability consideration, minor separation issues
3
Adequate architecture with recognizable modules, moderate separation of concerns
2
Weak architecture with unclear module boundaries, limited separation of concerns
1
Poor architecture with tangled dependencies, no clear modules, intermingled concerns
Auto-Fix (score < 5):
Add missing module boundaries or clear separation between concerns
Consolidate tangled dependencies into logical modules
Simplify overly complex architectural patterns
2. Originality
Measures: Avoidance of generic boilerplate and tailoring to the problem
For Code: Problem-specific solutions vs copy-paste patterns
For Designs: Domain-specific architecture vs generic templates
For Specifications: Tailored requirements vs boilerplate language
What to look for:
Problem-specific terminology and approach
Contextual examples that map to the domain
Removal of irrelevant template content
Novel solutions rather than copy-paste patterns
Scoring Rubric:
Score
Descriptor
5
Highly tailored solution with novel approaches directly mapped to the problem domain
4
Mostly tailored solution with some unique adaptations to the problem
3
Mix of generic and tailored approaches
2
Mostly generic with minimal adaptation to the problem
1
Generic, copy-paste solution with no adaptation to the specific problem
Auto-Fix (score < 5):
Replace generic boilerplate with problem-specific terminology
Add context-specific examples or patterns
Remove irrelevant template content
3. Craft
Measures: Code cleanliness, error handling, and documentation
For Code: Clean code, error handling, comments, documentation
For Designs: Diagram clarity, consistent formatting, completeness
For Specifications: Clear writing, consistent terminology, proper structure
Exceptionally clean code with comprehensive error handling and exemplary documentation
4
Clean code with good error handling and documentation with minor gaps
3
Adequate code quality with some error handling and documentation
2
Messy code with limited error handling and minimal documentation
1
Messy, error-prone code with little to no documentation
Auto-Fix (score < 5):
Add missing error handling for edge cases
Clean up inconsistent formatting or naming
Add doc comments to undocumented functions
4. Functionality
Measures: Feature completeness and edge case handling
For Code: Features work, edge cases handled
For Designs: All requirements covered, feasibility, completeness
For Specifications: Complete requirements, clear acceptance criteria, no gaps
What to look for:
All specified features are implemented
Edge cases are identified and handled
Requirements or acceptance criteria are covered
No broken references or incomplete specifications
Scoring Rubric:
Score
Descriptor
5
Complete feature implementation with comprehensive edge case handling
4
Full implementation with minor edge case gaps
3
Most features implemented with some edge cases handled
2
Partial implementation with several unhandled edge cases
1
Missing features and unhandled edge cases causing frequent failures
Auto-Fix (score < 5):
Add missing functionality or requirements coverage
Address identified edge cases in the implementation
Fix broken references or incomplete specifications
Self-Healing Behavior
When invoked in grade-and-fix mode:
Trigger: Auto-fix activates for any dimension scoring below 5
Fix Strategy: Apply minimal, targeted changes that address the specific gap without introducing unnecessary complexity
Re-grade: After each fix, re-score to verify improvement
Attempts: Maximum 2 auto-fix attempts per dimension
Fallback: If auto-fix fails to achieve score 5+, record actionable suggestions instead of blocking
Principle: Prioritize pragmatic simplicity over exhaustive perfection
Few-Shot Calibration
Use the examples in references/ directories to calibrate your scoring:
design-quality/: Examples of architecture quality at each score level
originality/: Examples of boilerplate vs tailored solutions
craft/: Examples of code cleanliness and documentation quality
functionality/: Examples of feature completeness
Compare the artifact you're grading against these examples for consistent calibration.
Output Format
The skill produces JSON output:
{"artifact":"<path-to-graded-file>","artifactType":"code | specification | design","timestamp":"<ISO-8601 timestamp>","mode":"evaluate | grade-and-fix","dimensions":{"designQuality":{"score":1-5,"justification":"<brief explanation of the score>","improved":"<null | description of auto-fix applied>"},"originality":{"score":1-5,"justification":"<brief explanation of the score>","improved":"<null | description of auto-fix applied>"},"craft":{"score":1-5,"justification":"<brief explanation of the score>","improved":"<null | description of auto-fix applied>"},"functionality":{"score":1-5,"justification":"<brief explanation of the score>","improved":"<null | description of auto-fix applied>"}},"overallScore":"<average of dimensions, displayed as X.Y>","summary":"<overall assessment text>","suggestions":{"<dimension>":"<actionable improvement if score < 5 and auto-fix failed>"}}
Glossary
Term
Definition
Quality Grading Skill
A skill that evaluates artifacts across multiple dimensions using a 1-5 scoring scale
Dimension
A distinct aspect of quality being evaluated (Design Quality, Originality, Craft, Functionality)
Artifact Type
The category of artifact being graded: code, specification, or design
Few-Shot Calibration
Providing example artifacts with known scores to guide consistent grading
Self-Healing
The skill's ability to auto-fix quality gaps without user prompting
Grade-and-Fix Mode
Invocation mode where grading and improvement are performed sequentially without user input
Examples
Example: Evaluate Code Quality
User: Grade this implementation using quality-grading skill
Artifact: src/services/auth.ts
Mode: evaluate
Example: Grade Design Document
User: Assess the quality of this architecture design
Artifact: docs/architecture/system-design.md
Mode: grade-and-fix
Example: Evaluate Specification
User: Grade this requirements document
Artifact: .specs/changes/feature/requirements.md
Mode: evaluate
Example: Grade and Fix
User: Grade and improve this module
Artifact: src/utils/
Mode: grade-and-fix
