Back to Details

site-reliability-engineer

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

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.
专注于Claude Skills展示网站的Docusaurus构建健康、MDX验证与部署安全保障。通过提交前验证与自动化健康检查，预防常见的构建失败问题。

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)
适用情况：
  • 提交前markdown/MDX文件验证
  • 排查Liquid模板语法错误
  • 验证SkillHeader组件属性
  • 检查缺失的英雄图片/ZIP文件
  • 构建前链接验证
  • 生成构建后健康报告
  • 诊断Docusaurus构建失败问题
不适用情况：
  • 通用DevOps场景（请使用deployment-engineer）
  • Kubernetes/云基础设施管理（请使用kubernetes-architect）
  • 运行时监控/告警（请使用observability-engineer）
  • 数据库迁移（请使用database-migrations agents）
  • 安全扫描（请使用security-auditor）

Core Problem Domain

核心问题领域

The 5 Recurring Anti-Patterns

5类常见反模式

#ProblemSymptomFix
1Liquid syntax in examplesLiquid templates break MDXWrap in backtick expression
2Unescaped angle brackets
<70
parsed as HTML		Use 
<70
3Wrong SkillHeader propsSSG build failureUse 
fileName
not 
skillId
4Missing critical filesSkill invisible on siteAdd to 
skills.ts
5Cache corruptionPhantom errorsClear 
.docusaurus
, 
build
#问题症状修复方案
1示例中使用Liquid语法Liquid模板破坏MDX解析用反引号表达式包裹
2未转义的尖括号
<70
被解析为HTML		使用
<70
转义
3SkillHeader组件属性错误静态站点生成（SSG）构建失败使用
fileName
而非
skillId
4缺失关键文件技能在站点中不可见将文件添加至
skills.ts
5缓存损坏出现莫名错误清理
.docusaurus
、
build
目录

Quick Start

快速开始

Install Hooks (One-Time)

安装钩子（仅需一次）

bash
npm run install-hooks
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
bash
npm run validate:liquid    # 检查Liquid语法
npm run validate:brackets  # 检查尖括号
npm run validate:props     # 检查SkillHeader属性
npm run validate:all       # 执行所有检查

Clear Cache (When Stuck)

清理缓存（遇到问题时）

bash
rm -rf .docusaurus build node_modules/.cache
npm run build
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
提交前钩子会自动执行以下操作：
  1. Liquid语法检查 - 扫描代码块外的双括号模板
  2. 尖括号检查 - 查找
    <数字
    格式的内容
  3. SkillHeader属性验证 - 校验组件使用是否合规
  4. 必填文件检查 - 确认英雄图片、ZIP文件存在
速度：常规提交场景下耗时不到5秒

Expert vs Novice Approach

专家与新手的处理方式对比

NoviceExpert
Runs full build to checkPre-commit catches 90% in 5 seconds
Manual cache clearingAuto-detect cache issues
Ignores warningsZero-tolerance for broken links
Simple regex validationContext-aware (skips code blocks)
新手做法专家做法
运行完整构建来检查错误提交前钩子在5秒内排查90%的问题
手动清理缓存自动检测缓存问题
忽略构建警告零容忍处理无效链接
使用简单正则验证上下文感知（跳过代码块内容）

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)
表现：执行
npm run build
来检查错误 问题：耗时数分钟而非数秒，反馈缓慢 替代方案：执行
npm run validate:all
（耗时不到30秒）

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)

脚本说明（位于
scripts/
目录）

ScriptPurpose
validate-liquid.js
Detect unescaped Liquid syntax
validate-brackets.js
Detect unescaped angle brackets
validate-skill-props.js
Validate SkillHeader component
脚本用途
validate-liquid.js
检测未转义的Liquid语法
validate-brackets.js
检测未转义的尖括号
validate-skill-props.js
验证SkillHeader组件属性

Troubleshooting Quick Reference

故障排查速查

IssueDiagnosisFix
Hook not running
ls -la .git/hooks/pre-commit
chmod +x
or reinstall
False positivesPattern in code blockCheck ``` markers
Slow validation
time npm run validate:all
Optimize glob patterns
问题诊断方法修复方案
钩子未运行执行
ls -la .git/hooks/pre-commit
检查		执行
chmod +x
赋予权限或重新安装钩子
出现误报匹配内容位于代码块内检查```标记是否正确
验证速度缓慢执行
time npm run validate:all
分析耗时		优化glob匹配规则

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
安装钩子后：
  • 构建失败率：15% → 降至2%以下
  • 错误诊断时间：10分钟 → 缩短至1分钟以内
  • 验证速度：耗时不到30秒

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)
  • references/validation-logic.md
    - 上下文感知检测规则说明
  • references/ci-cd-integration.md
    - GitHub Actions集成、健康报告配置
  • scripts/
    - 可用的验证脚本
预防问题类型：Liquid语法错误 | 尖括号解析失败 | 属性不匹配 | 资源缺失 | 无效链接
搭配使用角色：skill-documentarian（同步协作） | docusaurus-expert（高级配置）