Smithery is now a part of Arcade.dev! Read more in our announcement here
Validate Jupyter notebooks (.ipynb files) for production readiness...
Comprehensive validation of Jupyter notebooks (.ipynb files) to ensure production readiness. Validates smart links, layout structure, transitions, part flow, and overall quality standards.
Use this skill when you need to:
Before running full validation, manually verify:
<!-- action-cards --> marker(#) placeholder patternThis single check catches 80% of validation failures.
What it checks:
[text](#)) have matching headingsExpected pattern:
[Link Text](#) → Finds heading containing "Link Text"
Common issues:
What it checks:
Expected structure:
Introduction (Cells 0-N)
→ Transition (optional)
→ Part 1 (Start → Content → Summary)
→ Transition
→ Part 2 (Start → Content → Summary)
...
→ Conclusion
What it checks:
<!-- action-cards --> marker (REQUIRED)Expected pattern:
### Part X: Section Name
**Progress: X of Y** 🔵🔵🔵⚪⚪⚪
**Reading time: N minutes**
Contextual text explaining what's next...
<!-- action-cards -->
- [Topic 1](#)
- [Topic 2](#)
- [Topic 3](#)
⚠️ COMMON FAILURE: Missing Action Cards Marker
This is the #1 validation failure. Every transition cell between parts MUST include:
<!-- action-cards --> HTML comment marker(#) placeholder patternValidation will FAIL if:
<!-- action-cards --> markerWhen transitions are optional:
What it checks:
Expected title patterns:
### 🌍 Part 1: Topic Name
### 👥Part 2: By Your Role - Subtopic
### 🎯Part 3: By Your Task - Subtopic
Part structure requirements:
What it checks:
Common ordering issues:
Example of correct flow:
Part 6 Completion Cell
↓ immediately adjacent
Part 7 Transition Cell (with action cards)
↓
Part 7 Content Cells
↓
Part 7 Completion Cell
↓ immediately adjacent
Part 8 Transition Cell
What it checks:
<!-- action-cards --> marker present(#) placeholderQuality criteria:
What it checks:
Metadata requirements:
{
"metadata": {
"title": "Notebook Title",
"description": "Brief description",
"author": "Author Name",
"date": "YYYY-MM-DD",
"version": "X.Y",
"repo": "https://github.com/user/repo"
}
}
This is the most important validation step for missing action cards.
Find all transition cells by pattern matching:
def is_transition_cell(source):
return (
re.search(r'###.*Part \d+:', source) and
'Progress:' in source and
'🔵' in source and
'Reading time:' in source
)
Verify action card markers (REQUIRED):
has_action_cards = '<!-- action-cards -->' in source
if not has_action_cards:
issues.append({
'severity': 'ERROR',
'cell': cell_idx,
'message': f'Part {part_num} transition missing action cards marker'
})
Count links per transition (must be 3-6):
links = re.findall(r'^\s*- \[([^\]]+)\]\(#\)', source, re.MULTILINE)
if len(links) < 3:
issues.append({'severity': 'ERROR', 'message': 'Too few action cards'})
elif len(links) > 6:
issues.append({'severity': 'WARN', 'message': 'Too many action cards'})
Validate link targets - ensure all action card links resolve
Check contextual text - verify transition has explanatory text before action cards
Symptom: Link text doesn't match any heading
Fix:
# Before (broken)
[Getting Started](#) → No heading contains "Getting Started"
# After (fixed)
Heading: ### Getting Started Guide
Link: [Getting Started Guide](#)
Symptom: Part starts immediately after previous summary
Fix:
# Add transition cell with action cards
Contextual text...
<!-- action-cards -->
- [Topic 1](#)
- [Topic 2](#)
Symptom: Summary appears before content, or reference cells between parts
Fix:
# Reorder cells in notebook JSON
# Example: Move completion cell from index 64 to index 72
cells = notebook['cells']
completion_cell = cells.pop(64) # Remove from wrong position
cells.insert(72, completion_cell) # Insert at correct position
Common scenarios:
Symptom: Transition cell has no <!-- action-cards --> marker
Critical Issue: This is one of the most common validation failures. Every transition cell between parts MUST have action cards to guide readers.
Detection Pattern:
# Identifies transition cells by:
# 1. Contains "Part X:" heading
# 2. Has progress indicator (Progress: X of Y)
# 3. Has progress dots (🔵🔵...)
# 4. Has reading time estimate
# Then checks for:
# - <!-- action-cards --> marker (REQUIRED)
# - 3-6 markdown links after marker
# - Links use (#) placeholder pattern
Fix:
# Before (FAILS validation):
### Part 7: Universal Patterns
**Progress: 7 of 8** 🔵🔵🔵🔵🔵🔵🔵⚪
**Reading time: 2 minutes**
These patterns work everywhere...
# After (PASSES validation):
### Part 7: Universal Patterns
**Progress: 7 of 8** 🔵🔵🔵🔵🔵🔵🔵⚪
**Reading time: 2 minutes**
These patterns work everywhere...
<!-- action-cards -->
- [Beyond EDS](#)
- [Universal Patterns](#)
- [Apply Anywhere](#)
Why this matters:
Symptom: Parts numbered 1, 2, 4 (missing 3)
Fix: Renumber parts sequentially or add missing part
Use the /validate-notebook command:
/validate-notebook notebook-name.ipynb
Output includes:
Before deploying to production:
The validator assigns scores (0-100) in each category:
Smart Links (0-100):
Structure (0-100):
Transitions (0-100):
Part Flow (0-100):
Overall (0-100):
✅ Use descriptive, unique link text ✅ Keep link text consistent with headings ✅ Test all links before deployment ✅ Use emojis in headings (they're ignored in matching)
❌ Don't use generic link text like "Click here"
❌ Don't hardcode cell IDs like #cell-5
❌ Don't create circular link references
✅ Validate cell order with structural checks:
# Check adjacency between key sections
part_completion_idx < part_transition_idx + 1 # Must be adjacent
part_transition_idx < next_part_start_idx # Proper sequence
✅ Place reference/utility cells strategically:
✅ Keep technical detail cells within their parent section:
❌ Don't place utility cells between parts ❌ Don't split sections with unrelated content ❌ Don't place completion cells before content
✅ Provide contextual text explaining what's next ✅ Include 3-6 action cards per transition ✅ Link to major upcoming sections ✅ Use consistent formatting
❌ Don't skip transitions between major parts ❌ Don't have too many action cards (> 6) ❌ Don't have too few action cards (< 3)
✅ Number parts sequentially ✅ Use consistent title format ✅ Place summaries at end of parts ✅ Keep part structure uniform
❌ Don't skip part numbers ❌ Don't change title format mid-notebook ❌ Don't place summaries before content
.claude/commands/validate-notebook.md - Command implementationblocks/ipynb-viewer/README.md - Viewer documentationdocs/for-ai/explaining-educational-notebooks.md - Notebook creation guidedocs/for-ai/explaining-presentation-notebooks.md - Presentation notebooksThe validator produces a detailed report:
NOTEBOOK VALIDATION REPORT: notebook-name.ipynb
================================================================
SUMMARY:
Total Cells: 66
Smart Links: 51 (51 valid, 0 broken)
Parts: 7 (sequential)
Transitions: 6 (all with action cards)
Overall Score: 95/100 ✅ PRODUCTION READY
SMART LINKS: ✅ PASS
✓ All 51 smart links resolve correctly
✓ No broken or orphaned links
✓ Action card links validated
STRUCTURE: ✅ PASS
✓ Clear introduction section (8 cells)
✓ 7 parts with consistent structure
✓ Conclusion section present
✓ No gaps or missing sections
TRANSITIONS: ✅ PASS
✓ 6 transition cells with action cards
✓ Part 6 flows naturally (no transition needed)
✓ All action cards have 3-6 links
✓ Contextual text present
PART FLOW: ✅ PASS
✓ Parts numbered 1-7 sequentially
✓ No gaps or duplicates
✓ Summaries at end of each part
✓ Consistent title format
CELL ORDERING: ✅ PASS
✓ All cells in logical sequence
✓ Summaries after content
✓ Transitions before parts
✓ No orphaned cells
PRODUCTION READINESS: ✅ PASS
✓ Metadata complete
✓ Repository URL set
✓ No test content
✓ Valid JSON structure
✓ Appropriate file size
RECOMMENDATIONS:
• Notebook is ready for production deployment
• All validation checks passed
• Quality score: 95/100
Note: This validator is designed for educational and navigation notebooks. Testing notebooks (test.ipynb) may have different structure requirements and are validated separately.
