Report Generation Templates and Documentation Standards in reverse-skill: Complete Guide

The reverse-skill project uses eight standardized Markdown templates under skills/pentest-tools/templates/ and skills/docs-generator/references/, enforced by mandatory formatting rules in SKILL.md that require UTF-8 encoding, runnable code blocks, evidence-based findings, and no unresolved placeholders.

Overview of Report Generation Templates and Documentation Standards

The reverse-skill repository implements a complete workflow for security-oriented AI agents where structured reporting is not optional. When any task completes, the docs-generator skill automatically assembles findings into a formal deliverable using predefined templates and strict documentation standards. This article explains every template location, the enforcement rules codified in the source code, and how agents invoke this system in practice.

Report Generation Template Architecture

The template system operates in two layers: data collection templates that capture raw findings during operations, and report skeletons that format those findings into final deliverables.

Data Collection Templates (pentest-tools)

Located in skills/pentest-tools/templates/, these files standardize how agents record information during security assessments:

Template	Purpose	Key File Path
task_plan.md	High-level test plan with stages and status flags	skills/pentest-tools/templates/task_plan.md
scope.md	Authorized scope table listing targets, accounts, and prohibitions	skills/pentest-tools/templates/scope.md
rules.md	Allowed vs. forbidden operations, rate limits, and reporting requirements	skills/pentest-tools/templates/rules.md
progress.md	Timeline of actions, results, and risk ratings	skills/pentest-tools/templates/progress.md
findings.md	Structured vulnerability log with four categories: confirmed, potential, info-leak, excluded	skills/pentest-tools/templates/findings.md

These templates represent the single source of truth for raw data. According to RULES.md, the Completion Checklist explicitly requires "Generate formal report" using these inputs before any task can be marked complete.

Report Skeleton Templates (docs-generator)

The docs-generator skill consumes the raw data above and applies higher-level formatting through these reference files:

Template	Purpose	Key File Path
security-report-templates.md	Full report skeletons for reverse-engineering, pentest, CTF write-up, and vendor-specific reports	skills/docs-generator/references/security-report-templates.md
vendor-report-rules.md	Optional "flavor" overlays (malware, apt, vuln) that inject vendor-style sections	skills/docs-generator/references/vendor-report-rules.md
templates.md	Generic README and API documentation skeletons for non-security deliverables	skills/docs-generator/references/templates.md

The template selection logic resides in skills/docs-generator/SKILL.md. Lines 59-61 specify the output naming convention: YYYY-MM-DD_[type]-[target]-report.md.

Documentation Standards Enforcement

All generated documents must comply with standards codified in skills/docs-generator/SKILL.md. These rules are non-negotiable and validated through a self-audit block (lines 334-340).

File and Encoding Requirements

• Location: Project root, or docs/ subdirectory when it exists (lines 58-59)
• Naming: YYYY-MM-DD_[type]-[target]-report.md format (lines 59-61)
• Encoding: UTF-8 mandatory (line 62)
• Language: Follows user dialogue—Chinese input produces Chinese output, English produces English (lines 62-63)

Structural and Content Standards

Standard	Rule	Source Location
Mandatory sections	Evidence → Finding → Path structure required; must reference ops/evidence-finding-path.md	Lines 70-74
Code blocks	Every snippet must be runnable or contain clear context; always specify language (e.g., ```bash)	Lines 66-67
Placeholder prohibition	No TODO or unresolved placeholders allowed	Line 67
Evidence requirement	All findings need concrete proof: request/response dumps, screenshots, hashes	Lines 68-70
Reproducibility	Steps must enable third-party repetition without additional clarification	Lines 69-70
Sensitive data handling	Replace real secrets with placeholders like <API_KEY>; never commit actual values	Lines 70-71

Formatting and Presentation Rules

Lines 121-127 of SKILL.md establish these formatting standards:

• Sentence-case headings (not Title Case)
• Maximum three heading levels deep
• Tables for any data with more than three attributes
• Relative internal links for cross-references
• Mermaid diagrams inserted directly in Markdown, sourced from the diagram-generator skill (lines 75-86)

Information Architecture

The progressive disclosure standard (lines 92-101) requires content layering:

1. One-sentence description
2. Quick-start summary
3. Full API reference
4. Deep-dive technical details

Quality Checklist (Pre-Completion Validation)

Before claiming completion, the agent must verify (lines 30-35):

• All code examples tested
• No placeholder text remains
• Content matches actual code behavior
• Document is scannable without full read
• Clear next steps provided for reader

Anti-Patterns to Avoid

Lines 38-43 explicitly prohibit:

• Wall-of-text paragraphs
• Buried critical information
• Missing error documentation

Practical Usage Examples

Example 1: Generating a Pentest Report

This PowerShell workflow demonstrates how an agent invokes the template system:

# 0. Ensure tool index recognizes the report generator

powershell -NoProfile -ExecutionPolicy Bypass -File .\skills\scripts\refresh-tool-index.ps1

# 1. Agent reads findings template (auto-populated during test)

type .\skills\pentest-tools\templates\findings.md

# 2. Agent invokes docs-generator skill with "pentest" flavor

# Skill reads security-report-templates.md → selects pentest body

# Final output written to project root:

# 2024-11-03_pentest-TargetApp-report.md

The resulting report contains:

• Scope section (copied from scope.md)
• Findings table (populated from findings.md)
• Progress timeline (from progress.md)
• Vendor-flavor sections if "malware" style requested (via vendor-report-rules.md)
• Mermaid diagrams from diagram-generator skill (attack-path graphs)

Example 2: Creating Technical README Documentation

# Agent confirms request to "write documentation for the new API"

# Reads generic templates file

cat skills/docs-generator/references/templates.md

# Generates README.md in project root

cat <<'EOF' > README.md

# My API

## Getting started

```bash

# install dependencies

pip install -r requirements.txt

API endpoints

Method	Path	Description
GET	/v1/users	List users
POST	/v1/users	Create user
EOF

Output complies with **Formatting Standards**: sentence-case headings, language block tags, three-level heading limit.

## Critical Source Files Reference

| Path | Role in Report Generation Templates and Documentation Standards |
|------|----------------------------------------------------------------|
| `skills/pentest-tools/templates/*.md` | Raw data collection templates for scope, findings, progress, rules, and task planning |
| [`skills/docs-generator/SKILL.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/docs-generator/SKILL.md) | Orchestrates template selection, naming, language handling, diagram insertion, and final self-audit |
| [`skills/docs-generator/references/security-report-templates.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/docs-generator/references/security-report-templates.md) | Master skeletons for all security report types |
| [`skills/docs-generator/references/vendor-report-rules.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/docs-generator/references/vendor-report-rules.md) | Optional vendor-flavor overlays (`malware`, `apt`, `vuln`) |
| [`skills/docs-generator/references/templates.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/docs-generator/references/templates.md) | Generic documentation skeletons for README and API docs |
| [`docs/OVERVIEW.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/docs/OVERVIEW.md) | High-level routing system description showing report generation position |
| [`RULES.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/RULES.md) (Completion Checklist section) | Mandates formal report generation before task completion |
| [`ops/evidence-finding-path.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/ops/evidence-finding-path.md) | Defines mandatory Evidence → Finding → Path contract |

## Summary

- **Report generation templates** reside in `skills/pentest-tools/templates/` for data collection and `skills/docs-generator/references/` for final formatting
- **Documentation standards** are codified in [`skills/docs-generator/SKILL.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/docs-generator/SKILL.md) with explicit rules for encoding, structure, code quality, and evidence requirements
- The **docs-generator** skill bridges layers: selects appropriate template, applies standards, writes to project root or `docs/`, and validates via [`RULES.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/RULES.md) checklist
- **Mandatory validation** includes a quality checklist and self-audit block that prevent completion with placeholder text or untested examples
- All outputs follow **progressive disclosure** and **three-level heading limits** for immediate usability

## Frequently Asked Questions

### How does reverse-skill enforce documentation standards automatically?

The **docs-generator** skill defined in [`skills/docs-generator/SKILL.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/docs-generator/SKILL.md) contains a self-audit block at lines 334-340 that validates output against codified rules. Additionally, [`RULES.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/RULES.md) includes a **Completion Checklist** (lines 70-73) that prevents task completion until a formal report is generated and all quality criteria—runnable code, no placeholders, verified evidence—are satisfied.

### What happens if a finding lacks concrete evidence?

The **Evidence → Finding → Path** structure is mandatory per lines 70-74 of [`SKILL.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/SKILL.md) and defined in [`ops/evidence-finding-path.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/ops/evidence-finding-path.md). A finding without concrete proof—such as request/response dumps, screenshots, or cryptographic hashes—fails the quality checklist at lines 30-35 and blocks report finalization.

### Can templates be customized for specific vendor report formats?

Yes. The **vendor-report-rules.md** file at [`skills/docs-generator/references/vendor-report-rules.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/docs-generator/references/vendor-report-rules.md) provides optional "flavor" overlays including `malware`, `apt`, and `vuln` styles. The docs-generator skill merges these overlays with base templates from [`security-report-templates.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/security-report-templates.md) when specific vendor formatting is requested.

### Where are completed reports saved and how are they named?

According to lines 58-61 of [`skills/docs-generator/SKILL.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/docs-generator/SKILL.md), reports are written to the project root directory or `docs/` subdirectory if it exists. The naming convention is strictly `YYYY-MM-DD_[type]-[target]-report.md`—for example, [`2024-11-03_pentest-TargetApp-report.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/2024-11-03_pentest-TargetApp-report.md).

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