Ready to supercharge your AI agents?

Install any skill in seconds. Free to start, no credit card required.

Composing Vulnerability Report · jeremylongshore | DecimalAI

jeremylongshore/composing-vulnerability-report

SkillScore82Maintained

Read findings JSONL files from cluster 1-4 skills, deduplicate by fingerprint, group by severity, and compose a deliverable- grade markdown vulnerability report with per-finding sections (title, severity, target, detail, remediation, evidence) and a top-level summary table. The canonical written artifact a customer receives at engagement close; precise, reproducible, machine- checkable against source findings. Use when: closing an engagement, generating an interim report, regenerating after CVE

Securityby jeremylongshore

Links this skill to your agents and keeps it current with the author’s updates.

Automatic

Security & AppSec pack

1 · One-time — install the CLI (docs ↗)

pip install decimalai

2 · Get the skill — writes .claude/skills/jeremylongshore-composing-vulnerability-report/SKILL.md

decimalai skills pull jeremylongshore-composing-vulnerability-report --out .claude/skills/

No CLI? Get the same file — curl · raw file

curl -fsSL --create-dirs -o .claude/skills/jeremylongshore-composing-vulnerability-report/SKILL.md https://app.decimal.ai/s/jeremylongshore-composing-vulnerability-report/SKILL.md

Raw file: /s/jeremylongshore-composing-vulnerability-report/SKILL.md ↗ · machine-readable summary at /s/jeremylongshore-composing-vulnerability-report.json ↗

In productionGlobal

how this skill behaves on real traffic · last 30 days

No production data for this skill yet — usage numbers appear here once agents start running it.

Anonymized aggregate across every org using this skill — proof from real production use, not a demo.

Does this skill help? · Benchmark: with vs. withoutsign in to run this on your agents

22 test cases from the publisher’s eval.yaml · each run twice on gemini-3.6-flash — with the skill injected, then without · last run 46d ago

—+26% tokens0% turns82% of whole cases pass with skill (18/22)

Test case	Without → With	Effect	Δ tokens	Δ turns
case-02	✗→✓	▲ Improved	1062%	0%
case-03	✗→✓	▲ Improved	12%	0%
case-04	✗→✓	▲ Improved	-5%	0%
case-09	✗→✓	▲ Improved	94%	0%
case-11	✗→✓	▲ Improved	9%	0%

Showing 5 of 22 cases

SkillSafety

✓ 3 of 3 passed

Code scan15 of 15 checks clean

0 critical · 0 warning · 0 info — scanner v4 — 8/3/2026

live_secretremote_code_executionreverse_shelldata_exfiltrationssrf_metadataagent_snoopinganti_refusaldestructive_commandsobfuscated_unicodeunicode_homoglyphopaque_blobsuspicious_urltool_overreachtrigger_abuseprompt_injection_phrasing

IntentSafe

LLM judge · does the skill do what it claims

ContentClean

LLM judge · policy & harmful-content review

Source

Imported

jeremylongshore / claude-code-plugins-plus-skills

skills/.curated/composing-vulnerability-report/SKILL.md

View on GitHub ↗

License MITImported 8/3/2026Version v1Bundled 3 files · scripts

Skill contents

scripts/

references/

SKILL.md

Composing Vulnerability Report

Overview

After cluster 1-4 scan skills run, each one produces a Findings file. A typical engagement ends up with eight to twenty such files across the different skill categories. The customer wants ONE vulnerability report — comprehensive, deduplicated, organized by severity, with each finding cross-referenced to its source skill and target.

This skill consumes one or more findings files (JSONL preferred, JSON list also accepted), deduplicates entries by the canonical fingerprint defined in lib/finding.py, enriches each finding with a CVSS v3.1 vector when one isn't present (using a deterministic heuristic based on severity + category — explicitly noted as "derived, not assigned by NVD" in the output), and emits a single markdown report with per-finding sections plus a top-level summary table.

The report has a defined structure that downstream tools (next two skills in cluster 6) consume:

Header — engagement ID, generation timestamp, source files
Summary table — finding count by severity
Per-severity sections — CRITICAL first, then HIGH, MEDIUM,

LOW, INFO

Per-finding subsections — title, severity, target, detail,

remediation, evidence, references

When the skill produces findings

| Finding | Severity | Threshold | Affected control | |---|---|---|---| | Source file unparseable | HIGH | JSON/JSONL parse fails | (operational) | | Finding missing required field | HIGH | A finding record is missing title, severity, target, detail, or remediation | (operational) | | Duplicate fingerprint across files | INFO | Same finding appears in N>1 sources; reported as deduplication count | (informational) | | Source file has zero findings | INFO | Empty or all-info-only file; reported but not an error | (informational) | | Report generated cleanly | INFO | Positive confirmation | (informational) |

Prerequisites

Python 3.9+
One or more findings files in JSON or JSONL format produced by

any cluster 1-4 scan skill (which all share lib/finding.py schema)

Instructions

Step 1 — Gather findings sources

By default the skill reads every file matching engagement/findings/*.json and engagement/findings/*.jsonl. Override with --source FILE (repeatable).

Step 2 — Run the composer

bash
python3 ./scripts/compose_report.py engagements/acme-2026-q2/

Options:

Usage: compose_report.py PATH [OPTIONS]

Options:
  --source FILE         Specific findings file (repeatable; overrides default glob)
  --report-output FILE  Write the composed report here (default:
                        PATH/reports/vulnerability-report.md)
  --engagement-id ID    Override the engagement ID (default: parse from PATH/roe.yaml)
  --output FILE         Operational findings output (this skill's own findings)
  --format FMT          json | jsonl | markdown (default: markdown)
  --min-severity SEV    Filter report to findings at or above this severity
  --include-info        Include INFO-severity findings in the report (default: omit)

Step 3 — Review the report

The output report has a predictable structure. The header identifies the engagement, the source files, and the generation timestamp. The summary table shows finding counts by severity. Per-severity sections follow.

Each finding subsection includes a stable anchor (the fingerprint) so cross-references from later artifacts (executive summary, OWASP mapping) resolve into the report cleanly.

Step 4 — Verify against sources

bash
python3 ./scripts/compose_report.py engagements/acme-2026-q2/ --format json --output /tmp/compose-findings.json
jq '.[] | select(.severity == "high")' /tmp/compose-findings.json

If the report references a finding the operator didn't expect, trace back via the finding's skill_id + target to the source file.

Examples

Example 1 — End-of-engagement report

bash
python3 ./scripts/compose_report.py engagements/acme-2026-q2/ \
    --report-output engagements/acme-2026-q2/reports/vulnerability-report.md

Example 2 — Interim report mid-engagement

bash
python3 ./scripts/compose_report.py engagements/acme-2026-q2/ \
    --min-severity high \
    --report-output engagements/acme-2026-q2/reports/interim-2026-06-15.md

--min-severity high produces an interim report covering only HIGH and CRITICAL findings — useful for in-engagement customer syncs.

Example 3 — Regenerate after OWASP mapping

bash
python3 ./scripts/compose_report.py engagements/acme-2026-q2/ \
    --source engagements/acme-2026-q2/findings/all-findings-with-owasp.jsonl \
    --report-output engagements/acme-2026-q2/reports/vulnerability-report-v2.md

Re-run after mapping-findings-to-owasp-top10 has enriched each finding with its OWASP category; the regenerated report includes the OWASP tag in each per-finding subsection.

Output

JSON / JSONL / Markdown per lib/report.py for the skill's own operational findings. The PRIMARY output is the composed vulnerability report, written as standalone Markdown to the --report-output path.

Each operational Finding includes:

id — compose::<issue>::<source-file>
severity — CRITICAL / HIGH / MEDIUM / INFO
category — report-composition
summary — what went wrong (or right) during composition
evidence — source files, finding counts, dedup stats

Error Handling

PATH missing or empty → emits CRITICAL operational finding,

exits 1.

Source file unparseable → emits HIGH operational finding,

skips the file, continues with remaining sources.

No findings files found → emits HIGH operational finding,

exits 1.

Output report path not writable → emits HIGH operational

finding, exits 1.

Finding missing required fields → emits HIGH operational

finding, omits that record from the report, continues.

Resources

references/THEORY.md — Vulnerability-report structure history

(NIST SP 800-115, OWASP Testing Guide), CVSS v3.1 vector composition, severity scoring tradeoffs (CVSS vs intrinsic vs EPSS), finding-deduplication theory, why fingerprint-based dedup beats title-based

references/PLAYBOOK.md — Report-template variants per

audience (technical, executive, regulatory), per-finding remediation phrasing patterns, evidence-redaction patterns for distributed reports, cross-reference protocol with the OWASP-mapping and exec-summary skills

Illustrative Want to see what jeremylongshore/composing-vulnerability-report would put in front of your model? Preview the rendered body and check its trigger phrases — no LLM call, no signup.

Latest benchmark · publisher runVerified

8/13/2026, 21:55 UTC · 22 cases

Measured on 21 comparable cases — below the 22 needed to publish a lift, so this result is shown here but not on the registry card or leaderboard.

Lift

+45%

82% vs 36%

Agent turns

1.0 vs 1.0

Tokens

+26%

2,680.24 vs 2,129

fail → pass · 11pass → pass · 7fail → fail · 3pass → fail · 1

Per-case results (22)

Case	Status	Duration (ms)			Turns			Tokens			Tool calls
Case	Status	Without	With	Δ	Without	With	Δ	Without	With	Δ	Without	With	Δ
case-01 I need to assemble all the scan output JSON and JSONL files in my engagement workspace directory into a single consolidated vulnerability report in Markdown format. The report should eliminate duplicate entries, enrich missing CVSS vectors, and include an engagement header, a severity summary breakdown, and detailed sections for each vulnerability.	fail→fail	23,837	29,870	+25%	1	1	0%	5,092	7,880	+55%	0	0	—
case-02 We need an interim status report for the team focused on urgent security risks. Please process the findings files in our assessment directory and build a report that filters out lower-tier items, presenting only the critical and high severity issues along with finding counts and detailed remediation guidance.	fail→pass	7,186	5,592	-22%	1	1	0%	233	2,708	+1062%	0	0	—
case-03 I have an updated JSONL file containing enriched findings from our recent OWASP mapping step. Please generate an updated Markdown report using this specific input file rather than scanning the default findings directory, saving the output report to a specified custom location and checking for any unparseable records.	fail→pass	14,591	7,986	-45%	1	1	0%	2,807	3,152	+12%	0	0	—
case-04 We want to compile our security scan findings in `engagements/client-alpha/` into a standard report without passing explicit output filename parameters. Where will the tool place the generated markdown file by default?	fail→pass	12,051	4,476	-63%	1	1	0%	2,100	2,002	-5%	0	0	—
case-05 When generating the final markdown report for an engagement, in what relative order should findings be grouped across severity sections?	pass→pass	7,739	1,649	-79%	1	1	0%	1,307	1,917	+47%	0	0	—
case-06 We want to include informational severity findings alongside our technical vulnerabilities in the generated report for `engagements/acme/`. What CLI option forces informational findings to be included?	pass→pass	12,477	1,611	-87%	1	1	0%	2,241	1,977	-12%	0	0	—
case-07 During report generation on `engagements/pentest-2026/`, we want to log the composition tool's internal operational findings separately into a dedicated JSON file rather than sending them to stdout. Which flag controls this?	pass→pass	18,631	2,966	-84%	1	1	0%	3,352	2,251	-33%	0	0	—
case-08 When running the report consolidation tool, we want to exclude low and informational items, building a report that begins at medium severity. Which flag specifies this severity threshold?	pass→pass	7,288	2,781	-62%	1	1	0%	1,264	2,130	+69%	0	0	—
case-09 Instead of scanning the standard findings directory in `engagements/demo/`, we want to combine findings from two distinct files: `findings/network.json` and `findings/web.jsonl`. How should these specific files be supplied to the CLI tool?	fail→pass	5,586	2,635	-53%	1	1	0%	1,080	2,092	+94%	0	0	—
case-10 We need to generate a report for `engagements/acme-q1/` but need the report header to explicitly reflect an engagement ID of `ENG-9982` instead of pulling the value from `roe.yaml`. Which option overrides this setting?	pass→pass	7,603	2,977	-61%	1	1	0%	1,287	2,121	+65%	0	0	—
case-11 When running the report composer against `engagements/penta-corp/` without specifying explicit `--source` options, from which workspace subdirectory does the tool automatically read scan findings?	fail→pass	18,492	2,389	-87%	1	1	0%	1,888	2,049	+9%	0	0	—
case-12 When specifying `--output logs/ops-summary.json` during report composition for `engagements/penta-corp/` without passing `--format`, what format is used for the operational findings output?	pass→fail	6,349	3,949	-38%	1	1	0%	1,031	2,187	+112%	0	0	—
case-13 If an input finding record in a scan JSON file lacks required fields such as remediation or detail, how is this handled during report composition?	fail→pass	11,193	2,715	-76%	1	1	0%	1,792	2,085	+16%	0	0	—
case-14 What happens when the report composition tool is executed against a directory path that does not exist or is completely empty?	fail→pass	11,150	4,114	-63%	1	1	0%	1,957	2,345	+20%	0	0	—
case-15 If one JSON file in `engagement/findings/` contains invalid JSON syntax during report compilation, how does the composer handle that specific file and the rest of the execution?	fail→pass	10,030	2,758	-73%	1	1	0%	1,625	2,162	+33%	0	0	—
case-16 When `--report-output` points to a directory path where the current user lacks write permissions, how does the report composer report and terminate?	pass→pass	12,919	3,598	-72%	1	1	0%	2,143	2,368	+10%	0	0	—
case-17 We want the operational execution findings of the composition script itself to be emitted in JSONL format for machine parsing. What argument controls this operational findings output format?	pass→pass	9,325	2,748	-71%	1	1	0%	1,540	2,183	+42%	0	0	—
case-18 When two different scan output files contain identical findings, how does the report composer handle deduplication across files?	fail→pass	13,743	4,314	-69%	1	1	0%	2,364	2,418	+2%	0	0	—
case-19 When the same finding fingerprint is identified across three separate source files, what severity and metric are generated in the operational findings?	fail→fail	11,395	2,249	-80%	1	1	0%	1,769	2,061	+17%	0	0	—
case-20 We have raw findings in `findings/raw-scan.json` and need to automatically analyze their titles and descriptions to assign corresponding OWASP Top 10 2021 vulnerability categories to each record. How should we execute this taxonomy mapping task?	fail→pass	15,400	9,138	-41%	1	1	0%	3,296	3,521	+7%	0	0	—
case-21 We need to run an automated web vulnerability scan against `https://staging.example.com` to discover SQL injection and cross-site scripting vulnerabilities and write the raw scan output to disk. Which flags on `compose_report.py` initiate the dynamic scan?	fail→pass	12,067	10,415	-14%	1	1	0%	1,420	2,797	+97%	0	0	—
case-22 Please write a 2-page executive summary narrative with business risk analysis, financial impact assessment, and high-level strategic takeaways for the Chief Information Security Officer based on our recent penetration test.	fail→fail	22,534	17,368	-23%	1	1	0%	3,354	4,587	+37%	0	0	—

These cases were also screened by the skill’s intent / safety pass.See the Trust review ↗Reproduce this benchmark in Colab ↗

How this skill was measured

DecimalAI ran this skill against gemini-3.6-flash twice over the same eval suite — once with the skill loaded and once without — and compared the two runs case by case. 22 cases were attempted, and 21 counted toward the lift figure. The other 1 produced results that are not comparable between the two arms, so they are excluded from the headline rather than averaged into it. The headline lift of +45 percentage points is the difference between those two pass rates over the 21 comparable cases. 1 case got worse with the skill loaded, and it is included in that figure.

Model measured: gemini-3.6-flash
Graded by: gemini-3.6-flash
Grading method: judged
Verification: verified
Pass rate without the skill: 36.4%
Pass rate with the skill: 81.8%
Cases attempted: 22
Cases counted toward lift: 21
Cases that regressed: 1
Skill version measured: v1
Run completed: 8/13/2026, 21:55 UTC

Measured example — same prompt, with vs. without the skill · from the benchmark run · case case-03

Prompt

I have an updated JSONL file containing enriched findings from our recent OWASP mapping step. Please generate an updated Markdown report using this specific input file rather than scanning the default findings directory, saving the output report to a specified custom location and checking for any unparseable records.

Without the skill loaded, the model failed this case. With it loaded, the same prompt on the same model passed. This is one improved case from the latest verified run; every case, including any that regressed, is in the table above.

Show both answers

SkillScore blends 4 signals1 of 4 complete

BenchmarkPass rate WITH skill on a verified run82

Live evalNeeds ≥10 evaluated traces in 30 days

AI ratingNeeds ≥10 rated traces

AdoptionNeeds ≥10 serves across ≥2 orgs in 30 days

Efficiency · separate axis (at equal correctness)+0% turns+14% tokens

Shown for transparency; not credited unless a verified run shows no correctness regression.

Backed by 1 of 4 signals — each added signal makes the score more robust.

Verified on gemini-3.6-flash · re-tested 45 days ago

Other measured skills in the registry, with their headline benchmark lift.