Site Reliability Engineer

Expert in Docusaurus build health, MDX validation, and deployment safety for the Claude Skills showcase website. Prevents common build failures through pre-commit validation and automated health checks.

When to Use

Use for:

Pre-commit validation of markdown/MDX files Catching Liquid template syntax errors Validating SkillHeader component props Checking for missing hero images/ZIP files Pre-build link validation Post-build health reports Diagnosing Docusaurus build failures

Do NOT use for:

General DevOps (use deployment-engineer) Kubernetes/cloud infrastructure (use kubernetes-architect) Runtime monitoring/alerting (use observability-engineer) Database migrations (use database-migrations agents) Security scanning (use security-auditor) Core Problem Domain The 5 Recurring Anti-Patterns

Problem Symptom Fix

1 Liquid syntax in examples Liquid templates break MDX Wrap in backtick expression 2 Unescaped angle brackets <70 parsed as HTML Use <70 3 Wrong SkillHeader props SSG build failure Use fileName not skillId 4 Missing critical files Skill invisible on site Add to skills.ts 5 Cache corruption Phantom errors Clear .docusaurus, build Quick Start Install Hooks (One-Time) npm run install-hooks

Manual Validation npm run validate:liquid # Liquid syntax npm run validate:brackets # Angle brackets npm run validate:props # SkillHeader props npm run validate:all # All checks

Clear Cache (When Stuck) rm -rf .docusaurus build node_modules/.cache npm run build

Pre-Commit Validation

The pre-commit hook automatically:

Liquid syntax - Scans for double-brace templates outside code blocks Angle brackets - Finds <digit patterns SkillHeader props - Validates component usage Required files - Checks hero images, ZIPs exist

Speed: Under 5 seconds for typical commits

Expert vs Novice Approach Novice Expert Runs full build to check Pre-commit catches 90% in 5 seconds Manual cache clearing Auto-detect cache issues Ignores warnings Zero-tolerance for broken links Simple regex validation Context-aware (skips code blocks) Anti-Patterns Anti-Pattern: Full Build for Validation

What it looks like: npm run build to check for errors Why wrong: Minutes vs seconds, slow feedback Instead: npm run validate:all (under 30 seconds)

Anti-Pattern: Ignoring Build Warnings

What it looks like: "Build succeeded, ship it!" (ignoring warnings) Why wrong: Broken links = poor UX, tech debt Instead: Post-build validation fails on warnings

Anti-Pattern: Naive Regex Validation

What it looks like: /{{.*?}}/ (matches in code blocks too) Why wrong: False positives in code examples Instead: Track code block state, skip protected regions

Scripts (in scripts/ folder) Script Purpose validate-liquid.js Detect unescaped Liquid syntax validate-brackets.js Detect unescaped angle brackets validate-skill-props.js Validate SkillHeader component Troubleshooting Quick Reference Issue Diagnosis Fix Hook not running ls -la .git/hooks/pre-commit chmod +x or reinstall False positives Pattern in code block Check ``` markers Slow validation time npm run validate:all Optimize glob patterns Success Metrics

After installing hooks:

Build failure rate: 15% → under 2% Time to diagnose errors: 10 min → under 1 min Validation speed: Under 30 seconds Reference Files references/validation-logic.md - Context-aware detection patterns references/ci-cd-integration.md - GitHub Actions, health reports scripts/ - Working validation scripts

Prevents: Liquid errors | Angle bracket failures | Prop mismatches | Missing assets | Broken links

Use with: skill-documentarian (sync) | docusaurus-expert (advanced config)