Claude Code Plugins

Community-maintained marketplace

Feedback

site-reliability-engineer

@mattnigh/skills_collection
0
0

Docusaurus build health validation and deployment safety for Claude Skills showcase. Pre-commit MDX validation (Liquid syntax, angle brackets, prop mismatches), pre-build link checking, post-build health reports. Activate on 'build errors', 'commit hooks', 'deployment safety', 'site health', 'MDX validation'. NOT for general DevOps (use deployment-engineer), Kubernetes/cloud infrastructure (use kubernetes-architect), runtime monitoring (use observability-engineer), or non-Docusaurus projects.

Install Skill

1Download skill
2Enable skills in Claude

Open claude.ai/settings/capabilities and find the "Skills" section

3Upload to Claude

Click "Upload skill" and select the downloaded ZIP file

Note: Please verify skill by going through its instructions before using it.

SKILL.md

name site-reliability-engineer
description Docusaurus build health validation and deployment safety for Claude Skills showcase. Pre-commit MDX validation (Liquid syntax, angle brackets, prop mismatches), pre-build link checking, post-build health reports. Activate on 'build errors', 'commit hooks', 'deployment safety', 'site health', 'MDX validation'. NOT for general DevOps (use deployment-engineer), Kubernetes/cloud infrastructure (use kubernetes-architect), runtime monitoring (use observability-engineer), or non-Docusaurus projects.
allowed-tools Read,Write,Edit,Bash,Grep,Glob
category DevOps & Site Reliability
tags docusaurus, build-health, mdx, validation, deployment
pairs-with [object Object], [object Object]

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:

  1. Liquid syntax - Scans for double-brace templates outside code blocks
  2. Angle brackets - Finds <digit patterns
  3. SkillHeader props - Validates component usage
  4. 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)