pt1987/claude-code-psadt-skill

PSADT v4 → Intune Deployment Skill

A Claude Code skill that drives the full lifecycle of a PowerShell App Deployment Toolkit (PSADT) v4.x Intune Win32 package - from first conversation to a tested, upload-ready .intunewin.

Quick start · How it works · What makes it different · Go deeper · Security · Changelog

---

What is this?

A Claude Code skill: a reusable instruction package that teaches the agent how to build, package, test, troubleshoot and deploy a PSADT v4.x Intune Win32 app. You name the application; the skill runs the workflow - intake, research, scaffolding, all three deployment types (Install / Uninstall / Repair), pre-flight checks, a SYSTEM test, packaging, the dossier, and the optional Graph upload.

It loads progressively: the agent sees only the name and description until a task makes it relevant.

What that looks like in practice

Three applications, none of them packaged here before, each taken to a .intunewin with a GREEN SYSTEM gate on the first attempt. The times are the gate itself, read back from each run’s result.json: all five actions as NT AUTHORITY\SYSTEM in one throwaway sandbox, with the detection script evaluated after every one of them.

Those runs also produced the findings that make the packages correct: draw.io ships an MSI alongside the EXE that installs per-user and would have vanished into the SYSTEM profile; Audacity regenerates its MSI ProductCode on every build, so a ProductCode detection rule works exactly once; VS Code’s uninstaller hands back an exit code while a copy of itself is still deleting. The skill finds that kind of thing before it ships, not after a helpdesk ticket.

Quick start

npx psadt-deploy-skill

Installs the skill into ~/.claude/skills/psadt-deploy and runs the setup doctor, which provisions everything it can and names the handful of values only you can supply. Then open Claude Code in any folder and say what you want:

“Create the Win32 Intune package for 7-Zip 24.09” - or “package Notepad++ for Intune”

The skill asks at most four decision gates (scope · deployment semantics · SYSTEM-test consent · upload confirmation). Everything else it researches and states as an assumption instead of asking.

Details, flags, version pinning and requirements: docs/installation.md.

Uploading to Intune needs an Entra app with the Microsoft Graph application permission DeviceManagementApps.ReadWrite.All, admin-consented. scripts/New-PsadtEntraApp.ps1 creates it in one run; a Global Administrator or Privileged Role Administrator signs in once. Group management and configuration policies are separate opt-in permissions. Everything before the upload, the Windows Sandbox test included, needs no Entra permission. What each permission is for and what the script does: SECURITY.md.

How it works

Thirteen phases, each owned by a script rather than by prose, so a step either passed or did not:

Everything one app knows lives in \psadt-package.json - identity, the decisions taken at the gates, the research findings, every phase’s result and the artifacts produced. The generators write it, every later phase reads and updates it, and pre-flight fails without it. That is what stops two packages of the same app from disagreeing about their own version.

What makes it different

• The installer engine is read from the binary, not guessed from a filename - byte signatures in the PE overlay, resources and section table - and 19 engines’ documented silent switches ship with the skill, offline. A candidate is still a claim until a run proves it.
• The SYSTEM test is real. Every action runs as NT AUTHORITY\SYSTEM through a scheduled task in a throwaway Windows Sandbox - the same context the Intune Management Extension uses - and the verdict is keyed on the detection script, the same rule Intune evaluates. No elevation on your machine, and the machine is never modified.
• An uninstall has to prove it removed something. Inno Setup and NSIS uninstallers return an exit code while a copy of themselves is still deleting; generated hooks wait for the application to disappear and fail loudly if it does not.
• Nothing is deleted that you did not ask to delete - not an older Intune app version, not a foreign .intunewin, not a group, not another app’s assignment.
• A dossier is produced every time, uploaded or not: one self-contained bilingual HTML file with the return-code map, the detection rule, the hooks, the test results - and a ready-to-paste Company-Portal description.
• 1224 Pester tests, including drift guards that fail when the documentation and the code disagree - one of them reads the published landing page and compares its figures against this repository.

Go deeper

Status

In active use for the full build → package → test → dossier workflow, with the direct Graph upload verified against a live tenant. The helper scripts are covered by 1224 Pester tests.

One open point, honestly: the driver pnputil exit-code semantics are documented, not verified here. 0 / 259 / 3010 and the two 0xE... failures come from Microsoft’s documentation; confirming them against setupapi.dev.log on a DEV VM with a real vendor-signed and a real Microsoft-signed driver is still open.

Security

This skill installs software as SYSTEM, researches on the open web, and writes to an Intune tenant through an Entra app with admin consent. SECURITY.md states that risk surface next to the control that already covers each part of it, and each control names the file that implements it and the test that enforces it - so a review can check the claims rather than take them. The Entra permissions the skill holds, and exactly what its setup script creates, are listed under Entra permissions.

Two deliberate non-features: the skill does not declare allowed-tools (that field pre-approves tools, it does not restrict them), and content fetched during research is treated as data, never as instructions - see references/research-trust.md.

Roadmap

Publish finished packages to a private GitHub repository - per version, the package folder and the output folder as two zipped release assets. The .intunewin stays out, because it is rebuilt from the package folder. Private repositories only, credentials from the GitHub CLI, and a secret scan before anything leaves the machine. Have a request? Open an issue.

Contributing

Issues and pull requests are welcome. Keep SKILL.md, the references and the docs in English - the only non-English content is the generated end-user output, whose language follows language.dossier (default German). Two conventions worth knowing before you send a patch: generated .ps1 content is 7-bit ASCII (pre-flight fails on non-ASCII without a BOM), and anything that lands in a package’s output folder must be self-contained, because it gets copied to test clients that have no skill installed.

License

MIT © Patrick Taubert, PHAT Consulting GmbH

Acknowledgements

• PSAppDeployToolkit
• Microsoft Win32 Content Prep Tool
• Invoke-CommandAs
• README structure inspired by ComposioHQ/awesome-claude-skills

Changelog

CHANGELOG.md carries the complete history, every release since 0.1.0, and nothing is ever removed from it.

Latest: 0.50.0 - Packages with no installer. Terraform ships as a ZIP holding one Go binary, and the skill had no route for it: the research ladder named terraform.exe an InstallShield installer off one word in its data section and budgeted three agents. The engine probe now knows zip-archive and portable-binary, the ladder closes the package-owned questions itself (budget 3 -> 1), and New-PortablePackage.ps1 generates the package: the vendor ZIP unchanged, a machine-PATH edit that keeps REG_EXPAND_SZ, an own ARP row with a version-floor detection, a 1618 defer instead of killing a running CLI, and a SYSTEM smoke test of the copied binary. Terraform 1.16.5 went GREEN through the full sandbox gate on the first run. Also fixed on the way: all three generators recorded an empty process list as [null].

Previously: 0.49.4 - The dossier speaks one language at a time. An operator reading a real upload’s dossier found German and English mixed, the assigned groups shown as GUIDs and a logo row that repeated the logo section; reading both language views end to end found twenty more. The German view is German now, return-code types, Intune field labels and SYSTEM-test results included. Groups are recorded and shown by name - the GUIDs were a silent fallback for a group read back before Entra had replicated it. The header, the DEV-VM test rows, the per-hook “tested” badge and the hook contents come from the package instead of literals and PSADT’s own template comments, and the package-file section shows the upload. A test builds both views and fails on any string the language switch cannot reach.

Previously: 0.49.2 - A live two-version run found the skill contradicting itself. Packaging one app twice, end to end, exposed four places where the skill said one thing and did another. The Windows Sandbox kept the package folder mapped for the whole run, so the manifest writes of Phases 7 and 8 - done in that same window by design - failed; the VM now tests a snapshot, and an edit made meanwhile is named instead of tested around. The research ladder never read what the previous version had answered; it now carries those answers for confirmation, and the agent budget of the real second version dropped from 2 to 0. The Gate 2 close prompt never reached the command line; the generators record it, and the upload, the dossier and the sandbox all read it. The logo lookup now waits for the render, repairs a missing viewBox and measures what the picture holds.

Previously: 0.49.1 - The permissions it asks for were written down nowhere a reader looks. SECURITY.md now lists every Entra permission the skill can use - with its flag, its purpose and the script behind it - says who has to sign in, what New-PsadtEntraApp.ps1 does step by step and how to revoke access, and the README names what an upload needs. A sweep for other stale statements fixed the upload’s supersedence hint, which pointed at the portal instead of the script that records the change, and the dossier’s English view, which still showed German detection values and called the SYSTEM test “Phase 5.5”. The JSON store writer no longer loses an update silently when the file is held open, and runs under Windows PowerShell 5.1 again.

Previously: 0.49.0 - The second version of an app started from a blank sheet. Everything learned while packaging an application - the switches that took an afternoon, the uninstaller that has to be renamed first, the app mutex, the leftovers, both decision gates - was recorded in the manifest and then never read again, because every store is keyed by the installer hash and a new version has a new hash. Get-PsadtPriorPackage.ps1 finds the previous package by application identity instead and offers what it learned for confirmation. Purely additive: nothing that passes today starts failing.