| name | mpy-review |
| description | Use this skill when the user wants to review MicroPython code changes using historical review patterns. Invoke when user mentions reviewing code, finding review examples, or wants feedback on MicroPython PRs/commits/diffs. Provides semantic search across ~19.5K categorized review comments. |
MicroPython Review Assistant Skill
Purpose
This skill provides AI-assisted code review for MicroPython using historical review patterns from the lead maintainer. It searches a database of ~19.5K categorized review comments to find relevant examples and generate review context.
Note: When the mpy-reviewer MCP server is available (registered in .claude/settings.json), prefer using MCP tools directly (review_diff, search_reviews, etc.) instead of the CLI. The MCP server keeps the embedding model warm across calls, eliminating 2-3s cold start per query. This skill remains as a fallback for sessions outside the project scope.
IMPORTANT: The review_diff MCP tool accepts diffs of any size. Do NOT fall back to CLI because a diff seems "too large". Pass the full diff text directly as the diff_text parameter regardless of length. The tool internally splits multi-file diffs into per-file chunks for embedding, so large diffs are handled efficiently.
MCP file-based output: The MCP review_diff and review_pr tools return a compact orchestration prompt (~5-8K) instead of raw data. Review examples are written to individual temp files under /tmp/mpy-review-*/. The prompt includes a summary table with file paths, sizes, severities, and domains. To use the examples:
- Read small files (<2KB) directly with the Read tool
- For large files (>2KB), consider spawning subagents to process them in parallel
- The diff is NOT echoed back — you already have it in context from when you generated it
When to Use This Skill
Invoke this skill when the user:
- Wants to review code changes (branches, commits, diffs, PRs)
- Asks for maintainer-style feedback on their code
- Wants to find examples of specific review patterns
- Needs review context for MicroPython code
- Mentions reviewing, feedback, or code quality for MicroPython
Important: Users cannot invoke skills directly. They must ask you to use the skill:
- User: "Can you review my current branch?"
- User: "Can you /mpy-review the current branch?"
When the user asks for review help, invoke this skill proactively.
Requirements
This skill requires codanna for semantic code search and codebase analysis.
Automatic setup: A SessionStart hook automatically installs codanna via cargo on first use.
Manual installation:
cargo install codanna --all-features
If codanna is not installed, the tool will fail with a prominent error message directing the user to install it.
Tool Location
The underlying CLI tool is located at:
uv run --project ${CLAUDE_PLUGIN_ROOT} mpy-reviewer
Always use this full path when invoking the tool. Do not rely on PATH.
Understanding User Intent
Parse natural language requests and map to appropriate tool commands:
Review Current Changes
User says: "review my current changes", "review this branch", "review what I've done"
What to do:
- Generate diff:
git diff main (or appropriate base branch)
- Pipe to tool:
git diff main | uv run --project ${CLAUDE_PLUGIN_ROOT} mpy-reviewer review --stdin --codebase --output prompt
- Present the review prompt to help the user
Example:
git diff main | uv run --project ${CLAUDE_PLUGIN_ROOT} mpy-reviewer review --stdin --codebase --output prompt
Review Specific Commit
User says: "review commit abc123", "check commit abc123"
What to do:
- Get commit diff:
git show abc123
- Pipe to tool:
git show abc123 | uv run --project ${CLAUDE_PLUGIN_ROOT} mpy-reviewer review --stdin --output prompt
Example:
git show ca65d543 | uv run --project ${CLAUDE_PLUGIN_ROOT} mpy-reviewer review --stdin --codebase --output prompt
Review Uncommitted Changes
User says: "review my uncommitted changes", "review staged changes"
What to do:
git diff HEAD | uv run --project ${CLAUDE_PLUGIN_ROOT} mpy-reviewer review --stdin --output prompt
git diff --cached | uv run --project ${CLAUDE_PLUGIN_ROOT} mpy-reviewer review --stdin --output prompt
Review GitHub PR
User says: "review PR 12345", "check pull request 12345"
What to do:
uv run --project ${CLAUDE_PLUGIN_ROOT} mpy-reviewer review --pr 12345 --codebase --output prompt
Review Specific Files
User says: "review my changes to py/gc.c", "review changes in extmod/"
What to do:
git diff main -- py/gc.c | uv run --project ${CLAUDE_PLUGIN_ROOT} mpy-reviewer review --stdin --output prompt
git diff main -- extmod/ | uv run --project ${CLAUDE_PLUGIN_ROOT} mpy-reviewer review --stdin --codebase --output prompt
Find Review Examples
User says: "find examples of memory allocation reviews", "show me feedback on error handling"
What to do:
uv run --project ${CLAUDE_PLUGIN_ROOT} mpy-reviewer search "memory allocation" --domain memory -k 10
uv run --project ${CLAUDE_PLUGIN_ROOT} mpy-reviewer search "error handling" --domain correctness -k 10
Get Quick Context (No Full Prompt)
User says: "show me similar reviews", "what has been said about this before"
What to do:
Use --output context instead of --output prompt to get just the examples without full prompt structure:
git diff main | uv run --project ${CLAUDE_PLUGIN_ROOT} mpy-reviewer review --stdin --output context
Tool Commands Reference
Review Command
uv run --project ${CLAUDE_PLUGIN_ROOT} mpy-reviewer review [OPTIONS]
Input Options (choose one):
--diff FILE - Review a diff file--pr NUMBER - Review a GitHub PR (uses gh CLI)--stdin - Read diff from stdin (recommended for git integration)
Quality Options:
--codebase - Include MicroPython codebase context (definitions, patterns) [RECOMMENDED]--rerank - Use cross-encoder re-ranking for better relevance (slower, 5-10s on CPU)-k N - Number of review examples (default: 8)
Output Options:
--output context - Just the review examples (default, quick to read)--output prompt - Full prompt ready for AI review (recommended for comprehensive review)--output json - Structured JSON output
Search Command
uv run --project ${CLAUDE_PLUGIN_ROOT} mpy-reviewer search "query" [OPTIONS]
Options:
-k N - Number of results (default: 10)--domain DOMAIN - Filter by domain (see categories below)--severity SEVERITY - Filter by severity (blocking, suggestion, nitpick)--component COMPONENT - Filter by component (py_core, extmod, port_specific, etc.)--style-only - Only show comments that exemplify the maintainer's style--json - JSON output
Stats Command
uv run --project ${CLAUDE_PLUGIN_ROOT} mpy-reviewer stats
Shows index status and record count. Use this to verify the system is working.
Categories for Filtering
Domains (use with --domain)
correctness - Logic bugs, edge cases, error handlingcode_style - Formatting, naming conventionsapi_design - Public interfaces, function designmemory - Memory management, leaks, allocationperformance - Speed, efficiency optimizationsportability - Cross-platform compatibilitydocumentation - Comments, docs, claritytesting - Test coverage, qualitysecurity - Security vulnerabilitiesarchitecture - Design patterns, structurebuild_system - Makefiles, build configurationerror_handling - Error paths, recovery
Severities (use with --severity)
blocking - Must fix before mergesuggestion - Recommended improvementnitpick - Minor style/preference
Components (use with --component)
py_core - Core Python runtime (py/)extmod - Extended modules (extmod/)port_specific - Port implementations (ports/)drivers - Hardware driverstools - Build/dev toolstests - Test suitedocs - Documentationbuild_system - Build configuration
Output Interpretation
Context Output (--output context)
Returns formatted markdown with:
- Review examples with diff context
- Review comments
- Domain and severity tags
Present this directly to the user to show relevant past reviews.
Prompt Output (--output prompt)
Returns a complete prompt containing:
- Review style guide
- 5-10 relevant review examples with code context
- The code to review
- Task instructions for AI review
How to use: After generating this prompt, you should:
- Present it to the user, OR
- Use it internally to generate a maintainer-style review yourself
Note: When using the MCP server instead of CLI, the review_diff/review_pr tools return an orchestration prompt with temp file paths rather than inlining all examples. Read the referenced files to access the full review examples.
JSON Output (--output json)
Returns structured data. Parse and present relevant fields to user.
Two-Step Verification Workflow
After generating findings, use the verify_findings MCP tool to cross-check each
finding against the actual codebase before presenting results. This reduces false
positives caused by pattern-matching without context.
Structured Finding Format
Findings must be formatted as a JSON array:
[
{
"file": "extmod/asyncio/stream.py",
"line": 42,
"severity": "blocking",
"description": "POLLHUP not handled in ioctl bitmask",
"diff_hunk": "the relevant diff hunk text"
}
]
verify_findings Tool
verify_findings(findings, diff_text, pr_number=None, repo="micropython/micropython")
findings: JSON array of structured findings (format above)diff_text: the full unified diff being reviewedpr_number: optional PR numberrepo: repository slug
Returns a markdown orchestration prompt with a summary table and paths to
per-finding verdict files under /tmp/mpy-verify-*/.
Verdict Types
- confirmed: finding is valid; keep as-is (or with adjusted severity)
- partially_valid: finding has merit but needs adjustment; update severity/description
- false_positive: finding is wrong; drop it from the review
- inconclusive: verification could not determine validity; use your judgment
Verification Workflow
- Generate diff (git diff, git show, etc.)
- Call
review_diff to get examples and style context
- Read examples and analyze the diff
- Assemble findings as a JSON array
- Call
verify_findings(findings, diff_text) to cross-check
- Read verdict files for evidence
- Drop false positives, adjust partially valid findings
- Present verified findings as the final review
Workflow Examples
Example 1: User Wants General Review
User: "Can you review my current changes?"
Your response:
- Run:
git diff main | uv run --project ${CLAUDE_PLUGIN_ROOT} mpy-reviewer review --stdin --codebase --output prompt
- Read the generated prompt
- Use the prompt to provide maintainer-style review feedback to the user
Example 2: User Wants Quick Examples
User: "What has been said about similar code before?"
Your response:
- Run:
git diff main | uv run --project ${CLAUDE_PLUGIN_ROOT} mpy-reviewer review --stdin --output context
- Present the review examples to the user directly
- Summarize common themes
Example 3: User Asks About Specific Pattern
User: "Find me examples of feedback on GPIO configuration"
Your response:
- Run:
uv run --project ${CLAUDE_PLUGIN_ROOT} mpy-reviewer search "GPIO configuration" --component port_specific -k 15
- Present the search results
- Summarize key patterns
Example 4: User Mentions Specific Commit
User: "Review commit ca65d543"
Your response:
- Run:
git show ca65d543 | uv run --project ${CLAUDE_PLUGIN_ROOT} mpy-reviewer review --stdin --codebase --output prompt
- Use the prompt to provide review feedback
- Highlight key issues found from similar past reviews
Example 5: User Asks to Review Specific File
User: "Can you review my changes to py/gc.c?"
Your response:
- Run:
git diff main -- py/gc.c | uv run --project ${CLAUDE_PLUGIN_ROOT} mpy-reviewer review --stdin --codebase --output prompt
- Provide targeted review focusing on that file
- Reference relevant review patterns for GC code
Decision Guide: When to Use Which Options
Use --codebase
When: User wants comprehensive review, mentions API usage, function calls, or needs context
Why: Includes MicroPython codebase definitions and patterns
Cost: +2-3 seconds
Use --rerank
When: User emphasizes quality/accuracy, or initial results seem off-topic
Why: Better relevance via cross-encoder scoring
Cost: +5-10 seconds on CPU
Use --output prompt
When: User wants detailed review, mentions "thorough", or you'll provide review feedback
Why: Gives you complete context to generate maintainer-style review
Cost: Longer output to process
Use --output context
When: User asks for examples, "what has been said", or wants quick reference
Why: Just the examples, faster to read
Cost: Minimal
Use search instead of review
When: User asks about patterns/topics without providing specific code to review
Example: "What do reviewers think about error handling?"
Why: Semantic search, not diff-based retrieval
Handling Errors
"Index not found"
The vector index hasn't been built. Inform user:
The review database index needs to be built first. Run:
cd ${CLAUDE_PLUGIN_ROOT}
uv run python scripts/build_index_resume.py
"Command not found"
Verify uv and the project are accessible:
uv run --project ${CLAUDE_PLUGIN_ROOT} mpy-reviewer stats
Git errors (no repository, invalid ref, etc.)
Handle appropriately - ask user to clarify or check their git state.
Performance Expectations
- First query: 2-3 seconds (model loading)
- Subsequent queries: 0.5-1 second (dense search only)
- With --rerank: +5-10 seconds on CPU
- With --codebase: +2-3 seconds
Inform user if a long operation is running.
Data Scope
The database contains:
- ~19.5K categorized review comments
- Source: micropython/micropython and micropython/micropython-lib repositories
- Timeframe: 2013-2026
- Coverage: All PR review comments, issue comments, and review verdicts
Natural Language Understanding
Be flexible with user requests. Map to appropriate commands:
| User Intent | Tool Command |
|---|
| "review this" | git diff | ... review --stdin |
| "review commit X" | git show X | ... review --stdin |
| "review PR 123" | ... review --pr 123 |
| "find GPIO reviews" | ... search "GPIO" --component port_specific |
| "show me memory issues" | ... search "memory" --domain memory --severity blocking |
| "examples of his style" | ... search "..." --style-only |
Always interpret user intent conversationally, then invoke the appropriate tool command.
Important Notes
- Always use full path:
uv run --project ${CLAUDE_PLUGIN_ROOT} mpy-reviewer
- Prefer stdin for git integration: Use
git diff \| ... --stdin over temp files
- Default to quality: Use
--codebase --output prompt unless user wants quick results
- Be conversational: Don't just relay CLI output, interpret and present meaningfully
- Handle context: If reviewing specific commits/branches, mention what's being reviewed
- Cite examples: When referencing review patterns, show the actual comments from search results
Verification
To test the skill is working:
uv run --project ${CLAUDE_PLUGIN_ROOT} mpy-reviewer stats
Should show:
- Index exists: True
- Number of records: ~19.5K
