marp-slide-quality
Analyze and improve Marp markdown presentations using SlideGauge. Use when working with Marp slides, presentation files ending in .md with marp frontmatter, or when user asks to check, analyze, improve, or validate slide quality. Requires slidegauge package (installed via uvx).
When & Why to Use This Skill
This Claude skill provides automated analysis and optimization for Marp markdown presentations using the SlideGauge tool. It evaluates slide quality across critical dimensions—including accessibility, layout, color contrast, and content density—to ensure presentations are professional, readable, and impactful. By providing real-time scoring and actionable fixes, it helps users transform raw markdown into high-quality visual decks.
Use Cases
- Technical Presentation Auditing: Automatically scan Marp-based slide decks to detect overly complex code blocks, long titles, or excessive bullet points that hinder audience retention.
- Accessibility & Compliance: Ensure slides meet inclusive design standards by checking for color contrast ratios and missing alternative text (a11y) within the markdown source.
- Automated Content Refinement: Identify 'wall of text' slides and receive specific recommendations for splitting content or simplifying layouts to maintain a professional aesthetic.
- Quality Benchmarking: Use the 0-100 scoring system to validate slide improvements during the drafting process, ensuring every deck meets a minimum quality threshold before export.
| name | marp-slide-quality |
|---|---|
| description | Analyze and improve Marp markdown presentations using SlideGauge. Use when working with Marp slides, presentation files ending in .md with marp frontmatter, or when user asks to check, analyze, improve, or validate slide quality. Requires slidegauge package (installed via uvx). |
| allowed-tools | Read, Edit, Bash, Grep, Glob |
Marp Slide Quality Analyzer
This Skill uses SlideGauge to analyze Marp markdown presentations and help you create high-quality slides that follow best practices.
When to use this Skill
- User is working on a Marp presentation (
.mdfile withmarp: truefrontmatter) - User asks to check, analyze, validate, or improve slide quality
- User mentions SlideGauge or slide quality issues
- User wants to fix specific slide problems (too many bullets, long content, etc.)
Instructions
1. Initial Analysis
When user asks to analyze their slides:
# Run SlideGauge with text output for quick overview
uvx --from git+https://github.com/nibzard/slidegauge slidegauge <path-to-presentation.md> --text
Explain the results:
- Overall score and passing rate
- Number of issues found
- Category breakdown (a11y, code, color, content, layout)
2. Detailed Analysis
For slides that need fixing (score < 80):
# Get JSON output with detailed diagnostics
uvx --from git+https://github.com/nibzard/slidegauge slidegauge <path-to-presentation.md> --json | jq '.slides[] | select(.score < 80)'
For each failing slide, identify:
- Exact slide number and title
- Specific issues with deduction amounts
- Actionable recommendations
3. Fix Common Issues
Use the Edit tool to fix issues. See FIXES.md for specific fix patterns.
Common fixes:
- Too many bullets: Split into multiple slides or consolidate
- Content too long: Trim text or split slide
- Code too long: Simplify examples or split
- Too many lines: Reduce content density
- Title too long: Shorten to ≤35 characters
4. Validate Fixes
After making changes, re-run SlideGauge:
uvx --from git+https://github.com/nibzard/slidegauge slidegauge <path-to-presentation.md> --text
Compare before/after scores and confirm improvements.
Workflow
- Analyze: Run SlideGauge to get baseline scores
- Prioritize: Focus on slides scoring < 70 first, then < 80
- Fix: Apply fixes from FIXES.md based on diagnostics
- Validate: Re-run to confirm improvements
- Iterate: Repeat until all slides pass (≥70) or user is satisfied
Key Thresholds
- 70: Minimum passing score (slides below this MUST be fixed)
- 80: Good quality (recommend fixing these)
- 90+: Excellent quality
- 100: Perfect score
Category Scores
- a11y: Accessibility (alt text, contrast)
- code: Code block length and complexity
- color: Color usage and contrast ratios
- content: Text length, bullets, line count
- layout: Overall slide structure
Best Practices
- Always show user the results - don't just fix silently
- Explain WHY each fix improves the slide
- Get user approval before making major changes (splitting slides, removing content)
- Preserve user intent - don't change technical content
- Re-validate after fixes to show improvement
Examples
See EXAMPLES.md for detailed examples of:
- Analyzing a full presentation
- Fixing specific slide issues
- Splitting overloaded slides
- Optimizing code examples
Reference
See REFERENCE.md for complete SlideGauge rule documentation.
Dependencies
SlideGauge is installed via uvx on-demand:
uvx --from git+https://github.com/nibzard/slidegauge slidegauge --help
No manual installation required - uvx handles it automatically.