mdx-sanitizer — скилл для Claude Code: что делает и как установить
Скилл mdx-sanitizer для Claude Code экранирует в MDX конструкции, которые MDX 2.x принимает за JSX, перед сборкой Docusaurus. Исправляет ошибки unexpected token в прекоммит-хуках и билде.
MIT 202 установок ★ 274 обновлён 2026-09-06
npx skills add curiositech/some_claude_skills --skill mdx-sanitizer -a claude-codeЧто делает mdx-sanitizer
Скилл находит и исправляет конструкции, которые MDX 2.x принимает за JSX: неэкранированные < и > в тексте, дженерики вроде Promise<T>, операторы сравнения <= и >=, стрелки --> и псевдотеги <link>. Работает в трёх точках: при синхронизации из .claude/skills/ в website/docs/, в git-хуке перед коммитом через validate-brackets.js и на этапе билда в prebuild.
Внутри код в обратных кавычках и фенсированные блоки не трогает. Заменяет скобки на HTML-сущности (<, >), чтобы не сломать рендеринг. Запуск npm run sanitize:mdx проверяет файлы, npm run fix:mdx исправляет на месте. Без FFmpeg, Python или внешних API.
Какие задачи решает
- экранировать дженерики TypeScript и операторы сравнения в MDX перед билдом Docusaurus
- зафиксить падения прекоммит-хука на невалидных угловых скобках
- защитить контент от парсинга как JSX при наличии шаблонов Liquid
Примеры запросов агенту
- Проверь MDX-файлы в
website/docs/на незакрытые скобки и дженерики. - Исправь ошибки
unexpected token <в файлах.mdxкаталогаdocs/. - Запусти
npm run sanitize:mdx -- --fixдля всех файлов проекта.
Как установить mdx-sanitizer
1Через Skills CLI (Vercel)
npx skills add curiositech/some_claude_skills --skill mdx-sanitizer -a claude-code2Вручную: положить файлы
~/.claude/skills/mdx-sanitizer/SKILL.mdПапка скилла целиком; для одного проекта — .claude/skills/mdx-sanitizer/
1Через Skills CLI (Vercel)
npx skills add curiositech/some_claude_skills --skill mdx-sanitizer -a codex2Вручную: положить файлы
.agents/skills/mdx-sanitizer/SKILL.mdДля всех проектов — ~/.agents/skills/
1Через Skills CLI (Vercel)
npx skills add curiositech/some_claude_skills --skill mdx-sanitizer -a cursor2Вручную: положить файлы
.cursor/skills/mdx-sanitizer/SKILL.mdCursor читает и .agents/skills/, и .claude/skills/
1GitHub CLI
gh skill install curiositech/some_claude_skills .claude/skills/mdx-sanitizer2Вручную: положить файлы
.github/skills/mdx-sanitizer/SKILL.md1Через Skills CLI (Vercel)
npx skills add curiositech/some_claude_skills --skill mdx-sanitizer -a gemini-cli2Командой платформы
gemini skills install https://github.com/curiositech/some_claude_skills --path .claude/skills/mdx-sanitizerВручную: положить файлы
.devin/skills/mdx-sanitizer/SKILL.mdСтарый путь .windsurf/skills/ тоже читается
Через Skills CLI (Vercel)
npx skills add curiositech/some_claude_skills --skill mdx-sanitizer -a opencodeClaude.ai
Упакуйте папку в zip и загрузите в Settings → Capabilities → Skills
По шагам, с командами для каждой платформы: Как установить скилл в Claude Code: пять способов
Вопросы о mdx-sanitizer
Как установить mdx-sanitizer в Claude Code?
Выполни npx skills add curiositech/some_claude_skills --skill mdx-sanitizer -a claude-code, затем открой ~/.claude/skills/mdx-sanitizer/SKILL.md.
Что делает mdx-sanitizer?
Экранирует угловые скобки, дженерики TypeScript, операторы сравнения и шаблоны Liquid в MDX-файлах, чтобы Docusaurus не принял их за JSX и не упал при билде.
Когда mdx-sanitizer нужен?
Когда прекоммит-хук или билд Docusaurus падает с ошибкой unexpected token на угловых скобках, дженериках или шаблонах {{ }}.
Исходный текст
SKILL.md · MIT
---
name: mdx-sanitizer
description: Sanitize MDX content for Docusaurus builds. Fixes unescaped angle brackets (<, >, <=, >=), Liquid/Nunjucks template syntax ({{ }}), TypeScript generics (Promise<T>), and inline code backtick edge cases. Use when pre-commit hooks fail on bracket or Liquid validation, or when MDX/JSX build errors reference unexpected tokens. NOT for general markdown linting or prose editing.
allowed-tools:
- Read
- Write
- Edit
- Bash
- Glob
- Grep
version: 1.0.0
triggers:
- mdx error
- angle bracket
- jsx parsing
- build failure mdx
- escape angle brackets
- sanitize markdown
metadata:
category: DevOps & Automation
tags:
- mdx
- docusaurus
- markdown
- build-tools
- sanitization
pairs-with:
- skill: site-reliability-engineer
reason: MDX build failures are a primary Docusaurus deployment blocker that SRE validates
- skill: technical-writer
reason: Technical writers produce the MDX content that needs sanitization for safe rendering
- skill: skill-documentarian
reason: Skill documentation in MDX format requires sanitization before website deployment
---
# MDX Sanitizer
Comprehensive MDX content sanitizer that prevents JSX parsing errors caused by angle brackets, generics, and other conflicting patterns.
## The Problem
MDX 2.x treats unescaped `<` and `{` as JSX syntax. This causes build failures when content contains:
- **TypeScript generics**: `Promise<T>`, `Array<string>`, `Map<K, V>`
- **Comparisons**: `<100ms`, `<=`, `>=`
- **Arrows**: `-->`, `<--`, `->`
- **Invalid tags**: `<link>` in prose, `<tag>` placeholders
- **Empty brackets**: `<>`
## Solution Architecture
This skill implements a three-layer defense:
### 1. Sync-Time Sanitization (Proactive)
Content is sanitized when syncing from `.claude/skills/` to `website/docs/`:
- `syncSkillDocs.ts` - Main skill files
- `syncSkillSubpages.ts` - Reference files
- `doc-generator.ts` - Generated docs
### 2. Pre-Commit Validation (Reactive)
The git pre-commit hook validates files before commit using `validate-brackets.js`.
### 3. Build-Time Validation (Final Check)
`npm run validate:all` runs as part of `prebuild` to catch any issues.
## Usage
### Check for Issues (Dry Run)
```bash
cd website
npm run sanitize:mdx
# or with verbose output
npm run sanitize:mdx -- --verbose
```
### Fix All Issues
```bash
cd website
npm run sanitize:mdx -- --fix
# or shorthand
npm run fix:mdx
```
### Programmatic API
```typescript
import { sanitizeForMdx, validateMdxSafety, isMdxSafe } from './lib/mdx-sanitizer';
// Sanitize content
const result = sanitizeForMdx(content, { useHtmlEntities: true });
if (result.modified) {
console.log(`Fixed ${result.issues.length} issues`);
fs.writeFileSync(path, result.content);
}
// Validate without modifying
const issues = validateMdxSafety(content, 'path/to/file.md');
// Quick check
if (!isMdxSafe(content)) {
// Handle issues
}
```
## Escaping Strategies
The sanitizer uses HTML entities for maximum compatibility:
| Pattern | Original | Escaped |
|---------|----------|---------|
| Less-than | `<` | `<` |
| Greater-than | `>` | `>` |
| Generics | `<T>` | `&lt;T&gt;` |
| Comparison | `<=` | `&lt;=` |
Content inside code blocks (`` ``` `` or `` ` ``) is automatically protected and never escaped.
## Files Modified
- `website/scripts/lib/mdx-sanitizer.ts` - Core sanitizer module
- `website/scripts/sanitize-mdx.ts` - CLI wrapper
- `website/scripts/syncSkillDocs.ts` - Integration
- `website/scripts/syncSkillSubpages.ts` - Integration
- `website/scripts/lib/doc-generator.ts` - Integration
- `website/package.json` - npm scripts
## Patterns Detected
1. **Less-than before digit**: `<100`, `<0.5ms`
2. **Comparison operators**: `<=`, `>=`
3. **Empty brackets**: `<>`
4. **Arrows**: `<--`, `-->`
5. **Generic types**: `Promise<T>`, `Array<string>`
6. **Space after less-than**: `< value`
7. **Invalid pseudo-tags**: `<link>`, `<tag>` (not valid HTML)
## Troubleshooting
### Build Still Fails After Running Sanitizer
1. Clear Docusaurus cache: `npm run clear`
2. Re-run sanitizer: `npm run sanitize:mdx -- --fix`
3. Rebuild: `npm run build`
### False Positives
If valid JSX components are being escaped:
- Ensure they use PascalCase (e.g., `<MyComponent>`)
- Check they're valid HTML5 elements
### Manual Escaping
For edge cases, manually escape in source:
- Use backticks for inline code: `` `<T>` ``
- Use fenced code blocks for multi-line
- Use HTML entities: `<` and `>`
## Sources
- [MDX Troubleshooting](https://mdxjs.com/docs/troubleshooting-mdx/)
- [TypeDoc MDX Issues](https://github.com/tgreyuk/typedoc-plugin-markdown/issues/167)
© curiositech · MIT · curiositech/some_claude_skills