Generate Wiki

Generate Wiki Skill

Role Definition: You are a senior Java architect skilled in:

• Analyzing code structure of gRPC + Java microservice projects
• Understanding the mapping between proto definitions and Java implementations
• Writing clear and accurate technical documentation
• Identifying core business logic and key code paths

Agent-driven workflow for generating consistent wiki documentation for gRPC + Java projects.

What This Skill Does

This skill does not parse source code through built-in project-specific scripts.

Instead, it instructs the Agent to:

• inspect the repository with code-search and file-reading tools
• identify gRPC services, proto definitions, and Java implementations
• generate a consistent wiki structure
• follow the provided style and output requirements

Important: Not a Generic Wiki Template

This skill provides a framework, not a one-size-fits-all solution. Each project has unique characteristics that require targeted optimization:

• Different business domains — e-commerce, fintech, logistics, etc. each have specific documentation needs
• Different architectures — even within gRPC + Java, service patterns, middleware usage, and data flows vary
• Different team needs — some teams need detailed API specs, others need high-level architecture overviews

You should customize the generated wiki based on:

1. Your project's specific business logic and domain terminology
2. The actual service dependencies and data flows in your codebase
3. Your team's documentation standards and review requirements
4. The level of detail your developers need (API reference vs. architecture guide)

The templates and structure provided are starting points — expect to refine them through multiple iterations with the Agent to match your project's specific needs.

Required Workflow

See [docs/workflow.md](docs/workflow.md) for the complete Agent workflow.

Summary

Phase 1: Discovery - Find all components first

1. Scan - Find ALL proto, PowerJob, and Pulsar files
2. Inventory - Record ALL services, methods, messages, jobs, consumers
3. Output - List complete component inventory before generating

Phase 2: Generate Component Pages - Create detail documentation (with parallel optimization)

1. Check Component Count - If total components ≥ 50, enable parallel generation
2. Generate - Create wiki pages for ALL discovered components:

• Every RPC method → service/{Service}/{Method}.html
• Every PowerJob processor → job/{JobClass}/execute.html (if present)
• Every Pulsar consumer → consumer/{Consumer}/index.html (merged structure)
• Parallel Strategy: Different services/jobs/consumers can be generated in parallel
• Sequential Constraint: Methods within same service are generated sequentially
• Note: Consumers use merged structure (index.html only, no separate consume.html)

Phase 3: Generate Summary Pages (LAST) - Aggregate from finalized generated content

1. Re-read Generated Component Pages - After all gRPC, PowerJob, and Pulsar pages are complete, re-read:

• service/**/index.html and service/**/*.html
• job/index.html and job/*/index.html (if present)
• consumer/index.html and consumer/*/index.html (if present)
• the component inventory manifest produced during Phase 1

1. Generate System Architecture (01-system-architecture.html) - Based on completed component pages, all discovered services, jobs, consumers, dependencies, and message flows
2. Generate Core Features (02-core-features.html) - Based on completed gRPC, PowerJob, and Pulsar component analysis, grouped into business capabilities
3. Generate ER Diagram (03-er-diagram.html) - Based on ALL proto message types plus completed service method request/response mappings
4. Verify - Run the quality checklist before finishing

Important: System Architecture, Core Features, and ER Diagram MUST be generated AFTER all component pages are complete. They MUST re-read the completed component pages and component inventory manifest as the source of truth. Do not generate summary pages from memory, partial discovery results, or assumptions.

Output Requirements

Output Format Requirements

All generated pages must be rendered as HTML, not raw markdown files.

Generated structure:

wiki/
├── index.html              # Main navigation page (renders all content)
├── assets/
│   ├── css/style.css       # Unified styling (includes collapsible nav styles)
│   ├── js/nav-data.js      # Navigation tree data (generated from components)
│   └── js/nav.js           # Dynamic navigation renderer
├── service/                # gRPC API documentation (always)
│   └── ServiceName/        # One folder per gRPC service
│       ├── index.html      # Service overview page
│       ├── MethodName.html # One HTML file per RPC method
│       └── ...
├── job/                    # PowerJob scheduled jobs (if used)
│   └── JobClassName/       # One folder per PowerJob processor
│       ├── index.html      # Job overview page
│       └── execute.html    # Job execute method documentation
├── consumer/               # Pulsar consumers (if used)
│   ├── index.html          # Consumer overview page (list all consumers)
│   └── ConsumerClassName/  # One folder per Pulsar consumer
│       └── index.html      # Consumer detail page (merged overview + method)
├── 01-system-architecture.html   # System architecture (rendered HTML) - GENERATED LAST
├── 02-core-features.html         # Core features (rendered HTML) - GENERATED LAST
└── 03-er-diagram.html            # ER diagram (rendered HTML) - GENERATED LAST

Note:

• job/ and consumer/ directories are created only when the project actually uses PowerJob or Pulsar respectively.
• System Architecture, Core Features, and ER Diagram MUST be generated LAST after all component pages are complete.
• Phase 3 source of truth: before writing 01-system-architecture.html, 02-core-features.html, or 03-er-diagram.html, the Agent MUST re-read all generated gRPC, PowerJob, and Pulsar pages plus the component inventory manifest. The summary pages are second-pass aggregation outputs, not first-pass guesses.
• nav-data.js must be regenerated whenever components are added/removed/renamed.

Rendering approach (choose one):

1. Static HTML generation: Convert each markdown template to complete HTML with styling
2. SPA with router: Single index.html that dynamically loads and renders markdown content

If using approach #2 (SPA):

• Only one index.html at root
• Markdown files can be kept as .md but must be rendered in-browser
• URL routing must work (e.g., /#/service/UserService/GetUser)

Important: Users should never see raw markdown or download .md files when clicking links.

Parallel Generation Strategy

When to use parallel generation:

Total Components = gRPC Methods + PowerJob Processors + Pulsar Consumers

If Total Components >= 50:
    → Enable SUBAGENT PARALLEL generation
    → Improves speed by 3-5x on large projects

Independence Rules (What can be parallel):

| Component Type | Parallel Strategy | Constraint | |---------------|-------------------|------------| | gRPC Methods | Parallel across different services | Sequential within same service | | PowerJob Processors | Always parallel | Independent jobs | | Pulsar Consumers | Always parallel | Independent consumers |

Example Batch Strategy:

# Batch 1 (Parallel)
- ServiceA.GetUser
- ServiceB.CreateOrder
- ServiceC.UpdateInventory
- OrderSyncJob
- OrderEventConsumer

# Batch 2 (Parallel)
- ServiceA.ListUsers
- ServiceB.CancelOrder
- ServiceC.ListInventory
- DataCleanJob
- PaymentResultConsumer

# ... continue until all components processed

Subagent Implementation:

// Determine if parallel generation is needed
const totalComponents = grpcMethods.length + powerjobCount + pulsarCount;
const useParallel = totalComponents >= 50;

if (useParallel) {
    // Group independent components into batches
    const batches = createBatches(components);
    
    for (const batch of batches) {
        // Launch subagent for each component in batch
        const subagents = batch.map(component => 
            Agent({
                description: `Generate ${component.type} page: ${component.name}`,
                prompt: `
                    Generate wiki page for ${component.name}
                    Type: ${component.type}
                    Template: ${component.template}
                    Metadata: ${JSON.stringify(component.metadata)}
                    
                    Save to: ${component.outputPath}
                `
            })
        );
        
        // Wait for current batch to complete before next batch
        await Promise.all(subagents);
    }
} else {
    // Sequential generation for small projects
    for (const component of components) {
        generatePage(component);
    }
}

Important:

• Always wait for ALL component pages to complete before Phase 3 (Summary Pages)
• Subagents must use the same source link pattern and templates (auto-detect GitHub or GitLab from git remote -v)
• Each subagent saves its output file independently

Directory Grouping Rules

gRPC Services

Group RPC method documentation by gRPC Service name:

• Each gRPC service gets its own subdirectory under service/
• Directory name matches the service name in proto (e.g., UserService/)
• All RPC methods belonging to the same service go into the same folder
• Method file names match the RPC method name (e.g., GetUser.html)

PowerJob Processors

Group PowerJob documentation by Job Processor class name:

• Each PowerJob processor gets its own subdirectory under job/
• Directory name matches the processor class name (e.g., OrderSyncJob/)
• Must identify: Job name, cron expression, processor class, execute method
• Content should analyze: job purpose, scheduling logic, business implementation

Example structure:

job/
├── OrderSyncJob/           # Class: OrderSyncJob implements BasicProcessor
│   └── index.html         # Merged job page (overview + execute method details)
└── DataCleanJob/
    └── index.html         # Merged job page

Merged Structure: Since each PowerJob processor implements BasicProcessor with only one process() method, the documentation uses a merged structure:

• Single index.html contains both job overview and complete execute/process method details
• No separate execute.html file
• This reduces navigation depth and improves user experience, consistent with Pulsar consumer documentation

Pulsar Consumers

Group Pulsar consumer documentation by Consumer class name:

• Each Pulsar consumer gets its own subdirectory under consumer/
• Directory name matches the consumer class name (e.g., OrderEventConsumer/)
• Must identify: Topic name, subscription name, consumer class, receive method
• Content should analyze: message purpose, consumption logic, business handling

Example structure:

consumer/
├── index.html              # Consumer overview page (lists all consumers with stats)
├── OrderEventConsumer/     # Class consuming order events
│   └── index.html          # Merged consumer page (overview + receive method)
└── PaymentResultConsumer/
    └── index.html          # Merged consumer page

Merged Structure: Since each consumer typically has only one receive() method, the documentation uses a merged structure:

• Single index.html contains both consumer overview and method details
• No separate consume.html file
• This reduces navigation depth and improves user experience

Page Templates

All component types follow consistent documentation templates:

• [templates/page-service.md](templates/page-service.md) - gRPC service method documentation
• [templates/page-powerjob.md](templates/page-powerjob.md) - PowerJob processor documentation
• [templates/page-pulsar.md](templates/page-pulsar.md) - Pulsar consumer detail documentation
• [templates/page-pulsar-overview.md](templates/page-pulsar-overview.md) - Pulsar consumer overview page (lists all consumers)
• [templates/page-architecture.md](templates/page-architecture.md) - System architecture template
• [templates/page-features.md](templates/page-features.md) - Core features template
• [templates/page-er.md](templates/page-er.md) - ER diagram template with domain model and zoom/pan support

Page Content Standards

All pages follow a fixed directory structure for consistency:

gRPC Service Overview Page Structure (index.html)

The service overview page (index.html) provides a summary of the gRPC service with modern dashboard styling:

Required CSS Styles (inline in `` tag):

/* Breadcrumb Navigation */
.breadcrumb {
    display: flex;
    align-items: center;
    gap: 8px;
    margin-bottom: 20px;
    font-size: 14px;
    color: var(--text-secondary);
}
.breadcrumb a { color: var(--primary-color); text-decoration: none; }
.breadcrumb a:hover { text-decoration: underline; }
.breadcrumb-separator { opacity: 0.5; }
.breadcrumb-current { color: var(--text-primary); font-weight: 500; }

/* Service Header with Gradient */
.service-header {
    display: flex;
    align-items: center;
    gap: 20px;
    margin-bottom: 30px;
    padding: 30px;
    background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);
    border-radius: 12px;
    color: white;
    box-shadow: 0 4px 20px rgba(102, 126, 234, 0.3);
}
.service-icon { font-size: 48px; opacity: 0.9; }
.service-title h1 { font-size: 28px; margin-bottom: 8px; color: white; }
.service-title p { font-size: 14px; opacity: 0.9; color: rgba(255, 255, 255, 0.9); }

/* Stats Dashboard */
.stats-dashboard {
    display: grid;
    grid-template-columns: repeat(auto-fit, minmax(160px, 1fr));
    gap: 16px;
    margin-bottom: 32px;
}
.stat-card {
    background: var(--card-bg);
    border-radius: 12px;
    padding: 24px;
    text-align: center;
    border: 1px solid var(--border-color);
    box-shadow: 0 2px 4px rgba(0, 0, 0, 0.05);
    transition: all 0.2s ease;
}
.stat-card:hover {
    transform: translateY(-2px);
    box-shadow: 0 4px 12px rgba(0, 0, 0, 0.1);
}
.stat-card.primary { background: linear-gradient(135deg, #dbeafe 0%, #bfdbfe 100%); border-color: #93c5fd; }
.stat-card.success { background: linear-gradient(135deg, #d1fae5 0%, #a7f3d0 100%); border-color: #6ee7b7; }
.stat-card.warning { background: linear-gradient(135deg, #fef3c7 0%, #fde68a 100%); border-color: #fcd34d; }
.stat-icon { font-size: 24px; margin-bottom: 8px; }
.stat-value { font-size: 32px; font-weight: 700; line-height: 1; }
.stat-card.primary .stat-value { color: #1e40af; }
.stat-card.success .stat-value { color: #065f46; }
.stat-card.warning .stat-value { color: #92400e; }
.stat-label { font-size: 13px; color: var(--text-secondary); margin-top: 8px; }

/* Method Table with Clickable Rows */
.method-table tr {
    cursor: pointer;
    transition: background-color 0.15s ease;
}
.method-table tr:hover { background-color: #eff6ff !important; }
.method-table tr:hover td { color: var(--primary-color); }
.method-table td:first-child {
    font-family: 'Monaco', 'Menlo', 'Ubuntu Mono', 'Consolas', monospace;
    font-size: 13px;
}

/* Status Badge Improvements */
.badge {
    display: inline-flex;
    align-items: center;
    gap: 4px;
    padding: 4px 10px;
    border-radius: 12px;
    font-size: 12px;
    font-weight: 500;
}
.badge::before {
    content: '';
    display: inline-block;
    width: 6px;
    height: 6px;
    border-radius: 50%;
}
.badge-success::before { background: var(--success-color); }
.badge-danger::before { background: var(--danger-color); }
.badge-warning::before { background: var(--warning-color); }

/* Section Improvements */
.section { margin-bottom: 40px; }
.section-title {
    font-size: 20px;
    font-weight: 600;
    margi

…

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [crossoverJie](https://github.com/crossoverJie)
- **Source:** [crossoverJie/skills](https://github.com/crossoverJie/skills)
- **License:** Apache-2.0

Install and usage instructions live in the source repository linked above.