How to use the PowerShell Malware Deobfuscator agent skill

What an agent skill is and what this one does

An agent skill is a folder of instructions and supporting files that an AI agent can load when a task matches it. This skill is for analysing PowerShell scripts that have been hidden with encoding, string tricks or indirect execution calls.

When you give the agent a suspicious script, it follows a structured process. It identifies which obfuscation techniques are present, such as Base64 encoding, split strings, character-code tricks and repeated Invoke-Expression calls. It decodes what it can and pulls out indicators such as URLs, IP addresses, domains, file paths and registry keys. The bundled Python scripts automate parts of this, and the agent writes up the recovered commands for an analyst to review.

• Identifies techniques such as -EncodedCommand, FromBase64String, string concatenation, [char] arrays, backtick insertion, $env: abuse, SecureString, compression and XOR
• Uses the PSDecode and PowerDecode tools, and optionally CyberChef for manual transformations
• Replaces Invoke-Expression calls with Write-Output to capture the script content that would otherwise run
• Produces a report structured around obfuscation layers, results and extracted indicators

Install the skill in Claude Code or the Claude apps

Download the ZIP of the skill from this page. The ZIP contains the SKILL.md file and its supporting folders, including scripts, references and assets.

For a personal setup, unzip the folder into ~/.claude/skills/ so it is available across your projects. To limit it to one project, unzip it into the .claude/skills/ folder inside that project.

In the Claude apps, you can instead upload the skill under Settings → Capabilities → Skills.

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

Install the tools the skill needs

The skill needs Python 3.9 or later and PowerShell 5.1 or PowerShell 7 or later, since PowerShell provides the AST access the analysis relies on. The scripts also require the regex pip package.

PSDecode is optional but recommended. It is a PowerShell module installed with the command below. PowerDecode is an optional external GitHub project at https://github.com/Malandrone/PowerDecode. CyberChef is optional and useful for manual encoding transformations.

• Python 3.9+ and the regex pip package (used by scripts/process.py)
• PowerShell 5.1+ or PowerShell 7+
• PSDecode (optional)
• PowerDecode (optional, external project)
• CyberChef (optional, for manual transformations)
• An isolated VM or sandbox is recommended for any script execution

Run the skill safely on a suspicious script

Do the analysis inside an isolated virtual machine or sandbox. The skill itself suggests this, and it is the most important precaution. Scripts that execute samples can still cause harm if isolation fails.

Keep the sample inside the isolated environment. Do not copy the agent's output or the sample onto a production machine without review. Only use the skill where you are authorised to analyse the sample; the skill frames its use around authorised testing and analysis.

• Use a VM or sandbox for analysis
• Do not run unknown malware just to see what it does
• Confirm you have authorisation to analyse the sample

Ask the agent for a deobfuscation in plain language

Once the skill is installed, you trigger it by describing the task. Paste or point the agent to the script and say what you need. Useful requests name the outcome you want, such as the final command, the payload location or the C2 endpoints.

Example requests you might type:

• Deobfuscate this PowerShell script from the compromised host and tell me what the final command does.
• This script uses -EncodedCommand. Decode it and list every URL, IP address and domain it contacts.
• Remove the Invoke-Expression layers from this script and show me the payload it drops.
• Identify the obfuscation techniques in this PowerShell file and write up the recovered commands for review.

Review the output and build on it

The agent writes up the recovered commands and indicators for an analyst to check. Treat the result as analysis to verify, not as a final answer. Confirm each recovered command and indicator against the original script before you act on it.

The output follows an analysis report structure: obfuscation layers identified, layer-by-layer results, and extracted indicators grouped into URLs, IP addresses, file system artifacts and registry keys. The skill notes that it maps to MITRE ATT&CK techniques and NIST CSF categories, which can help when writing detections.

• Check each decoded layer against the original script
• Record URLs, IPs, domains, file paths and registry keys as indicators
• Use observed tradecraft to inform detection work