AI skill for Flatpak packaging

README.rst

@@ -21,6 +21,15 @@ Then install the dependencies with **pip**::
 
   pip install -r requirements.txt
 
+AI Assistant Skill
+------------------
+
+This repository also includes optional AI assistant guidance for Flatpak
+packaging in ``skills/flatpak-packaging``. AI assistants can use it to
+help draft manifests, choose runtimes, review sandbox permissions, and debug
+packaging issues. It is assistant metadata only; Flatpak and the documentation
+build do not require it.
+
 Build the Documentation
 -----------------------
 

docs/tips-and-tricks.rst

@@ -191,3 +191,12 @@
 Then after a ``systemctl --user daemon-reload``, those
 ``systemd.resource-control(5)`` parameters will apply to all instances of that
 app.
+
+Flatpak packaging AI assistant skill
+------------------------------------
+
+You can also find the optional AI assistant guidance for Flatpak packaging in 
+https://github.com/flatpak/flatpak-docs/tree/master/skills. AI assistants 
+can use it as context for tasks such as writing manifests, choosing runtimes, 
+reviewing sandbox permissions, and debugging packaging issues. It is assistant 
+metadata only; Flatpak itself does not read or require it.

skills/flatpak-packaging/SKILL.md

@@ -0,0 +1,86 @@
+---
+name: flatpak-packaging
+description: Build, configure, debug, and publish Flatpak applications with flatpak-builder manifests. Use this skill when the user asks you to create or edit Flatpak YAML/JSON manifests, choose runtimes and SDKs, configure finish-args sandbox permissions, add module sources or dependencies, package Python/Electron/.NET/Qt apps, build/install/test with flatpak-builder, inspect or debug sandboxes, create bundles or repositories, write .flatpakref/.flatpakrepo files, or advise on Flatpak app IDs, desktop files, AppStream metadata, extensions, and Flathub-style packaging.
+---
+
+# Flatpak Packaging
+
+## Overview
+
+Use this skill to turn an application into a Flatpak package or to maintain an existing Flatpak manifest. Prefer the project's own build system and upstream metadata, keep sandbox permissions minimal, and verify with `flatpak-builder` whenever the local environment has Flatpak tooling installed.
+
+## First Moves
+
+1. Inspect the project before writing a manifest: application ID, build system, runtime/toolkit, executable command, desktop file, MetaInfo/AppStream file, icons, network/filesystem/device needs, and distribution target.
+2. Check for an existing manifest such as `*.yml`, `*.yaml`, `*.json`, or Flathub packaging. Preserve local style unless it conflicts with Flatpak requirements.
+3. Choose the narrowest runtime that already contains the app's major toolkit. Use Freedesktop for generic apps, GNOME for GNOME/GTK apps, KDE for Qt/KDE apps, and matching SDK branches for builds.
+4. Put the main app module last unless a frequently changing independent module should intentionally be last to improve cache reuse.
+5. Pin downloaded sources with checksums and Git sources with exact commits. Avoid branch-only Git sources for reproducible builds.
+6. Prefer portals and XDG base directories over broad filesystem or D-Bus permissions.
+
+## Reference Routing
+
+- Read `references/manifest-and-sources.md` when creating or changing manifest structure, modules, build systems, cleanup, source types, or bundled dependencies.
+- Read `references/runtimes-and-conventions.md` when choosing runtime/SDK branches or checking app IDs, desktop files, icons, MetaInfo, exported files, D-Bus service files, MIME files, and XDG paths.
+- Read `references/sandbox-permissions.md` when deciding `finish-args`, reducing permissions, using portals, debugging D-Bus access, granting filesystem/device access, or using conditional permissions.
+- Read `references/build-debug.md` when building, installing locally, entering a sandbox, using GDB/strace/valgrind/perf, auditing bus traffic, testing portal permissions, or troubleshooting a failed build/run.
+- Read `references/framework-notes.md` for Python, Electron, .NET, or Qt-specific manifest patterns and generator tooling.
+- Read `references/distribution-and-repositories.md` when creating bundles, repositories, `.flatpakref` or `.flatpakrepo` files, signing, hosting, or publishing updates.
+- Read `references/extensions.md` when defining extension points, consuming SDK/runtime extensions, building app plugins/add-ons, or using bundled extensions.
+
+## Core Workflow
+
+1. Create or edit the manifest:
+
+```yaml
+id: org.example.App
+runtime: org.freedesktop.Platform
+runtime-version: '25.08'
+sdk: org.freedesktop.Sdk
+command: app-command
+finish-args:
+  - --share=ipc
+  - --socket=fallback-x11
+  - --socket=wayland
+  - --device=dri
+modules:
+  - name: app
+    buildsystem: meson
+    sources:
+      - type: git
+        url: https://example.org/app.git
+        tag: v1.0.0
+        commit: 0123456789abcdef0123456789abcdef01234567
+```
+
+2. Build and install locally:
+
+```bash
+flatpak remote-add --if-not-exists --user flathub https://dl.flathub.org/repo/flathub.flatpakrepo
+flatpak-builder --force-clean --user --install-deps-from=flathub --repo=repo --install builddir org.example.App.yml
+flatpak run org.example.App
+```
+
+3. Validate exported desktop metadata:
+
+```bash
+desktop-file-validate path/to/org.example.App.desktop
+appstreamcli validate --explain path/to/org.example.App.metainfo.xml
+```
+
+4. Debug inside the sandbox when runtime behavior differs from the host:
+
+```bash
+flatpak run --command=sh --devel --filesystem="$(pwd)" org.example.App
+flatpak-builder --run builddir org.example.App.yml sh
+flatpak run --log-session-bus org.example.App
+```
+
+5. Package for distribution only after the app installs, launches, and has correct metadata. Repositories are preferred for updates; single-file bundles are for direct sharing or removable media.
+
+## Permission Stance
+
+- Treat `finish-args` as static packaging policy; variables are not expanded inside these arguments.
+- Avoid `--filesystem=home`, `--filesystem=host`, `--socket=session-bus`, `--socket=system-bus`, and `--device=all` unless the app is a development/system tool or no narrower permission works.
+- For GUI apps that support Wayland, use `--socket=wayland` plus `--socket=fallback-x11`; for X11-only apps, use `--socket=x11` and usually `--share=ipc`.
+- Use `:ro` for read-only filesystem needs, XDG directory grants for specific user folders, and `--persist=DIR` for legacy hardcoded dot-directories.

skills/flatpak-packaging/references/build-debug.md

@@ -0,0 +1,155 @@
+# Build and Debug
+
+Related public docs: [Building your first Flatpak](https://docs.flatpak.org/en/latest/first-build.html), [Building Introduction](https://docs.flatpak.org/en/latest/building-introduction.html), [Flatpak Builder](https://docs.flatpak.org/en/latest/flatpak-builder.html), [Debugging](https://docs.flatpak.org/en/latest/debugging.html), [Tips and Tricks](https://docs.flatpak.org/en/latest/tips-and-tricks.html), [Using Flatpak](https://docs.flatpak.org/en/latest/using-flatpak.html).
+
+## Setup and build
+
+Install `flatpak` and `flatpak-builder` from the distribution or from Flathub. For development, add Flathub user-wide:
+
+```bash
+flatpak remote-add --if-not-exists --user flathub https://dl.flathub.org/repo/flathub.flatpakrepo
+```
+
+Build and install a manifest locally:
+
+```bash
+flatpak-builder --force-clean --user --install-deps-from=flathub --repo=repo --install builddir org.example.App.yml
+flatpak run org.example.App
+```
+
+What `flatpak-builder` does:
+
+- Creates the build directory.
+- Downloads and verifies module sources.
+- Builds and installs each module into the app prefix.
+- Applies finish/sandbox metadata.
+- Exports the result to a repository when `--repo` is used.
+
+Useful variants:
+
+```bash
+# Export to a local repo without installing.
+flatpak-builder --force-clean --user --install-deps-from=flathub --repo=repo builddir org.example.App.yml
+
+# Install directly without a separate repo step.
+flatpak-builder --user --install builddir org.example.App.yml
+
+# Sign exported commits.
+flatpak-builder --gpg-sign=<key-id> --repo=repo builddir org.example.App.yml
+```
+
+Use `--gpg-homedir` if the signing key lives outside the default GPG home.
+
+## Run commands inside the sandbox
+
+Use an installed app sandbox:
+
+```bash
+flatpak run --command=sh --devel --filesystem="$(pwd)" org.example.App
+```
+
+Use an uninstalled build tree:
+
+```bash
+flatpak-builder --run builddir org.example.App.yml sh
+flatpak-builder --run builddir org.example.App.yml /app/bin/app-command
+```
+
+`--devel` uses the SDK as runtime and adjusts sandbox setup for debugging.
+
+## Debug symbols and tools
+
+Install debug materials first:
+
+```bash
+flatpak install --include-sdk --include-debug org.example.App
+```
+
+For graphics stack crashes, identify the runtime branch and install GL debug extensions:
+
+```bash
+flatpak info --show-runtime org.example.App
+flatpak install org.freedesktop.Platform.{GL,GL32}.Debug.default//24.08
+```
+
+Inside a debug shell:
+
+```bash
+gdb /app/bin/app-command
+gdb --args /app/bin/app-command --some-arg
+valgrind --leak-check=full --track-origins=yes --show-leak-kinds=all --log-file=valgrind.log /app/bin/app-command
+strace -e trace=openat,read -o strace.log -f /app/bin/app-command
+```
+
+For `perf`, grant `/sys` and a writable output path:
+
+```bash
+flatpak run --command=perf --filesystem=/sys --filesystem="$(pwd)" --devel org.example.App record -v -- <command>
+```
+
+## Coredumps
+
+If systemd coredumps are enabled:
+
+```bash
+coredumpctl list
+flatpak-coredumpctl -m <PID> org.example.App
+(gdb) bt full
+```
+
+## Multiple shells in one sandbox
+
+List running sandbox instances and enter one:
+
+```bash
+flatpak ps
+flatpak enter <instance-id> /bin/bash
+```
+
+Use this when one shell runs the app and another shell attaches a debugger.
+
+## Permissions while debugging
+
+Temporarily add runtime permissions to a debug run rather than broadening the manifest:
+
+```bash
+flatpak run --devel --command=sh --system-talk-name=org.freedesktop.login1 org.example.App
+```
+
+Inspect and reset portal permissions:
+
+```bash
+flatpak permission-show org.example.App
+flatpak permission-reset org.example.App
+```
+
+See running apps and stop one:
+
+```bash
+flatpak ps
+flatpak kill org.example.App
+```
+
+## D-Bus audit
+
+Do not grant `--socket=session-bus` or `--socket=system-bus` when auditing; those disable the useful filtering.
+
+```bash
+flatpak run --log-session-bus org.example.App
+flatpak run --log-session-bus org.example.App | grep '(required 1)'
+flatpak run --log-system-bus --system-talk-name=org.example.Placeholder org.example.App
+```
+
+Translate observed names into narrow `--talk-name=` or `--system-talk-name=` grants only when a portal is not appropriate.
+
+## Test against runtimes
+
+For testing only:
+
+```bash
+flatpak run --runtime-version=master org.example.App
+flatpak run --runtime=org.gnome.Sdk org.example.App
+flatpak run -d org.example.App
+```
+
+Do not treat success on an ABI-incompatible runtime as supported behavior.