nddipiazza/robos / .agents/skills/install-desktop-app
install-desktop-app
VerifiedInstall, configure, and register a desktop application, its FreeDesktop .desktop entry, and icon on GNOME Linux, with support for desktop shortcuts, GNOME Shell favorites, icon caching, and validation.
Install Desktop Application & .desktop Icon on GNOME Linux
Standardized skill and automation engine for installing, configuring, and registering desktop applications, .desktop launcher entries, and application icons on GNOME Linux (Ubuntu, Debian, Fedora, and RobOS appliance desktops).
Complies with the FreeDesktop.org Desktop Entry Specification 1.5, Icon Theme Specification, and GNOME Shell / Desktop Icons NG (DING) standards.
Architecture Overview
flowchart LR
subgraph Source ["Application Source"]
BIN["App Binary / Executable"]
ICON["App Icon (SVG / PNG)"]
end
subgraph Script ["install-desktop-app.sh"]
VAL["desktop-file-validate"]
GEN["Generate .desktop"]
end
subgraph XDG ["FreeDesktop XDG Layer"]
XDG_BIN["~/.local/bin/ (Launcher Wrapper)"]
XDG_ICON["~/.local/share/icons/hicolor/"]
XDG_APP["~/.local/share/applications/"]
end
subgraph Caches ["Caches & Indices"]
GIC["gtk-update-icon-cache"]
UDD["update-desktop-database"]
end
subgraph GNOME ["GNOME Shell Integration"]
DESK["~/Desktop/ (GIO metadata::trusted)"]
DASH["GNOME Dash / Ubuntu Dock (Favorites)"]
GRID["GNOME App Grid & Search Provider"]
end
BIN --> GEN
ICON --> GEN
GEN --> VAL
VAL --> XDG_APP
ICON --> XDG_ICON
BIN --> XDG_BIN
XDG_ICON --> GIC
XDG_APP --> UDD
XDG_APP --> DESK
XDG_APP --> DASH
XDG_APP --> GRID
GIC --> GRID
GIC --> DASH
Image: GNOME Desktop Install Architecture
Input
$ARGUMENTS — Application details and target options:
--app-id <id>(Required): Unique lowercase kebab-case slug (e.g.robos-crpg,godot-editor).--name <name>(Required): Display name (e.g."RobOS cRPG: Realm of Heroes").--exec <command>(Required): Executable binary or invocation command line.--icon <path>: Path to SVG/PNG icon file or theme icon name.--desktop: Create and trust launchable desktop shortcut in~/Desktop/.--favorite/--dock: Pin app to GNOME Shell favorites dock.--path <dir>: Set working directory (Path=...).--categories <list>: Semicolon-delimited categories (e.g."Game;RolePlaying;").--comment <text>: Tooltip and search description.--wrapper: Generate a wrapper script in~/.local/bin/<app-id>.--scope <user|system>: Target scope (userdefault to~/.local/share/, orsystemto/usr/share/).
Procedures
1. Automated Installation via Script
Use the bundled automation utility:
plugins/robos/skills/install-desktop-app/scripts/install-desktop-app.sh \
--app-id <app-id> \
--name "<Display Name>" \
--exec "<executable command>" \
--icon "<path/to/icon.svg>" \
--path "<working-directory>" \
--categories "Utility;Development;" \
--desktop \
--favorite
2. Manual / Step-by-Step Procedure
When performing manual setup or customizing entries:
Step 1: Multi-Scale Icon Placement & Cache Update
GNOME Shell and Ubuntu Dock require raster PNGs across standard sizes (16x16 through 512x512) in the hicolor theme to render taskbar/dock icons reliably without falling back to the missing gear icon.
- Scalable Vector Icons (SVG):
mkdir -p ~/.local/share/icons/hicolor/scalable/apps ~/.local/share/pixmaps cp icon.svg ~/.local/share/icons/hicolor/scalable/apps/<app-id>.svg cp icon.svg ~/.local/share/pixmaps/<app-id>.svg chmod 644 ~/.local/share/icons/hicolor/scalable/apps/<app-id>.svg - Multi-Scale Raster Icons (PNG):
for s in 16 24 32 48 64 128 256 512; do mkdir -p ~/.local/share/icons/hicolor/${s}x${s}/apps python3 -c "import gi; gi.require_version('GdkPixbuf', '2.0'); from gi.repository import GdkPixbuf; GdkPixbuf.Pixbuf.new_from_file_at_scale('icon.svg', $s, $s, True).savev('$HOME/.local/share/icons/hicolor/${s}x${s}/apps/<app-id>.png', 'png', [], [])" done cp ~/.local/share/icons/hicolor/256x256/apps/<app-id>.png ~/.local/share/pixmaps/<app-id>.png - Dual-Key / Alias Installation:
If the running window's
WM_CLASSdiffers from<app-id>(e.g.robos-task-plannervsrobos-task-explorer), install / symlink icons under<wm-class>as well so dock lookups succeed via either key. - Update GTK Icon Cache:
gtk-update-icon-cache -f -t ~/.local/share/icons/hicolor
Step 2: Native Electron Window Icon (_NET_WM_ICON)
Electron's BrowserWindow({ icon: ... }) only supports raster PNG images on Linux. If passed an SVG, Electron cannot set _NET_WM_ICON on the X11 window. Always keep a companion icon.png in the package directory and pass:
const iconPng = path.join(__dirname, 'icon.png');
const win = new BrowserWindow({
title: 'My RobOS App',
icon: fs.existsSync(iconPng) ? iconPng : path.join(__dirname, 'icon.svg'),
...
});
Step 3: Generate Desktop Entry
Create ~/.local/share/applications/<app-id>.desktop:
[Desktop Entry]
Version=1.5
Type=Application
Name=<Display Name>
GenericName=<Generic Name>
Comment=<Description>
Exec=<exec-command> %U
Icon=<app-id>
Path=<working-directory>
Terminal=false
Categories=<Categories;>
Keywords=<search;keywords;>
StartupWMClass=<wm-class>
StartupNotify=true
X-RobOS-App=true
Step 3: Validate and Register
- Validate desktop syntax:
desktop-file-validate ~/.local/share/applications/<app-id>.desktop - Update desktop database:
update-desktop-database ~/.local/share/applications
Step 4: GNOME Desktop Shortcut (DING Extension)
For GNOME Desktop Icons NG (DING) to display and launch the desktop shortcut without prompting "Untrusted Application":
cp ~/.local/share/applications/<app-id>.desktop ~/Desktop/
chmod +x ~/Desktop/<app-id>.desktop
gio set ~/Desktop/<app-id>.desktop metadata::trusted true
Step 5: GNOME Shell Favorites (Dock Pinning)
To pin the application to the left-hand Ubuntu dock / GNOME Shell dash:
# Read current favorites
CURRENT="$(gsettings get org.gnome.shell favorite-apps)"
# Add <app-id>.desktop if not already present
gsettings set org.gnome.shell favorite-apps "$(echo "$CURRENT" | sed "s/]$/, '<app-id>.desktop']/")"
Validation & Verification
- Check file validity:
desktop-file-validate ~/.local/share/applications/<app-id>.desktop - Verify GIO recognition:
gio info ~/.local/share/applications/<app-id>.desktop gio info ~/Desktop/<app-id>.desktop | grep "metadata::trusted" - Test launcher from terminal:
gtk-launch <app-id>
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack." | Stars: 196k | Updated | Claude CodeCodex | Verified | Install |
| ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read. | Stars: 192k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report. | Stars: 192k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt. | Stars: 192k | Updated | Claude CodeCodex | Verified | Install |