# How to Use `docs-generator` and `diagram-generator` in reverse‑skill for Technical Report Production

> Streamline technical report production with reverse-skill's docs-generator and diagram-generator. Automate markdown reports with embedded diagrams using this powerful tool.

- Repository: [ZhaoXu/reverse-skill](https://github.com/zhaoxuya520/reverse-skill)
- Tags: how-to-guide
- Published: 2026-08-05

---

**The `docs-generator` and `diagram-generator` skills in `reverse-skill` form an automated pipeline that produces security‑oriented markdown reports with embedded visual diagrams, triggered by task completion or manual keywords like *写报告*, *writeup*, or *report*.**

The `reverse-skill` repository by zhaoxuya520 ships two tightly‑coupled automation skills designed for reverse‑engineering, penetration testing, and CTF workflows. These skills eliminate manual report writing by generating structured documentation with verifiable evidence chains and professional diagrams. This guide walks through the complete workflow from trigger to final output, referencing actual source files and implementation details from the repository.

## Triggering the Report Generation Pipeline

The `docs-generator` skill activates automatically when a reverse‑engineering, pentest, or CTF task finishes. Manual invocation is also supported through specific keywords. According to [[`skills/docs-generator/SKILL.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/docs-generator/SKILL.md)](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/docs-generator/SKILL.md), the skill reads the task's **evidence chain** and selects an appropriate markdown template based on task classification.

**Supported trigger keywords:**
- `写报告` (Chinese: "write report")
- `writeup`
- `report`

When triggered, the skill performs initial validation against [`tool-index.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/tool-index.md) to ensure required external tools are available, with self‑bootstrapping if dependencies are missing (lines 10‑13).

## Selecting Templates and Gathering Evidence

### Template Selection Logic

The skill maps task types to templates using a defined table in [[`skills/docs-generator/SKILL.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/docs-generator/SKILL.md)](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/docs-generator/SKILL.md) (lines 31‑38):

| Task Type | Template File |
|-----------|---------------|
| `逆向工程` (reverse engineering) | [[`references/security-report-templates.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/references/security-report-templates.md)](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/docs-generator/references/security-report-templates.md) |
| `渗透测试` (penetration test) | [`security-report-templates.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/security-report-templates.md) — pentest section |
| `CTF Writeup` | [`security-report-templates.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/security-report-templates.md) — CTF section |

### Evidence Chain Requirement

Every generated report **must** include the **Evidence → Finding → Path** chain as specified in [[`skills/ops/evidence-finding-path.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/ops/evidence-finding-path.md)](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/ops/evidence-finding-path.md). This is enforced as a hard requirement (`MUST` on line 56 of [`docs-generator/SKILL.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/docs-generator/SKILL.md)).

The evidence chain ensures reports contain verifiable proof rather than unsubstantiated claims.

## Integrating Diagrams with `diagram-generator`

During report assembly, `docs-generator` automatically delegates diagram creation to its sibling skill. The *图表集成* (diagram integration) section (lines 59‑70 of [`docs-generator/SKILL.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/docs-generator/SKILL.md)) specifies when and how this cross‑skill call occurs.

### Supported Diagram Languages

[[`skills/diagram-generator/SKILL.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/diagram-generator/SKILL.md)](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/diagram-generator/SKILL.md) defines a decision table for selecting diagram source formats:

- **Mermaid** — default for flowcharts and sequence diagrams (native GitHub/GitLab rendering)
- **Graphviz DOT** — for complex dependency graphs
- **PlantUML** — for UML‑style architectural diagrams

### Rendering Pipeline

When image export is requested, `diagram-generator` executes [[`scripts/render_diagram.py`](https://github.com/zhaoxuya520/reverse-skill/blob/main/scripts/render_diagram.py)](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/diagram-generator/scripts/render_diagram.py) (lines 9‑15). The script detects available renderers:

```python

# Core logic from render_diagram.py lines 11-15

# Pseudo‑representation of renderer detection

if tool_available('mmdc'):      # Mermaid CLI

    render_with_mermaid(input_path, output_format)
elif tool_available('dot'):     # Graphviz

    render_with_graphviz(input_path, output_format)
elif tool_available('java'):    # PlantUML requirement

    render_with_plantuml(input_path, output_format)

```

**Supported output formats:** `PNG`, `SVG`, `PDF`

## Complete Workflow Examples

### Basic Skill Invocation

Trigger report generation from a case script with PowerShell:

```powershell

# Post-task invocation following docs-generator/SKILL.md conventions

Skill('docs-generator') -Args @{
    EvidencePath = 'C:\Cases\2024-001\evidence.json'
    TaskType    = 'reverse-engineering'   # Alternatives: 'pentest', 'ctf'

}

```

This call references the **ACTION REQUIRED** section of [[`skills/docs-generator/SKILL.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/docs-generator/SKILL.md)](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/docs-generator/SKILL.md).

### Embedding Mermaid Diagrams

The generated report contains editable diagram source. Example output structure:

```markdown

## 攻击路径图 (Attack Path Diagram)

Editable Mermaid source:

```mermaid
flowchart TD
    A[Initial Access] --> B{Privilege Escalation}
    B -->|Success| C[Domain Admin]
    B -->|Fail| D[Re‑attempt]

```

**Assumptions:**
- Target environment: Windows domain
- Privilege escalation via CVE‑2022‑XXXX

```

Mermaid blocks render natively on GitHub and GitLab without additional tooling.

### On‑Demand Image Rendering

Generate static assets for distribution:

```powershell

# Render Mermaid source to SVG using diagram-generator

Skill('diagram-generator') -Args @{
    InputFile  = 'attack-path.mmd'    # Previously generated by the skill

    Format     = 'svg'
    OutputFile = 'deliverables/attack-path.svg'
}

```

### End‑to‑End Pipeline Script

Complete workflow combining both skills:

```powershell

# Step 1: Generate base report

$report = Skill('docs-generator') -Args @{
    TaskType     = 'pentest'
    EvidencePath = 'evidence/evidence-chain.json'
    OutputDir    = 'docs/'
}

# Step 2: Create attack-path diagram source

$diagram = Skill('diagram-generator') -Args @{
    Language    = 'mermaid'
    DiagramType = 'flowchart'
    Description = 'Lateral movement path for Corp-DC-01'
}

# Step 3: Render to SVG for client delivery

Skill('diagram-generator') -Args @{
    InputFile  = $diagram.SourcePath
    Format     = 'svg'
    OutputFile = 'deliverables/lateral-movement.svg'
}

# Step 4: Append rendered diagram to report

Add-Content -Path $report.Path -Value @"

## Visual Appendix

![Attack Path](lateral-movement.svg)
"@

```

## Architecture and Design Principles

The two skills implement **progressive disclosure**: reports build step‑by‑step with validation at each stage.

```

Task Completion
    ↓
docs-generator (template selection + evidence validation)
    ↓
[diagram-generator invocation for visual assets]
    ↓
Markdown report with embedded/linked diagrams
    ↓
field-journal (sanitized evidence write‑back)

```

**Key design enforcements:**
- `docs-generator` serves as **textual content producer**
- `diagram-generator` serves as **visual asset producer**
- Both skills validate against checklists at file end (`docs-generator` lines 68‑75, `diagram-generator` lines 82‑86)

## Checklist Validation

Each skill enforces completion through structured checklists:

**`docs-generator` requirements (lines 68‑75):**
- [ ] Evidence chain populated from [`ops/evidence-finding-path.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/ops/evidence-finding-path.md)
- [ ] Template matched to task type
- [ ] Diagram sections tagged for `diagram-generator` integration
- [ ] Output filename formatted as `YYYY‑MM‑DD_task‑type‑description.md`

**`diagram-generator` requirements (lines 82‑86):**
- [ ] Source language validated (Mermaid/DOT/PlantUML)
- [ ] Rendering tool availability confirmed
- [ ] Output format supported by selected renderer

## Summary

- **`docs-generator`** automates markdown report creation with template‑based structure and mandatory evidence chains from [[`skills/ops/evidence-finding-path.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/ops/evidence-finding-path.md)](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/ops/evidence-finding-path.md)
- **`diagram-generator`** produces editable diagram source (Mermaid, Graphviz, PlantUML) with optional rasterization via [[`scripts/render_diagram.py`](https://github.com/zhaoxuya520/reverse-skill/blob/main/scripts/render_diagram.py)](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/diagram-generator/scripts/render_diagram.py)
- **Cross‑skill integration** occurs automatically when `docs-generator` encounters diagram requirements, calling `diagram-generator` per lines 59‑70 of [`docs-generator/SKILL.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/docs-generator/SKILL.md)
- **Manual invocation** supports PowerShell-based workflow automation with structured argument passing
- **Final output** combines embedded Mermaid (GitHub‑native) with optional rendered PNG/SVG/PDF assets for external distribution

## Frequently Asked Questions

### What triggers the `docs-generator` skill automatically?

The skill activates when the `reverse-skill` framework detects task completion in reverse‑engineering, pentest, or CTF workflows. Specific keywords (`写报告`, `writeup`, `report`) also trigger manual invocation according to [[`skills/docs-generator/SKILL.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/docs-generator/SKILL.md)](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/docs-generator/SKILL.md).

### Do I need external tools installed for diagram generation?

Mermaid diagrams render natively on GitHub/GitLab without tools. For PNG/SVG/PDF export, `diagram-generator` requires `mmdc` (Mermaid CLI), `dot` (Graphviz), or Java (PlantUML) as detected in [[`scripts/render_diagram.py`](https://github.com/zhaoxuya520/reverse-skill/blob/main/scripts/render_diagram.py)](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/diagram-generator/scripts/render_diagram.py). Both skills self‑bootstrap missing dependencies.

### Can I customize the report templates?

Templates reside in [[`skills/docs-generator/references/security-report-templates.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/docs-generator/references/security-report-templates.md)](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/docs-generator/references/security-report-templates.md). The mapping table in [`docs-generator/SKILL.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/docs-generator/SKILL.md) (lines 31‑38) links task types to template sections—modify these files directly to customize output structure.

### What is the `field-journal` skill and when does it execute?

[`skills/field-journal/`](https://github.com/zhaoxuya520/reverse-skill/tree/main/skills/field-journal) handles sanitized write‑back of evidence after report generation completes. It runs as the final step in the full pipeline, closing the loop between raw evidence and deliverable documentation (referenced in `docs-generator` lines 57‑58).