site-reliability-engineer — Claude Code skill for Docusaurus checks
The site-reliability-engineer skill checks Docusaurus builds for MDX issues, validates links, and helps catch site problems before deployment.
MIT 196 installs ★ 274 updated 2026-10-30
npx skills add curiositech/some_claude_skills --skill site-reliability-engineer -a claude-codeWhat site-reliability-engineer does
Before a commit, the skill checks MDX for Liquid syntax, unescaped angle brackets, and incorrect SkillHeader props. It also looks for required hero images and ZIP files. Install the hook with npm run install-hooks.
Run individual checks with npm run validate:liquid, npm run validate:brackets, or npm run validate:props; npm run validate:all runs the full set. The skill also covers link checks before a build and health reports afterward. Validation scripts live in scripts/. A full npm run build is not the quick pre-commit check this skill is designed to provide.
Its scope is Docusaurus, including the Claude Skills showcase site. The README directs Kubernetes, cloud infrastructure, and runtime monitoring work to other skills.
What it helps with
- catch Liquid syntax that breaks MDX
- validate
SkillHeadercomponent props - find missing hero images or ZIP files
- check links before a build
- diagnose Docusaurus build failures
Example prompts for the agent
- Check my MDX changes for Liquid syntax issues before I commit.
- Validate the links and report site health after the Docusaurus build.
- Run the complete validation with
npm run validate:all.
How to install site-reliability-engineer
1Skills CLI (Vercel)
npx skills add curiositech/some_claude_skills --skill site-reliability-engineer -a claude-code2Manually: put the files in place
~/.claude/skills/site-reliability-engineer/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/site-reliability-engineer/
1Skills CLI (Vercel)
npx skills add curiositech/some_claude_skills --skill site-reliability-engineer -a codex2Manually: put the files in place
.agents/skills/site-reliability-engineer/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add curiositech/some_claude_skills --skill site-reliability-engineer -a cursor2Manually: put the files in place
.cursor/skills/site-reliability-engineer/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install curiositech/some_claude_skills .claude/skills/site-reliability-engineer2Manually: put the files in place
.github/skills/site-reliability-engineer/SKILL.md1Skills CLI (Vercel)
npx skills add curiositech/some_claude_skills --skill site-reliability-engineer -a gemini-cli2Platform CLI
gemini skills install https://github.com/curiositech/some_claude_skills --path .claude/skills/site-reliability-engineerManually: put the files in place
.devin/skills/site-reliability-engineer/SKILL.mdThe legacy .windsurf/skills/ path still works
Skills CLI (Vercel)
npx skills add curiositech/some_claude_skills --skill site-reliability-engineer -a opencodeClaude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
Step by step, with commands for each platform: How to install skills in Claude Code: five ways
Questions about site-reliability-engineer
How do I install site-reliability-engineer in Claude Code?
Run npx skills add curiositech/some_claude_skills --skill site-reliability-engineer -a claude-code. The skill file will be at ~/.claude/skills/site-reliability-engineer/SKILL.md.
What does site-reliability-engineer do?
It checks MDX, links, SkillHeader props, and required site files. It can also help diagnose Docusaurus build failures and report site health after a build.
Which checks can I run manually?
Use npm run validate:liquid, npm run validate:brackets, or npm run validate:props for individual checks. Run npm run validate:all for the complete set.
Source text
SKILL.md · MIT
---
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
metadata:
category: DevOps & Site Reliability
pairs-with:
- skill: devops-automator
reason: CI/CD for site deployments
- skill: skill-documentarian
reason: Maintain skill documentation quality
tags:
- docusaurus
- build-health
- mdx
- validation
- deployment
---
# 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)
```bash
npm run install-hooks
```
### Manual Validation
```bash
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)
```bash
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)
© curiositech · MIT · curiositech/some_claude_skills