Keep FMA custom script comments admin-facing (new-fma skill)

[allenhouchins]

Related issue: NA

Updates the new-fma Claude Code skill so custom FMA install/uninstall scripts ship with short, admin-facing comments instead of internal engineering history.

Why

FMA install and uninstall scripts are customer-visible and customer-editable:

• MaintainedApp.InstallScript / UninstallScript are JSON-exposed (server/fleet/maintained_apps.go:19-20) and returned by GET /api/_version_/fleet/software/fleet_maintained_apps/{app_id} (server/service/maintained_apps.go:189) and by the software title endpoint (server/fleet/software_installer.go:92,102).
• They render in Ace editors labeled "Install script" / "Uninstall script" in the Edit software modal (frontend/pages/SoftwarePage/components/forms/AdvancedOptionsFields/AdvancedOptionsFields.tsx:93-127), writable outside GitOps mode. FMAs aren't excluded from "Edit software."

So every comment in these scripts is product copy an admin reads. Today a number of shipped scripts open with headers about Fleet's own tooling instead — validator timeouts, "hangs in CI", the ingester, winget metadata archaeology, silentinstallhq.com links, and narratives of what was tried first and why it failed. None of that means anything to a customer reading the script in Fleet.

What changed

One file: .claude/skills/new-fma/SKILL.md.

• New "Custom script comments: these ship to customers" section covering:
  • Why the scripts are customer-visible, with the API and UI surfaces named.
  • A length budget anchored to the existing corpus: template header plus ~4 lines of app-specific comment. Of the 580 scripts in ee/maintained-apps/inputs/*/scripts/, only 51 open with a longer block, so a big header is the exception to justify.
  • A keep list — a comment earns its place only if an editing admin would break something without it or be surprised at install time: host-visible side effects (force-quit, reboot, config deleted), scope/destructiveness decisions, load-bearing switches where the obvious choice is wrong, exit-code meanings.
  • A cut list drawn from what's actually in the scripts today: Fleet-tooling references, catalog archaeology and silentinstallhq/PR links, debugging narrative, first person, and comments restating the next line. These go in the PR body instead.
  • Runtime vs. edit-time: if the fact matters while installing, Write-Host/echo it, since install output surfaces in the host's software install details.
  • A worked before/after on darktable_install.ps1 (20-line header to 4 lines), naming which facts survive and which move to the PR.
  • A prune-on-touch rule so existing bloated headers get cleaned up incrementally.
• New pre-ship checklist item for script comments.
• Widened the skill description so it also triggers on writing or cleaning up an FMA script, not just adding a new FMA.

What this PR does not do

It does not rewrite the 51 over-budget scripts. Each needs its facts checked against the script it documents (as the darktable example was), so that's a separate reviewable change — likely letter-batched like the other FMA workstreams.

Checklist for submitter

• Changes file added for user-visible changes in changes/, orbit/changes/ or ee/fleetd-chrome/changes.
  See Changes files for more information.

  N/A — tooling/docs only. No product code, API, schema, or UI changes; nothing user-visible in a Fleet release.

Testing

• QA'd all new/changed functionality manually

  Verified the claims the guidance rests on before writing it: traced the script text from the datastore through both API responses to the Ace editors in the Edit software modal, and confirmed the editors are writable outside GitOps mode. Measured the comment-block distribution across all 580 scripts in ee/maintained-apps/inputs/*/scripts/ for the length budget. Confirmed the three files the section links to exist, and checked that the condensed darktable header stays faithful to what that script actually does.

  No automated tests — the change is a Markdown skill file with no executable code.

[Copilot]

Pull request overview

Updates the new-fma Claude skill guidance to treat FMA custom install/uninstall script comments as admin-facing “product copy” (since scripts are exposed via API/UI), and adds concrete rules/budget for keeping comments short and relevant.

Changes:

• Expands the skill’s trigger description to include writing/cleaning up custom FMA install/uninstall scripts and reviewing script comments.
• Adds a new “Custom script comments: these ship to customers” section with keep/cut guidance, a length budget, and a darktable before/after example.
• Adds a pre-ship checklist item to enforce the new comment guidance.

Suppressed comments (1)

.claude/skills/new-fma/SKILL.md:117

• This uses the shorthand inputs/*/scripts/, but elsewhere in this skill (and in the repo) the scripts live under ee/maintained-apps/inputs/*/scripts/. Using the full repo-relative path avoids confusion for contributors trying to verify the numbers.

Budget: the Fleet template header (`# Learn more about .exe install scripts:` + URL) if the script started from a template, then **at most ~4 lines** of app-specific comment. Of the 580 scripts in `inputs/*/scripts/`, only 51 open with a longer block than that — a big header is the exception you have to justify, not the norm.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.