К основному содержанию
скилл CX Codex

wiki-ado-convert — скилл для Claude Code: что делает и как установить

Скилл wiki-ado-convert генерирует Node.js-скрипт, который переводит markdown-документацию VitePress и GFM в формат, совместимый с Azure DevOps Wiki. Чинит диаграммы Mermaid, ссылки и фронтматтер перед публикацией в вики.

MIT 4 установок ★ 3 232 обновлён 2026-10-23

Установить в Claude Code · Через Skills CLI (Vercel) Все способы и платформы ↓
npx skills add microsoft/skills --skill wiki-ado-convert -a claude-code
Открыть на GitHub

Что делает wiki-ado-convert

Скилл не редактирует исходные файлы, а создаёт скрипт сборки, который копирует документацию в dist/ado-wiki/ уже в переработанном виде. Он меняет синтаксис Mermaid-диаграмм (например, flowchart на graph, обёртку кода на ::: mermaid), убирает YAML-фронтматтер, который ADO иначе выводит как текст, и превращает ссылки на родительские каталоги с исходным кодом в обычный текст, потому что вики ADO живёт отдельно от репозитория.

Перед генерацией скрипта скилл проверяет git remote get-url origin и спрашивает, локальный это репозиторий или есть адрес удалённого, чтобы сохранить ссылки на источник в переведённых файлах. Скрипт собран как ESM-модуль на встроенных модулях Node.js, без внешних зависимостей, и пропускает каталоги node_modules, .vitepress, .git, dist, build.

Часть диаграмм Mermaid ADO поддерживает не полностью: mindmap, sankey, quadrantChart и block рисоваться не будут, а связи от и к подграфам (subgraph) обрезаются, хотя узлы внутри подграфов работают нормально.

Какие задачи решает

  • перевести VitePress-документацию в формат Azure DevOps Wiki
  • исправить синтаксис диаграмм Mermaid под рендер ADO
  • убрать YAML-фронтматтер, который ADO показывает как текст
  • заменить ссылки на файлы исходного кода на обычный текст
  • собрать скрипт конвертации без внешних npm-зависимостей

Примеры запросов агенту

  • Сгенерируй скрипт, который конвертирует нашу документацию в формат ADO Wiki
  • Собери сборку docs в dist/ado-wiki с исправленными диаграммами Mermaid
  • Проверь, какие диаграммы Mermaid не отрендерятся в Azure DevOps Wiki

Как установить wiki-ado-convert

1Через Skills CLI (Vercel)

npx skills add microsoft/skills --skill wiki-ado-convert -a claude-code

2Вручную: положить файлы

~/.claude/skills/wiki-ado-convert/SKILL.md

Папка скилла целиком; для одного проекта — .claude/skills/wiki-ado-convert/

По шагам, с командами для каждой платформы: Как установить скилл в Claude Code: пять способов

Вопросы о wiki-ado-convert

Как установить wiki-ado-convert в Claude Code?

Выполните npx skills add microsoft/skills --skill wiki-ado-convert -a claude-code, скилл появится в ~/.claude/skills/wiki-ado-convert/SKILL.md.

Что делает wiki-ado-convert?

Создаёт Node.js-скрипт, который копирует markdown-документацию в dist/ado-wiki/, переписывая синтаксис Mermaid, удаляя фронтматтер и исправляя ссылки на исходный код так, чтобы файлы корректно отображались в Azure DevOps Wiki.

Какие диаграммы Mermaid не поддерживает Azure DevOps Wiki?

На 2025 год ADO не рендерит mindmap, sankey, quadrantChart, xychart и block, а связи между подграфами не работают, хотя сами узлы внутри подграфов отображаются корректно.

Исходный текст

SKILL.md · MIT
---
name: wiki-ado-convert
description: Converts VitePress/GFM wiki markdown to Azure DevOps Wiki-compatible format. Generates a Node.js build script that transforms Mermaid syntax, strips front matter, fixes links, and outputs ADO-compatible copies to dist/ado-wiki/.
license: MIT
metadata:
  author: Microsoft
  version: "1.0.0"
---

# ADO Wiki Converter

Generate a Node.js build script that transforms VitePress/GFM markdown documentation into Azure DevOps Wiki-compatible format. The source files remain untouched — the script produces transformed copies in `dist/ado-wiki/`.

## Source Repository Resolution (MUST DO FIRST)

Before generating the build script, resolve the source repository context:

1. **Check for git remote**: Run `git remote get-url origin`
2. **Ask the user**: _"Is this a local-only repository, or do you have a source repository URL?"_
   - Remote URL → store as `REPO_URL`, preserve linked citations in converted output
   - Local → preserve local citations as-is
3. **Do NOT proceed** until resolved

## Why This Is Needed

Azure DevOps Wikis use a markdown dialect that differs from GFM and VitePress in several critical ways. Documentation that renders perfectly in VitePress will have broken diagrams, raw front matter, dead links, and rendering issues when published as an ADO Wiki.

## ADO Wiki Incompatibilities

### CRITICAL — Will Break Rendering

| Issue | VitePress/GFM | ADO Wiki | Fix |
|-------|--------------|----------|-----|
| Mermaid code fences | ` ```mermaid ` ... ` ``` ` | `::: mermaid` ... `:::` | Convert opening/closing fences |
| `flowchart` keyword | `flowchart TD` | `graph TD` | Replace `flowchart` with `graph` (preserve direction) |
| `<br>` in Mermaid labels | `Node[Label<br>Text]` | Not supported | Strip `<br>` variants (replace with space) |
| Long arrows `---->` | `A ---->B` | Not supported | Replace with `-->` |
| YAML front matter | `---` ... `---` at file start | Rendered as visible raw text | Strip entirely |
| Parent-relative source links | `[text](../../src/file.cs)` | Broken (wiki is separate) | Convert to plain text |
| VitePress container directives | `::: tip` / `::: warning` | Not supported | Convert to ADO alert blockquotes `> [!TIP]` / `> [!WARNING]` |

### MODERATE — May Not Render Optimally

| Issue | Notes |
|-------|-------|
| Mermaid `style` directives | ADO's Mermaid version may ignore inline styling. Leave as-is (cosmetic). |
| Mermaid thick arrows `==>` | May work. Leave as-is. |
| Mermaid dotted arrows `-.->` | May work. Leave as-is. |
| Subgraph linking | Links to/from subgraphs not supported, but nodes inside subgraphs work fine. |

### NOT AN ISSUE (Compatible As-Is)

- ✅ Standard markdown tables, blockquotes, horizontal rules
- ✅ Unicode emoji, fenced code blocks with language identifiers
- ✅ Same-directory relative links (`./other-page.md`)
- ✅ External HTTP/HTTPS links
- ✅ Bold, italic, strikethrough, inline code
- ✅ Lists (ordered, unordered, nested), headings 1-6
- ✅ Images with relative paths

## ADO Wiki Mermaid Supported Diagram Types

As of 2025:
- ✅ `sequenceDiagram`, `gantt`, `graph` (NOT `flowchart`), `classDiagram`
- ✅ `stateDiagram`, `stateDiagram-v2`, `journey`, `pie`, `erDiagram`
- ✅ `requirementDiagram`, `gitGraph`, `timeline`
- ❌ `mindmap`, `sankey`, `quadrantChart`, `xychart`, `block`

## Build Script Structure

The generated script should be a **Node.js ESM module** (`scripts/build-ado-wiki.js`) using only built-in Node.js modules (`node:fs/promises`, `node:path`, `node:url`). No external dependencies.

### Transformation Functions

#### 1. Strip YAML Front Matter

Remove `---` delimited YAML blocks at file start. ADO renders these as visible text.

```javascript
function stripFrontMatter(content) {
  if (!content.startsWith('---')) return content;
  const endIndex = content.indexOf('\n---', 3);
  if (endIndex === -1) return content;
  let rest = content.slice(endIndex + 4);
  if (rest.startsWith('\n')) rest = rest.slice(1);
  return rest;
}
```

#### 2. Convert Mermaid Blocks

Process line-by-line, tracking mermaid block state. Apply fixes ONLY inside mermaid blocks:

- Opening: ` ```mermaid ` → `::: mermaid`
- Closing: ` ``` ` → `:::`
- `flowchart` → `graph` (preserve direction: TD, LR, TB, RL, BT)
- Strip `<br>`, `<br/>`, `<br />` (replace with space)
- Replace long arrows (`---->` with 4+ dashes) with `-->`

```javascript
function convertMermaidBlocks(content) {
  const lines = content.split('\n');
  const result = [];
  let inMermaid = false;

  for (const line of lines) {
    const trimmed = line.trimEnd();

    if (!inMermaid && /^```mermaid\s*$/.test(trimmed)) {
      result.push('::: mermaid');
      inMermaid = true;
      continue;
    }

    if (inMermaid && /^```\s*$/.test(trimmed)) {
      result.push(':::');
      inMermaid = false;
      continue;
    }

    if (inMermaid) {
      let fixed = line;
      fixed = fixed.replace(/^(\s*)flowchart(\s+)/, '$1graph$2');
      fixed = fixed.replace(/<br\s*\/?>/gi, ' ');
      fixed = fixed.replace(/-{4,}>/g, '-->');
      result.push(fixed);
    } else {
      result.push(line);
    }
  }

  return result.join('\n');
}
```

#### 3. Convert Parent-Relative Source Links

Convert `[text](../path)` to plain text. Preserves same-directory `.md` links and external URLs.

```javascript
function convertSourceLinks(content) {
  return content.replace(
    /\[([^\]]*)\]\(\.\.\/[^)]*\)/g,
    (match, linkText) => linkText
  );
}
```

#### 4. Convert VitePress Container Directives (Optional)

Convert `::: tip` / `::: warning` / `::: danger` to ADO alert blockquotes:

```javascript
function convertContainerDirectives(content) {
  // ::: tip → > [!TIP]
  // ::: warning → > [!WARNING]
  // ::: danger → > [!CAUTION]
  // ::: info → > [!NOTE]
  // closing ::: → (blank line)
}
```

### Script Main Flow

```javascript
async function main() {
  const files = await collectMarkdownFiles(ROOT);
  const stats = { frontMatter: 0, mermaid: 0, sourceLinks: 0, containers: 0 };

  for (const filePath of files) {
    let content = await readFile(filePath, 'utf-8');
    content = stripFrontMatter(content);
    content = convertMermaidBlocks(content);
    content = convertSourceLinks(content);

    const outPath = join(OUTPUT, relative(ROOT, filePath));
    await mkdir(dirname(outPath), { recursive: true });
    await writeFile(outPath, content, 'utf-8');
  }

  // Print transformation statistics
}
```

### Skip Directories

The script should skip: `node_modules`, `.vitepress`, `.git`, `dist`, `build`, `out`, `target`, and any non-documentation directories.

### npm Script Integration

```json
{
  "scripts": {
    "build:ado": "node scripts/build-ado-wiki.js"
  }
}
```

## Verification Checklist

After the script runs, verify:
1. File count in `dist/ado-wiki/` matches source (minus skipped dirs)
2. Zero ` ```mermaid ` fences remaining — all converted to `::: mermaid`
3. Zero `flowchart` keywords remaining — all converted to `graph`
4. No YAML front matter in output files
5. Parent-relative links converted to plain text
6. Same-directory `.md` links preserved
7. Directory structure preserved
8. Non-markdown files (images, etc.) copied as-is
9. `index.md` at root is a proper wiki home page (NOT a placeholder)

## Index Page Generation (CRITICAL)

The ADO Wiki's `index.md` **MUST be a proper wiki landing page**, NOT a generic placeholder with "TODO" text.

### Logic

1. **If VitePress source has `index.md`**: Transform it (strip front matter, strip VitePress hero/features blocks). If meaningful content remains, use it.
2. **If no meaningful content remains** (empty after stripping, or only VitePress hero markup): Generate a proper landing page with:
   - Project title as `# heading`
   - Overview paragraph (from README or wiki overview page)
   - Quick Navigation table (Section, Description columns linking to wiki sections)
   - Links to onboarding guides if they exist
3. **NEVER leave a placeholder** — if `index.md` contains "TODO:", "Give a short introduction", or similar placeholder text, **replace it entirely**

### ADO Wiki `.order` Files

Generate `.order` files in each directory to control sidebar ordering:
- Onboarding guides first, then numbered sections
- List page names without `.md` extension, one per line

## Citation & Diagram Preservation

The converted ADO wiki must maintain the same quality standards:

- **Linked citations** (`[file:line](URL)`) are standard markdown — preserve them as-is
- **`<!-- Sources: ... -->` comment blocks** after Mermaid diagrams — preserve (HTML comments work in ADO)
- **Tables with "Source" columns** — preserve as-is (standard markdown tables)
- **Mermaid diagrams** — convert fences only; diagram content, types, and structure are preserved
- All Mermaid diagram types supported by ADO (graph, sequenceDiagram, classDiagram, stateDiagram, erDiagram, etc.) pass through unchanged

## Important Notes

- **Source files are NEVER modified** — only copies in `dist/ado-wiki/`
- **Images must be copied too** — if source has images, copy them with same relative paths
- The script should work with **any VitePress wiki**, not just this specific one
- Print statistics at the end showing count of each transformation type
- Script uses zero external dependencies — only Node.js builtins

© Microsoft · MIT · microsoft/skills

Похожие скиллы

Все скиллы по теме «Тексты и документация» →
ado-pipeline-best-practices JosiahSiegel Скилл ado-pipeline-best-practices учит ассистента проектировать, проверять и оптимизировать YAML-пайплайны Azure DevOps по стандартам индустрии. CX Codex +1 182установок Azure DevOps (ADO) microsoft Azure DevOps (ADO) — MCP-сервер для Claude Code, связывающий ИИ-агентов с Azure DevOps для запросов задач, сборок, репозиториев и вики из диалога в среде разработки. CX Codex +1 ★ 2 092звёзд репо azure-devops MicrosoftDocs Помогает администрировать Azure DevOps, настраивать пулы и разбирать сбои. Подключается при настройке прав, аналитики OData и серверов TFS. CX Codex +1 442установок azure-boards MicrosoftDocs Помогает работать с Azure Boards: задачами, WIQL-запросами, интеграциями и настройками. Запрашивает документацию Microsoft для разбора конкретной проблемы. CX Codex +1 242установок adf-master JosiahSiegel Скилл adf-master помогает настроить CI/CD для Azure Data Factory, написать скрипты PrePostDeploymentScript и подготовить шаблоны ARM для развёртывания. CX Codex +1 164установок azure-devops-specialist qdhenry Субагент azure-devops-specialist помогает управлять инфраструктурой Microsoft Azure и пайплайнами CI/CD через команды az и вызовы MCP. Пригодится при настройке сервисов, деплое и валидации шаблонов ARM. CX Codex ★ 1 357звёзд репо

Из того же набора250

Весь набор →
azure-identity-rust Скилл azure-identity-rust подсказывает агенту, как подключить Microsoft Entra ID к Rust-приложению: какой credential взять для локальной разработки, а какой для продакшена. CX Codex +1 5установок azure-eventhub-rust Скилл azure-eventhub-rust для Claude Code помогает работать с крейтом azure_messaging_eventhubs в Rust: настраивать стриминг событий, отправлять батчи и читать данные из партиций. CX Codex +1 5установок azure-cosmos-rust Скилл azure-cosmos-rust подсказывает агенту, как работать с Azure Cosmos DB NoSQL API из Rust: CRUD документов, контейнеры, ключи разделов и аутентификация. CX Codex +1 5установок pydantic-models-py Скилл pydantic-models-py для Claude Code задаёт структуру моделей Pydantic v2 по шаблону из пяти вариантов: Base, Create, Update, Response и InDB. Генерирует схемы запросов и ответов API с наследованием, чтобы не дублировать поля. CX Codex +1 5установок azure-validate Скилл azure-validate для Claude Code и GitHub Copilot проверяет готовность проекта к развёртыванию в Azure. Запускает предварительные проверки конфигурации, инфраструктуры и прав доступа. CX Codex +1 4установок azure-deploy Скилл azure-deploy для Claude Code и GitHub Copilot, который выполняет деплой уже подготовленного приложения в Azure. CX Codex +1 4установок fastapi-router-py Скилл fastapi-router-py для Claude Code создаёт роутеры FastAPI с CRUD-операциями, аутентификацией и моделями ответов. Создаёт REST API и новые защищённые маршруты. CX Codex +1 4установок azure-storage Скилл azure-storage помогает работать с хранилищами Azure: загружать блобы, выбирать уровни доступа и настраивать очереди. Пригодится при настройке инфраструктуры и работе с SDK. CX Codex +1 3установок

Ещё в каталоге

Спонсоры проекта

Компании, которые помогают держать аналитику открытой