SKILL.md
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 patternsreferences/ci-cd-integration.md - GitHub Actions, health reportsscripts/ - Working validation scripts
Prevents: Liquid errors | Angle bracket failures | Prop mismatches | Missing assets | Broken links
Use with: skill-documentarian (sync) | docusaurus-expert (advanced config)
