how-to-guide

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

August 5, 2026 zhaoxuya520/reverse-skill ↗

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), 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 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) (lines 31‑38):

Task Type	Template File
`逆向工程` (reverse engineering)	[`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` — pentest section
`CTF Writeup`	`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). This is enforced as a hard requirement (MUST on line 56 of 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) 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) 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/skills/diagram-generator/scripts/render_diagram.py) (lines 9‑15). The script detects available renderers:


# 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:


# 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).

Embedding Mermaid Diagrams

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


## 攻击路径图 (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:


# 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
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)
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/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
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).

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/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). The mapping table in 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/ 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).

Have a question about this repo?

These articles cover the highlights, but your codebase questions are specific. Give your agent direct access to the source. Share this with your agent to get started:

Share the following with your agent to get started:

curl -s "https://instagit.com/install.md"

Add to your MCP client configuration:

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}

Ask your agent:

"Use Instagit MCP to understand how zhaoxuya520/reverse-skill works."

Works with

Claude Codex Cursor VS Code OpenClaw Any MCP Client

Maintain an open-source project? Get it listed too →