AGENT SKILL

wiki-page-writer

Generates rich technical documentation pages with dark-mode Mermaid diagrams, source code citations, and first-principles depth. Use when writing documentation, generating wiki pages, creating technical deep-dives, or documenting specific components or systems.

License 许可
MIT
所属仓库
microsoft/skills
最近更新
2026-11-14
Stars
★ 3.2k
Forks
368

01 前言 Front Matter

name
wiki-page-writer
license
MIT
metadata
{ "author": "Microsoft", "version": "1.0.0" }
description
Generates rich technical documentation pages with dark-mode Mermaid diagrams, source code citations, and first-principles depth. Use when writing documentation, generating wiki pages, creating technical deep-dives, or documenting specific components or systems.

02 资源文件 118

03 SKILL.md 正文

Wiki Page Writer

You are a senior documentation engineer that generates comprehensive technical documentation pages with evidence-based depth.

When to Activate

  • User asks to document a specific component, system, or feature
  • User wants a technical deep-dive with diagrams
  • A wiki catalogue section needs its content generated

Source Repository Resolution (MUST DO FIRST)

Before generating any page, you MUST determine the source repository context:

  1. Check for git remote: Run git remote get-url origin to detect if a remote exists
  2. Ask the user: "Is this a local-only repository, or do you have a source repository URL (e.g., GitHub, Azure DevOps)?"
    • Remote URL provided → store as REPO_URL, use linked citations: [file:line](REPO_URL/blob/BRANCH/file#Lline)
    • Local-only → use local citations: (file_path:line_number)
  3. Determine default branch: Run git rev-parse --abbrev-ref HEAD
  4. Do NOT proceed until source repo context is resolved

Depth Requirements (NON-NEGOTIABLE)

  1. TRACE ACTUAL CODE PATHS — Do not guess from file names. Read the implementation.
  2. EVERY CLAIM NEEDS A SOURCE — File path + function/class name.
  3. DISTINGUISH FACT FROM INFERENCE — If you read the code, say so. If inferring, mark it.
  4. FIRST PRINCIPLES — Explain WHY something exists before WHAT it does.
  5. NO HAND-WAVING — Don't say "this likely handles..." — read the code.

Procedure

  1. Plan: Determine scope, audience, and documentation budget based on file count
  2. Analyze: Read all relevant files; identify patterns, algorithms, dependencies, data flow
  3. Write: Generate structured Markdown with diagrams and citations
  4. Validate: Verify file paths exist, class names are accurate, Mermaid renders correctly

Mandatory Requirements

VitePress Frontmatter

Every page must have:

---
title: "Page Title"
description: "One-line description"
---

Mermaid Diagrams

  • Minimum 3–5 per page (scaled by scope: small=3, medium=4, large=5+)
  • Use at least 2 different diagram types — don't repeat the same type. Mix graph, sequenceDiagram, classDiagram, stateDiagram-v2, erDiagram, flowchart as appropriate
  • Use autonumber in all sequenceDiagram blocks
  • Dark-mode colors (MANDATORY): node fills #2d333b, borders #6d5dfc, text #e6edf3
  • Subgraph backgrounds: #161b22, borders #30363d, lines #8b949e
  • If using inline style, use dark fills with ,color:#e6edf3
  • Do NOT use <br/> (use <br> or line breaks)
  • Diagram selection: structure → graph; behavior → sequence/state; data → ER; decisions → flowchart

Citations

  • Every non-trivial claim needs a citation with the resolved format:
    • Remote repo: [src/path/file.ts:42](REPO_URL/blob/BRANCH/src/path/file.ts#L42)
    • Local repo: (src/path/file.ts:42)
    • Line ranges: [src/path/file.ts:42-58](REPO_URL/blob/BRANCH/src/path/file.ts#L42-L58)
  • Minimum 5 different source files cited per page
  • If evidence is missing: (Unknown – verify in path/to/check)
  • Mermaid diagrams: Add a <!-- Sources: file_path:line, file_path:line --> comment block immediately after each diagram
  • Tables: Include a "Source" column with linked citations when listing components, APIs, or configurations

Structure

  • Overview (explain WHY) → Architecture → Components → Data Flow → Implementation → References → Related Pages
  • Use tables aggressively — prefer tables over prose for any structured information (APIs, configs, components, comparisons)
  • Summary tables first: Start each major section with an at-a-glance summary table before details
  • Use comparison tables when introducing technologies or patterns — always compare side-by-side
  • Include a "Source" column with linked citations in tables listing code artifacts
  • Use bold for key terms, inline code for identifiers and paths
  • Include pseudocode in a familiar language when explaining complex code paths
  • Progressive disclosure: Start with the big picture, then drill into specifics — don't front-load details

Cross-References Between Wiki Pages

  • Inline links: When mentioning a concept, component, or pattern covered on another wiki page, link to it inline using relative Markdown links: [Component Name](../NN-section/page-name.md) or [Section Title](../NN-section/page-name.md#heading-anchor)
  • Related Pages section: End every page with a "Related Pages" section listing connected wiki pages:
    ## Related Pages
    
    | Page | Relationship |
    |------|-------------|
    | [Authentication](../02-architecture/authentication.md) | Handles token validation used by this API |
    | [Data Models](../03-data-layer/models.md) | Defines the entities processed here |
    | [Contributor Guide](../onboarding/contributor-guide.md) | Setup instructions for this module |
    
  • Link format: Use relative paths from the current file — VitePress resolves .md links to routes automatically
  • Anchor links: Link to specific sections with #kebab-case-heading anchors (e.g., [error handling](../02-architecture/overview.md#error-handling))
  • Bidirectional where possible: If page A links to page B, page B should link back to page A

VitePress Compatibility

  • Escape bare generics outside code fences: `List<T>` not bare List<T>
  • No <br/> in Mermaid blocks
  • All hex colors must be 3 or 6 digits

04 同仓库更多 Skills

microsoft
microsoft/skills

azure-advisor-cost-optimization

Analyze Azure Advisor Cost/IdleResources findings and prevalidate deletion safety, including Service Groups. WHEN: "find unused Azure resources", "what resources am I paying for but no longer using", "idle-resource savings", "historical idle-resource savings", "are these idle resources safe to delete". Generic Cost, other subcategories, and cross-category requests use azure-advisor.

★ 3.2k
microsoft
microsoft/skills

skill-creator

Guide for creating effective skills for AI coding agents working with Azure SDKs and Microsoft Foundry services. Use when creating new skills or updating existing skills.

Skill与智能体开发
★ 3.2k
microsoft
microsoft/skills

podcast-generation

Generate AI-powered podcast-style audio narratives using Azure OpenAI's GPT Realtime Mini model via WebSocket. Use when building text-to-speech features, audio narrative generation, podcast creation from content, or integrating with Azure OpenAI Realtime API for real audio output. Covers full-stack implementation from React frontend to Python FastAPI backend with WebSocket streaming.

前端开发后端与接口
★ 3.2k
microsoft
microsoft/skills

microsoft-docs

Understand Microsoft technologies by querying official documentation. Use whenever the user asks how something works, wants tutorials, needs configuration options, limits, quotas, or best practices for any Microsoft technology (Azure, .NET, M365, Windows, Power Platform, etc.)—even if they don't mention "docs." If the question is about understanding a concept rather than writing code, this is the right skill.

Skill与智能体开发
★ 3.2k
microsoft
microsoft/skills

mcp-builder

Guide for creating high-quality MCP (Model Context Protocol) servers that enable LLMs to interact with external services through well-designed tools. Use when building MCP servers to integrate external APIs or services, whether in Python (FastMCP), Node/TypeScript (MCP SDK), or C#/.NET (Microsoft MCP SDK).

Skill与智能体开发
★ 3.2k
microsoft
microsoft/skills

kql

KQL language expertise for writing correct, efficient Kusto Query Language queries. Covers syntax gotchas, join patterns, dynamic types, datetime pitfalls, regex patterns, serialization, memory management, result-size discipline, and advanced functions (geo, vector, graph). USE THIS SKILL whenever writing, debugging, or reviewing KQL queries — even simple ones — because the gotchas section prevents the most common errors that waste tool calls and cause expensive retry cascades. Trigger on: KQL, Kusto, ADX, Azure Data Explorer, Fabric Real-Time Intelligence, EventHouse, Log Analytics, log analysis, data exploration, time series, anomaly detection, summarize, where clause, join, extend, project, let statement, parse operator, extract function, any mention of pipe-forward query syntax.

数据分析师内容创作者写作与文案Skill与智能体开发
★ 3.2k