AI skill for Flatpak packaging

[besdar]

Hello @bbhtt and the Flatpak team,

In this pull request, I am adding a flatpak-packaging AI assistant skill and short mentions of its location in README.rst and docs/tips-and-tricks.rst. The changes in your documentation only mention where the skill lives and what it is for.

Why include this

More Flatpak developers (and I personally) are using AI coding assistants to draft manifests, choose runtimes, review sandbox permissions, and debug flatpak-builder failures. A repository-local skill gives those assistants a compact, maintainer-reviewable summary of the Flatpak packaging guidance in this repository, instead of forcing each assistant to infer packaging practice from scattered files or stale third-party examples.

Keeping the skill in this repository is useful because it can evolve alongside the documentation it summarizes. When runtime recommendations, permissions, extension guidance, or packaging conventions change, maintainers can review the assistant-facing guidance in the same place as the human-facing docs.

Source documentation

The skill files are self-contained so they remain clear when installed without a local checkout of this repository. The table below records the repository documentation files that were summarized into each bundled reference file:

Skill reference	Repository documentation summarized
references/build-debug.md	docs/first-build.rst, docs/building-introduction.rst, docs/flatpak-builder.rst, docs/debugging.rst, docs/tips-and-tricks.rst, docs/using-flatpak.rst
references/distribution-and-repositories.md	docs/publishing.rst, docs/repositories.rst, docs/hosting-a-repository.rst, docs/single-file-bundles.rst, docs/flatpak-builder.rst
references/extensions.md	docs/dependencies.rst, docs/extension.rst, docs/available-runtimes.rst, docs/conventions.rst
references/framework-notes.md	docs/python.rst, docs/electron.rst, docs/dotnet.rst, docs/qt.rst
references/manifest-and-sources.md	docs/manifests.rst, docs/module-sources.rst, docs/dependencies.rst, docs/first-build.rst
references/runtimes-and-conventions.md	docs/available-runtimes.rst, docs/basic-concepts.rst, docs/dependencies.rst, docs/conventions.rst, docs/desktop-integration.rst
references/sandbox-permissions.md	docs/sandbox-permissions.rst, docs/portals.rst, docs/desktop-integration.rst, docs/debugging.rst

What skills are

Skills are portable instruction folders for AI agents. A skill usually contains a SKILL.md file with trigger metadata and workflow guidance, plus optional reference files, scripts, or assets. AI assistants load the skill when a user asks for a task in that domain, giving the assistant project-specific context and reducing generic or outdated answers.

For background on the AI skills format and ecosystem, see:

• https://agentskills.io
• https://skills.sh/

This change in the documentation only points to the skill folder and describes its purpose. The new files only add optional metadata that AI assistants can use when helping developers package applications with Flatpak.

Thank you for considering this pull request. I am ready to answer any questions or adjust the wording/structure if there is a better fit for the Flatpak documentation repository.

[besdar]

The validation fails because those links don’t exist yet before the merge of this pull request. I can change the links, but I don't know how in this case.

[bbhtt]

Not interested.

I don't want a parallel set of docs just to satisfy LLMs' hunger. It's duplicated effort to maintain these .md alongside .rst.

If you are a beginner and using LLMs for Flatpak packaging, I suggest to not do that and rather read the existing documentation itself. At least that way, we can improve the existing documentation for everyone.