How to use the Email Header Phishing Analyzer agent skill

What the skill makes the agent do

An agent skill is a folder containing a SKILL.md file with instructions, plus optional reference files and scripts that the agent can read and run when a request matches the skill's description. This one covers email header analysis for phishing investigations.

Once installed, the agent can take the raw headers of a suspicious email and walk through them step by step: which servers the message passed through (the Received chain), whether the sender's domain vouches for the message (SPF, DKIM and DMARC results), and whether the sending address or domain looks forged or lookalike. It can also run a helper Python script to parse .eml files and pull out key fields such as From, Reply-To, Return-Path, Message-ID and Authentication-Results.

• Walks the Received chain from the bottom up, which is the chronological order
• Checks SPF, DKIM and DMARC using DNS lookups such as dig
• Flags a Reply-To that differs from From
• Checks for lookalike domains using edit distance
• Produces a structured verdict on whether the sender was likely spoofed

Install the skill from the ZIP download

Download the skill ZIP from this page and unzip it. The skill folder is named analyzing-email-headers-for-phishing-investigation and contains SKILL.md, scripts/agent.py and references/api-reference.md.

For a personal install across all your projects, place the folder in ~/.claude/skills/. To limit it to one project, place it in that project's .claude/skills/ folder instead.

If you use the Claude apps rather than a local setup, you can upload the skill under Settings → Capabilities → Skills.

• Personal: ~/.claude/skills/analyzing-email-headers-for-phishing-investigation/
• Project only: <your-project>/.claude/skills/analyzing-email-headers-for-phishing-investigation/
• Claude apps: Settings → Capabilities → Skills, then upload

Trigger the skill with natural requests

You do not need to name the skill. The skill's description says it applies when triaging a suspicious or reported email, investigating a phishing incident, or verifying whether a sender domain was spoofed. Describe the situation and attach or point to the email file or its headers.

Give the agent the raw headers or the .eml file, not a forwarded summary, because the Received chain and authentication results are only present in the original message source.

• "A user reported this email as phishing. Here are the raw headers. Was the sender spoofed?"
• "Trace the Received chain in case-2024-001/email/phishing_email.eml and tell me which server it came from."
• "Check whether the SPF, DKIM and DMARC results for this message's From domain pass."
• "This message's Reply-To is different from From. Check whether the domain looks like a lookalike of a real brand."

What you need before running it

The core workflow needs Python 3, which includes the standard email library the script uses, and raw email headers in EML format. It also uses DNS tools such as dig for SPF, DKIM and DMARC lookups, so the machine needs network access for those queries.

Some steps are optional. The SPF check uses the pyspf package and the lookalike check uses python-Levenshtein. Parsing Outlook PST files needs pypff. IP and domain reputation checks need an AbuseIPDB or VirusTotal API key.

• Required: Python 3, Python email standard library (included), raw email headers in EML format, DNS tools such as dig
• Optional: pyspf and python-Levenshtein packages
• Optional: pypff for PST files
• Optional: AbuseIPDB or VirusTotal API key for reputation checks

Safety notes: scripts and network use

This skill runs scripts and uses the network. The helper script scripts/agent.py parses files you provide, and the DNS and reputation steps send queries outside your machine. Review the scripts before running them, and keep API keys out of shared files.

Only analyze mail you are authorized to examine. The skill handles private correspondence and forensic evidence, so analyzing a live mailbox without authorization carries legal and privacy risk. Header checks are also one signal and can be wrong for forwarded or mailing-list mail, so do not treat a single result as proof.

• Review scripts/agent.py before running it
• Use only authorized mail and evidence
• Do not rely on one check; forwarded and mailing-list messages can fail SPF or DKIM legitimately

Tips for better results

Export the message source rather than copying the visible text. The source file keeps the full header chain. The source shows how to export from Outlook (File > Properties > Internet Headers), Gmail (Show original) and Thunderbird (View > Message Source).

Keep the case files in one folder so the agent can refer to the same paths across steps. Ask for the reasoning behind a verdict, not just the verdict, so you can check each finding.

• Export the original message source, not a screenshot or forward
• Give the agent the file path and the case folder
• Ask it to show each Received hop and each auth result it relied on
• Verify any important conclusion with your own dig lookups