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).

⭐5stars🔀1forks📁View on GitHub🕐Updated Jan 11, 2026⬇️2downloads

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.
namemarp-slide-quality
descriptionAnalyze 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-toolsRead, 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 (.md file with marp: true frontmatter)
  • 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

  1. Analyze: Run SlideGauge to get baseline scores
  2. Prioritize: Focus on slides scoring < 70 first, then < 80
  3. Fix: Apply fixes from FIXES.md based on diagnostics
  4. Validate: Re-run to confirm improvements
  5. 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

  1. Always show user the results - don't just fix silently
  2. Explain WHY each fix improves the slide
  3. Get user approval before making major changes (splitting slides, removing content)
  4. Preserve user intent - don't change technical content
  5. 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.