Skip to content
Get packs

Guide · Agent skill

How to use the PDF Malware Triage with PDFiD agent skill

Updated · written with AI from the project's own documentation and checked against our catalogue data

This guide explains what the analyzing-pdf-malware-with-pdfid agent skill does, how to install it for Claude, and how to ask for PDF triage in plain language. It is written for readers who have not used agent skills before. By the end you will know how to install the skill, what it asks the agent to do, and what safety limits to respect when the sample is malicious.

PDF Malware Triage with PDFiDmukul975/Anthropic-Cybersecurity-Skills · Apache-2.0

Quick start

  1. 1Download and unzip. Download the skill ZIP from this page and unzip it. Confirm that SKILL.md is in the folder.
  2. 2Place the folder. Move the folder into ~/.claude/skills/ for personal use or into a project's .claude/skills/ folder.
  3. 3Or upload in the Claude apps. In the Claude apps, open Settings, go to Capabilities, and upload the skill under Skills.
  4. 4Install the tools. Install Python 3.8+, pdfid, pdf-parser and peepdf, and make sure pdftotext from poppler-utils is available.
  5. 5Prepare an isolated VM. Move the sample into an isolated analysis VM without a PDF reader installed.
  6. 6Ask for triage. Describe the suspicious PDF and ask for keyword triage, JavaScript extraction or embedded file review.
  7. 7Treat results as leads. Use the findings to decide next steps, remembering that keyword counts can produce false positives and negatives.

What is an agent skill and what does this one do?

An agent skill is a folder of instructions and optional scripts that an AI agent loads when a task matches the skill's description. This one is named analyzing-pdf-malware-with-pdfid and is licensed Apache-2.0. Its description says it analyzes malicious PDF files using PDFiD, pdf-parser, and peepdf to identify embedded JavaScript, shellcode, exploits, and suspicious objects without opening the document.

When the skill is active, the agent follows a structured static-analysis method. It runs or describes PDFiD to count risky keywords such as /JavaScript, /OpenAction and /EmbeddedFile, uses pdf-parser to inspect individual objects, uses peepdf for interactive JavaScript extraction, and then pulls out embedded files and URLs for further analysis. The package also includes a small Python script, scripts/agent.py, that counts suspicious PDF keywords and computes file hashes.

Install the skill from the ZIP

Download the ZIP for this skill from this page and unzip it. The skill folder should contain SKILL.md, scripts/agent.py and references/api-reference.md.

For a personal install, place the unzipped folder in ~/.claude/skills/. For a single project, place it in that project's .claude/skills/ folder. Start a new agent session afterwards so the skill is picked up.

Alternatively, in the Claude apps, open Settings, go to Capabilities, and upload the skill under Skills.

  • Personal: ~/.claude/skills/
  • Project: .claude/skills/ inside your project
  • Claude apps: Settings → Capabilities → Skills

Check what you need before you start

The skill assumes a specific toolset. Install these before relying on the agent's output. Python 3.8 or newer is required, along with Didier Stevens' pdfid and pdf-parser tools and peepdf. The skill also refers to poppler-utils (pdftotext) for text extraction.

Some tools are optional: YARA with PDF rules for family identification, CyberChef as a web tool for decoding, and scdbg and speakeasy for shellcode emulation.

The source recommends an isolated analysis VM without a PDF reader installed, so that a malicious sample cannot be opened by accident.

  • Required: Python 3.8+, pdfid, pdf-parser, peepdf, poppler-utils (pdftotext)
  • Optional: YARA with PDF rules, CyberChef, scdbg, speakeasy
  • Recommended: isolated analysis VM
pip install pdfid pdf-parser pip install peepdf

How to trigger the skill with natural requests

You do not need special syntax. The skill activates for requests about PDF malware analysis, malicious document analysis, PDF exploit investigation, or suspicious attachment triage. Describe the situation and the file, and say what you want to know.

Be specific about the goal. Asking whether a PDF has auto-run actions gets a different answer than asking for the attack vector. Mention that the file is a sample you are analysing in an isolated environment so the agent frames its steps correctly.

  • "Triage suspect.pdf, which email security flagged as a phishing attachment. Check for JavaScript and auto-run actions."
  • "Run PDFiD on this sample and tell me which high-risk keywords appear."
  • "Extract the JavaScript from suspect.pdf so I can review it in my isolated VM."
  • "Find any embedded files in this PDF and hash them."

Read the PDFiD keyword output

PDFiD counts PDF keywords. The skill groups them by risk. High-risk indicators include /JS, /JavaScript, /AA, /OpenAction and /Launch. Medium-risk indicators include /EmbeddedFile, /RichMedia, /AcroForm and /XFA. Low-risk indicators include /ObjStm and /URI.

Treat these as leads, not verdicts. The skill itself warns that keyword counts are heuristic and can produce false positives and negatives. A nonzero /JavaScript count tells you where to look next; it does not prove the file is malicious.

  • HIGH: /JS, /JavaScript, /AA, /OpenAction, /Launch, /JBIG2Decode
  • MEDIUM: /EmbeddedFile, /RichMedia, /AcroForm, /XFA
  • LOW: /ObjStm, /URI, /Page
pdfid suspect.pdf pdfid -e suspect.pdf pdfid -d suspect.pdf

Follow the triage workflow step by step

The skill's workflow moves from broad to narrow. It starts with PDFiD for keyword counts, then uses pdf-parser to search for objects such as /JavaScript or /OpenAction and to inspect or decompress a specific object. Next it extracts JavaScript, either with pdf-parser or with peepdf's interactive commands such as js_analyse. Shellcode found in streams can be examined with scdbg or speakeasy, and embedded files and URLs are pulled out for hashing and review.

You can ask the agent to stop after any stage. A keyword-only pass is often enough to decide whether a sample needs deeper work.

  • Keyword scan with PDFiD
  • Object search and inspection with pdf-parser
  • JavaScript extraction with pdf-parser or peepdf
  • Shellcode emulation with scdbg or speakeasy (optional)
  • Embedded file and URL extraction with hashing
pdf-parser --search "/OpenAction" suspect.pdf pdf-parser --object 5 --filter --raw suspect.pdf peepdf -f -i suspect.pdf

Safety notes: scripts, samples and network

This skill runs scripts. Its metadata states that it runs scripts and that it does not use the network. Even so, the samples are malicious by definition, so only run the analysis on an isolated VM, never on a machine with a PDF reader or sensitive data.

The skill says it is not for viewing or summarising the visual content of a PDF. Do not ask it to render or open the file in a viewer. Review extracted JavaScript and shellcode as data rather than executing it. Keep the source PDF unchanged, and note that the skill's own examples extract files to disk with names based on offsets.

  • Run only in an isolated analysis VM
  • Do not install or use a PDF reader on the analysis machine
  • Treat keyword counts as heuristics, not verdicts
  • Do not use this skill to view rendered content

Tips for better results

Give the agent the file path and the context from the email or report. Ask for the output to be saved to a file so you have a record. If you need a repeatable first-pass checklist, ask the agent to run the same keyword scan and object search on every sample in the same order.

When results conflict, ask the agent to explain which indicators support each conclusion and which are only heuristic. Decoding of Base64, hex or deflate streams can be done with CyberChef, which the skill lists as an optional web tool.

  • Name the file and say why it was flagged
  • Ask for results saved to a file
  • Keep the same step order across samples
  • Ask which indicators are heuristic

What people use it for

  • Triage a phishing attachment that email security flagged, checking for JavaScript and auto-run actions.
  • Give an incident responder a repeatable first-pass checklist for PDF samples.
  • Extract JavaScript from a suspicious PDF for manual review in an isolated VM.
  • Find embedded files in a PDF and compute their hashes for comparison.
  • Teach static analysis of document malware to students using the same workflow each time.

Frequently asked questions

How do I install the PDF malware analysis agent skill?

Download the ZIP from this page and unzip it. Place the folder in ~/.claude/skills/ for personal use or in a project's .claude/skills/ folder, or upload it in the Claude apps under Settings, Capabilities, Skills.

What do I need installed to use this skill?

The skill requires Python 3.8+, Didier Stevens' pdfid and pdf-parser, peepdf, and poppler-utils for pdftotext. YARA with PDF rules, CyberChef, scdbg and speakeasy are optional, and an isolated analysis VM is recommended.

Is this skill free to use?

The skill is licensed under Apache-2.0, as listed on this page. Check the licence file in the package for the full terms. The required tools are installed separately by you.

Does the skill open the PDF or show what it looks like?

No. The skill is for structural analysis of PDF objects and explicitly is not for viewing or summarising the visual content of a PDF. It is designed to examine the file without opening it in a viewer.

Can I trust the skill to say whether a PDF is malicious?

Not on its own. Keyword counts from PDFiD are heuristic and can produce false positives and negatives. Use the output to decide where to look next and confirm findings with deeper analysis.

Why does the skill need an isolated VM?

The samples are malicious, and the skill assumes an isolated analysis environment. Running it on a machine with a PDF reader or sensitive data risks accidental exposure.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

This skill suits security analysts, incident responders and students who want a structured, repeatable static-analysis method for suspicious PDFs, and who can work in an isolated VM. It is not a good choice if you only want to view or summarise a PDF's contents, or if you need a definitive malware verdict from keyword counts alone.

Download the skill