# Generate Wiki

> >

- **Type:** Skill
- **Install:** `agentstack add skill-crossoverjie-skills-generate-grpc-java-wiki`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [crossoverJie](https://agentstack.voostack.com/s/crossoverjie)
- **Installs:** 0
- **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills)
- **Latest version:** 0.1.0
- **License:** Apache-2.0
- **Upstream author:** [crossoverJie](https://github.com/crossoverJie)
- **Source:** https://github.com/crossoverJie/skills/tree/main/skills/generate-grpc-java-wiki

## Install

```sh
agentstack add skill-crossoverjie-skills-generate-grpc-java-wiki
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# 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)
4. **Check Component Count** - If total components ≥ 50, enable parallel generation
5. **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
5. **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
6. **Generate System Architecture** (`01-system-architecture.html`) - Based on completed component pages, all discovered services, jobs, consumers, dependencies, and message flows
7. **Generate Core Features** (`02-core-features.html`) - Based on completed gRPC, PowerJob, and Pulsar component analysis, grouped into business capabilities
8. **Generate ER Diagram** (`03-er-diagram.html`) - Based on ALL proto message types plus completed service method request/response mappings
9. **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:**

```javascript
// 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)**:

```css
/* 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.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-crossoverjie-skills-generate-grpc-java-wiki
- Seller: https://agentstack.voostack.com/s/crossoverjie
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.