diff --git a/CODEOWNERS b/CODEOWNERS
index 4865d7ca..4a6092d8 100644
--- a/CODEOWNERS
+++ b/CODEOWNERS
@@ -1,2 +1,3 @@
 /docs/standard/ @publiccodeyml/steering-committee
 /governance/ @publiccodeyml/steering-committee
+/skills/ @tomootes
diff --git a/skills/generate-publiccode-yml/ARCHITECTURE.md b/skills/generate-publiccode-yml/ARCHITECTURE.md
new file mode 100644
index 00000000..50614ff4
--- /dev/null
+++ b/skills/generate-publiccode-yml/ARCHITECTURE.md
@@ -0,0 +1,2 @@
+For swiftness, use the don-checker for linting, which is an NPM package:
+- https://github.com/developer-overheid-nl/don-checker
\ No newline at end of file
diff --git a/skills/generate-publiccode-yml/README.md b/skills/generate-publiccode-yml/README.md
new file mode 100644
index 00000000..d9e23e01
--- /dev/null
+++ b/skills/generate-publiccode-yml/README.md
@@ -0,0 +1,39 @@
+# `generate-publiccode-yml` skill
+
+An [Agent Skills](https://agentskills.io) skill that teaches an AI agent to
+create, update and validate a
+[`publiccode.yml`](https://publiccodeyml.github.io) file for any
+repository, following the latest released version of the Standard.
+
+## Layout
+
+- `SKILL.md`: the skill itself: workflow, mandatory keys, enum rules,
+  deprecation table and file conventions.
+- `reference/`: the Standard's schema and controlled vocabularies,
+  **copied from `docs/standard/`** with `scripts/sync-reference.sh`.
+  The source of truth is `docs/standard/`; run the sync script whenever the
+  Standard changes so the skill never drifts from the release it ships in.
+- `reference/validation.md`: how to validate a `publiccode.yml` with the
+  official tooling (libpubliccode, GitHub Action, GitLab CI, editor
+  integration, web editor).
+
+## Using the skill
+
+Point any agent that supports Agent Skills at this directory, use for example `npx skills`:
+
+```bash
+npx skills add https://github.com/publiccodeyml/publiccode.yml/tree/main/skills/generate-publiccode-yml
+```
+
+Or copy/symlink the directory into your agent's skills folder.
+
+## Versioning
+
+The skill tracks the released Standard living in this repository: it is
+pinned to the version shipped in its own checkout. Update
+`publiccodeYmlVersion` guidance in `SKILL.md` when a new major version line
+of the Standard is released.
+
+## License
+
+CC0-1.0, same as the Standard itself.
diff --git a/skills/generate-publiccode-yml/SKILL.md b/skills/generate-publiccode-yml/SKILL.md
new file mode 100644
index 00000000..4b1d17ad
--- /dev/null
+++ b/skills/generate-publiccode-yml/SKILL.md
@@ -0,0 +1,125 @@
+---
+name: generate-publiccode-yml
+description:
+  Create, update or validate a publiccode.yml metadata file for a repository.
+  Use this skill whenever the user works on software developed by or for
+  public administrations and wants to make it discoverable in public software
+  catalogs, mentions publiccode.yml or publiccode.yml keys, or asks to add
+  metadata to a government/public-sector repository — even if they only say
+  things like "make this repo ready for the catalog" or "describe this
+  project for reuse".
+license: CC0-1.0
+metadata:
+  author: Tom Ootes (developer.overheid.nl)
+---
+
+# publiccode.yml author
+
+`publiccode.yml` is the metadata file that national and international
+software catalogs (developers.italia.it, opencode.de, …) crawl to index
+public-sector software. This skill writes a valid file and keeps existing
+ones up to date.
+
+The Standard is versioned; target the latest released major line (currently
+v0, latest release v0.8.0). The full specification is in
+`reference/schema.core.rst` — consult it for any key you are unsure about
+instead of guessing.
+
+## Workflow
+
+1. **Look for an existing `publiccode.yml`** in the repository root. If one
+   exists, update it: preserve values that are still true, fix what has
+   drifted, and remove deprecated keys (see below).
+2. **Gather information** about the project before writing anything:
+   - `README.md` for name, purpose, features and links;
+   - API specifications (`openapi.json`, `swagger.json`, …): reuse their
+     `info.description` for the longDescription, and link them under
+     `description/[lang]/apiDocumentation` when hosted;
+   - package manifests (`package.json`, `pyproject.toml`, `pom.xml`,
+     `Cargo.toml`, `go.mod`, …) for name, description and license;
+   - the git remote URL for `url` (use the HTTP(S) clone URL without
+     login credentials);
+   - a `LICENSE`/`LICENCE` file: map it to its SPDX identifier;
+   - CI/CD configs or docs for a live deployment URL (`landingURL`) and
+     documentation links.
+   For GitHub/GitLab repositories, the organization page shows the display
+   name of the publishing organization — use that display name (not the URL
+   slug) for `organisation/name` and `legal/mainCopyrightOwner`.
+3. **Write the file** following the conventions below.
+4. **Validate** with don-checker:
+   `npx @developer-overheid-nl/don-checker@latest validate --standard publiccode --input ./publiccode.yml`
+   — and cross-check with the reference parser when available. More
+   options in `reference/validation.md`. Fix all errors; report warnings
+   honestly to the user.
+
+Never invent facts. Values like contact persons, `legal/mainCopyrightOwner`
+or `fundedBy` are factual claims: if the repository does not reveal them,
+leave the key out or ask the user.
+
+## Mandatory keys
+
+Every file needs: `publiccodeYmlVersion: "0"`, `name`, `url`, `platforms`,
+`developmentStatus`, `softwareType`, `description` (at least one BCP 47
+language with `shortDescription` and a `longDescription` of 150–10000
+chars), `legal/license` (SPDX expression), `maintenance/type`,
+`localisation/localisationReady` + `availableLanguages`.
+
+Conditional rules: `maintenance/contractors` only when
+`maintenance/type` is `contract`; `maintenance/contacts` mandatory when the
+type is `internal` or `community`. Contacts must be natural persons — put
+organizations in `affiliation`.
+
+## Choosing enum values
+
+`softwareType` — decide in this order:
+- plugin manifest or explicit extension of another application → `addon`
+- only configuration files, no executable code → `configurationFiles`
+- reusable library/SDK without UI → `library`
+- web interface → `standalone/web`
+- background service or API without its own UI → `standalone/backend`
+- desktop → `standalone/desktop`, mobile → `standalone/mobile`,
+  IoT → `standalone/iot`; anything else → `standalone/other`
+
+`categories` and `intendedAudience/scope` only accept values from
+`reference/categories-list.rst` and `reference/scope-list.rst`. Pick the
+closest category that exists (or `other`) — never invent a new one. For
+`supports/id`, only aliases listed in `reference/aliases-list.rst` are valid.
+
+`name` is the product's public name in normal capitalization — not the
+repository slug in kebab-case, camelCase or snake_case.
+
+## Deprecated keys — never add, remove when found
+
+`usedBy`, `videos`, `intendedAudience/unsupportedCountries`,
+`dependsOn/open`, `description/[lang]/genericName`, `monochromeLogo`,
+`inputTypes`, `outputTypes`, `legal/repoOwner` (→ `organisation/name`),
+`legal/authorsFile`, scope `government`, the single-string form of
+`isBasedOn` (use a one-element array), and all `it.*` country-specific
+sections (→ `supports`).
+
+## File conventions
+
+- UTF-8, YAML 1.2. Quote `"0"` in `publiccodeYmlVersion`.
+- Since v0.8.0, `description/[lang]/longDescription` is Markdown. Use a
+  YAML **literal** block (`|`) when the Markdown contains line-sensitive
+  structures (lists, links on separate lines); the **folded** form (`>`),
+  as in the official examples, is fine for plain prose. Short lines (~80
+  chars) keep diffs readable.
+- `shortDescription` ≤ 150 chars, single sentence. Write it as a folded
+  scalar with strip chomping (`>-`) when wrapping over multiple lines:
+  the lines merge back into one contiguous sentence.
+- Do not add `releaseDate` or `softwareVersion` while generating — they
+  drift out of date immediately. Remove them from existing files on
+  request.
+- Dates are `YYYY-MM-DD` only. Phone numbers are strings, preferably E.164
+  (`+39…`).
+- Insert a blank line between top-level sections for readability.
+- Put user documentation under `description/[lang]/documentation`,
+  API docs under `apiDocumentation`.
+
+## Examples
+
+`reference/examples/publiccode.minimal.yml` shows the smallest valid file;
+`reference/examples/publiccode.yml` shows an extended one. When updating an
+existing file, aim for minimal changes — catalogs re-crawl the file, so
+keep the diff reviewable.
diff --git a/skills/generate-publiccode-yml/reference/aliases-list.rst b/skills/generate-publiccode-yml/reference/aliases-list.rst
new file mode 100644
index 00000000..0650c068
--- /dev/null
+++ b/skills/generate-publiccode-yml/reference/aliases-list.rst
@@ -0,0 +1,22 @@
+.. _aliases-list:
+
+List of aliases
+===============
+
+Here follows the list of aliases that can be used in the
+``supports`` key. Each alias resolves to the canonical resource it
+refers to.
+
+========  ===============================================
+alias     resource
+========  ===============================================
+gdpr      https://eur-lex.europa.eu/eli/reg/2016/679/oj
+eidas     https://eur-lex.europa.eu/eli/reg/2014/910/oj
+nis2      https://eur-lex.europa.eu/eli/dir/2022/2555/oj
+cra       https://eur-lex.europa.eu/eli/reg/2024/2847/oj
+spid      https://www.spid.gov.it/
+cie       https://www.cartaidentita.interno.gov.it/
+anpr      https://www.anpr.interno.it/
+pagopa    https://www.pagopa.gov.it/
+io        https://io.italia.it/
+========  ===============================================
diff --git a/skills/generate-publiccode-yml/reference/categories-list.rst b/skills/generate-publiccode-yml/reference/categories-list.rst
new file mode 100644
index 00000000..6180072c
--- /dev/null
+++ b/skills/generate-publiccode-yml/reference/categories-list.rst
@@ -0,0 +1,118 @@
+.. _categories-list:
+
+List of software categories
+===========================
+
+Here follows a controlled vocabulary of allowed categories for the software.
+
+================
+Valid categories
+================
+
+- accounting
+- agile-project-management
+- applicant-tracking
+- application-development
+- appointment-scheduling
+- backup
+- billing-and-invoicing
+- building-information-modelling
+- blog
+- budgeting
+- business-intelligence
+- business-process-management
+- cad
+- call-center-management
+- cloud-management
+- collaboration
+- communications
+- compliance-management
+- contact-management
+- content-management
+- crm
+- customer-service-and-support
+- data-analytics
+- data-collection
+- data-visualization
+- design
+- design-system
+- digital-asset-management
+- digital-citizenship
+- document-management
+- donor-management
+- e-commerce
+- e-signature
+- educational-content
+- email-management
+- email-marketing
+- employee-management
+- enterprise-project-management
+- enterprise-social-networking
+- erp
+- event-management
+- facility-management
+- feedback-and-reviews-management
+- financial-reporting
+- fleet-management
+- fundraising
+- gamification
+- geographic-information-systems
+- grant-management
+- graphic-design
+- help-desk
+- hr
+- ide
+- identity-management
+- instant-messaging
+- integrated-library-system
+- inventory-management
+- it-asset-management
+- it-development
+- it-management
+- it-security
+- it-service-management
+- knowledge-management
+- learning-management-system
+- marketing
+- mind-mapping
+- mobile-marketing
+- mobile-payment
+- network-management
+- office
+- online-booking
+- online-community
+- payment-gateway
+- payroll
+- predictive-analysis
+- procurement
+- productivity-suite
+- project-collaboration
+- project-management
+- property-management
+- real-estate-management
+- regulations-and-directives
+- remote-support
+- resource-management
+- sales-management
+- seo
+- service-desk
+- social-media-management
+- survey
+- talent-management
+- task-management
+- taxes-management
+- test-management
+- time-management
+- time-tracking
+- translation
+- video-conferencing
+- video-editing
+- visitor-management
+- voip
+- warehouse-management
+- web-collaboration
+- web-conferencing
+- website-builder
+- whistleblowing
+- workflow-management
+- other
diff --git a/skills/generate-publiccode-yml/reference/examples/publiccode.minimal.yml b/skills/generate-publiccode-yml/reference/examples/publiccode.minimal.yml
new file mode 100644
index 00000000..bba0dd83
--- /dev/null
+++ b/skills/generate-publiccode-yml/reference/examples/publiccode.minimal.yml
@@ -0,0 +1,36 @@
+publiccodeYmlVersion: "0"
+
+name: Medusa
+url: "https://example.com/italia/medusa.git"
+platforms:
+  - web
+
+developmentStatus: development
+
+softwareType: "standalone/desktop"
+
+description:
+  en:
+    shortDescription: >
+      A rather short description which
+      is probably useless
+
+    longDescription: >
+      Very long description of this software, also split
+      on multiple rows. You should note what the software
+      is and why one should need it. We can potentially
+      have many pages of text here.
+
+legal:
+  license: AGPL-3.0-or-later
+
+maintenance:
+  type: "community"
+
+  contacts:
+    - name: Francesco Rossi
+
+localisation:
+  localisationReady: true
+  availableLanguages:
+    - en
diff --git a/skills/generate-publiccode-yml/reference/examples/publiccode.yml b/skills/generate-publiccode-yml/reference/examples/publiccode.yml
new file mode 100644
index 00000000..426c87f9
--- /dev/null
+++ b/skills/generate-publiccode-yml/reference/examples/publiccode.yml
@@ -0,0 +1,105 @@
+publiccodeYmlVersion: "0"
+
+name: Medusa
+applicationSuite: MegaProductivitySuite
+url: "https://example.com/italia/medusa.git"
+landingURL: "https://example.com/italia/medusa"
+isBasedOn:
+  - "https://github.com/italia/otello.git"
+softwareVersion: "1.0"
+releaseDate: "2017-04-15"
+logo: img/logo.svg
+
+platforms:
+  - android
+  - ios
+
+categories:
+  - content-management
+  - office
+
+usedBy:
+  - Comune di Firenze
+  - Comune di Roma
+
+roadmap: "https://example.com/italia/medusa/roadmap"
+
+developmentStatus: development
+
+softwareType: "standalone/desktop"
+
+intendedAudience:
+  scope:
+    - science-and-technology
+  countries:
+    - IT
+    - DE
+
+description:
+  en:
+    localisedName: Medusa
+    shortDescription: >
+      This description can have a maximum 150
+      characters long. We should not fill the
+      remaining space with "Lorem Ipsum". End
+
+    longDescription: >
+      Very long description of this software, also split
+      on multiple rows. You should note what the software
+      is and why one should need it.
+      It can also contain some basic Markdown.
+
+    documentation: "https://read.the.documentation/medusa/v1.0"
+    apiDocumentation: "https://read.the.api.doc/medusa/v1.0"
+
+    features:
+      - Very important feature
+      - Will run without a problem
+      - Has zero bugs
+      - Solves all the problems of the world
+    screenshots:
+      - img/sshot1.jpg
+      - img/sshot2.jpg
+      - img/sshot3.jpg
+    awards:
+      - 1st Price Software of the year
+
+legal:
+  license: AGPL-3.0-or-later
+  mainCopyrightOwner: City of Chicago
+
+maintenance:
+  type: "contract"
+
+  contractors:
+    - name: "Fornitore Privato SPA"
+      email: "dario.bianchi@fornitore.it"
+      website: "https://privatecompany.com"
+      until: "2019-01-01"
+
+  contacts:
+    - name: Francesco Rossi
+      email: "francesco.rossi@comune.reggioemilia.it"
+      affiliation: Comune di Reggio Emilia
+      phone: "+3923113215112"
+
+localisation:
+  localisationReady: true
+  availableLanguages:
+    - en
+    - it
+    - fr
+    - de
+
+dependsOn:
+  proprietary:
+    - name: Oracle
+      versionMin: "11.4"
+    - name: IBM SoftLayer
+  hardware:
+    - name: NFC Reader
+      optional: true
+
+organisation:
+  uri: urn:x-italian-pa:c_h501
+  name: Roma Capitale
diff --git a/skills/generate-publiccode-yml/reference/schema.core.rst b/skills/generate-publiccode-yml/reference/schema.core.rst
new file mode 100644
index 00000000..b74e8495
--- /dev/null
+++ b/skills/generate-publiccode-yml/reference/schema.core.rst
@@ -0,0 +1,906 @@
+.. _core:
+
+The Standard
+============
+
+This document represents the description of the ``publiccode.yml``
+schema.
+
+Top-Level Keys and Sections
+---------------------------
+
+Key ``publiccodeYmlVersion``
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+-  Type: string
+-  Presence: mandatory
+-  Example: ``"0.1"``
+
+This key specifies the version to which the current ``publiccode.yml``
+adheres to, for forward compatibility.
+
+Key ``name``
+~~~~~~~~~~~~
+
+-  Type: string
+-  Presence: mandatory
+-  Example: ``"Medusa"``
+
+This key contains the name of the software. It contains the (short)
+public name of the product, which can be localised in the specific
+``localisation`` section. It should be the name most people usually
+refer to the software. In case the software has both an internal “code”
+name and a commercial name, use the commercial name.
+
+Key ``applicationSuite``
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+-  Type: string
+-  Presence: optional
+-  Example: ``"MegaProductivitySuite"``
+
+This key contains the name of the “suite” to which the software belongs.
+
+Key ``url``
+~~~~~~~~~~~
+
+-  Type: string (URL)
+-  Presence: mandatory
+-  Example: ``"https://example.com/italia/medusa.git"``
+
+A unique identifier for this software. This string must be a URL to the
+source code repository (git, svn, …) in which the software is published.
+If the repository is available under multiple protocols, prefer
+HTTP/HTTPS URLs which don’t require user authentication.
+
+Forks created for the purpose of contributing upstream should not
+modify this file; this helps software parsing ``publiccode.yml`` to
+immediately skip technical forks. On the contrary, a
+complete fork that is meant to be maintained separately from the
+original software should modify this line, to give themselves the status
+of a different project.
+
+See :ref:`forks-and-variants` for a complete description of what
+is a software variant and how to handle forked software as a parser or
+an author.
+
+Key ``landingURL``
+~~~~~~~~~~~~~~~~~~
+
+-  Type: string (URL)
+-  Presence: optional
+-  Example: ``"https://example.com/italia/medusa"``
+
+If the ``url`` parameter does not serve a human readable or browsable
+page, but only serves source code to a source control client, with this
+key you have an option to specify a landing page. This page, ideally, is
+where your users will land when they will click a button labeled
+something like “Go to the application source code”. In case the product
+provides an automated graphical installer, this URL can point to a page
+which contains a reference to the source code but also offers the
+download of such an installer.
+
+Key ``isBasedOn``
+~~~~~~~~~~~~~~~~~
+
+-  Type: array of strings, or a single string (*deprecated*)
+-  Presence: optional
+-  Example: ``["https://github.com/italia/otello.git"]``
+
+In case this software is a variant or a fork of another software, which
+might or might not contain a ``publiccode.yml`` file, this key will
+contain the ``url`` of the original project(s).
+
+The existence of this key identifies the fork as a software
+variant, descending from the specified repositories.
+
+The single string form is deprecated, use a one element array
+instead.
+
+Key ``softwareVersion``
+~~~~~~~~~~~~~~~~~~~~~~~
+
+-  Type: string
+-  Presence: optional
+-  Example: ``"1.0"``, ``"dev"``
+
+This key contains the latest stable version number of the software. The
+version number is a string that is not meant to be interpreted and
+parsed but just displayed; parsers should not assume semantic versioning
+or any other specific version format.
+
+Key ``releaseDate``
+~~~~~~~~~~~~~~~~~~~
+
+-  Type: string (date)
+-  Presence: optional
+-  Example: ``"2017-04-15"``
+
+This key contains the date at which the latest version was released.
+
+Key ``logo``
+~~~~~~~~~~~~
+
+-  Type: string (relative path to file or absolute URL)
+-  Presence: optional
+-  Acceptable formats: SVG, SVGZ, PNG, JPEG, WebP, AVIF
+-  Example: ``"img/logo.svg"``
+
+This key contains the path to the logo of the software. Logos SHOULD be
+in vector format.
+The key value can be the relative path to the file starting from the root of
+the repository, or it can be an absolute URL pointing to the logo in raw
+version. In both cases, the file must reside inside the same repository where
+the ``publiccode.yml`` file is stored.
+
+Key ``monochromeLogo`` (*deprecated*)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+-  Type: string (path to file)
+-  Presence: optional
+-  Acceptable formats: SVG, SVGZ, PNG
+-  Example: ``"img/logo-mono.svg"``
+
+A monochromatic (black) logo. The logo should be in vector format;
+raster formats are only allowed as a fallback. In this case, they should
+be transparent PNGs, minimum 1000px of width.
+The key value can be the relative path to the file starting from the root of
+the repository, or it can be an absolute URL pointing to the logo in raw
+version. In both cases, the file must reside inside the same repository where
+the ``publiccode.yml`` file is stored.
+
+Key ``inputTypes`` (*deprecated*)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+-  Type: array of enumerated strings
+-  Presence: optional
+-  Values: as per RFC 6838
+-  Example: ``"text/plain"``
+
+A list of Media Types (MIME Types) as mandated in `RFC
+6838 <https://www.rfc-editor.org/rfc/rfc6838.html>`__ which the application can
+handle as input.
+
+In case the software does not support any input, you can skip this field
+or use ``application/x.empty``.
+
+Key ``outputTypes`` (*deprecated*)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+-  Type: array of enumerated strings
+-  Presence: optional
+-  Values: as per RFC 6838
+-  Example: ``"text/plain"``
+
+A list of Media Types (MIME Types) as mandated in `RFC
+6838 <https://www.rfc-editor.org/rfc/rfc6838.html>`__ which the application can
+handle as output.
+
+In case the software does not support any output, you can skip this
+field or use ``application/x.empty``.
+
+Key ``platforms``
+~~~~~~~~~~~~~~~~~
+
+-  Type: enumerated string or array of strings
+-  Presence: mandatory
+-  Values: ``web``, ``windows``, ``mac``, ``linux``, ``ios``,
+   ``android``. Human readable values outside this list are allowed.
+-  Example: ``web``
+
+This key specifies which platform the software runs on. It is meant to
+describe the platforms that users will use to access and operate the
+software, rather than the platform the software itself runs on.
+
+Use the predefined values if possible. If the software runs on a
+platform for which a predefined value is not available, a different
+value can be used.
+
+Key ``categories``
+~~~~~~~~~~~~~~~~~~
+
+-  Type: array of strings
+-  Presence: optional
+-  Acceptable values: see :ref:`categories-list` 
+
+A list of categories that can be used to describe the software and can help
+building catalogs of open software.
+
+The controlled vocabulary :ref:`categories-list` contains the list of allowed
+values.
+
+Key ``usedBy`` (*deprecated*)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+-  Type: array of strings
+-  Presence: optional
+
+A list of the names of prominent public administrations (that will serve
+as “testimonials”) that are currently known to the software maintainer
+to be using this software.
+
+Parsers are encouraged to enhance this list also with other information
+that can obtain independently; for instance, a fork of a software, owned
+by an administration, could be used as a signal of usage of the
+software.
+
+Key ``fundedBy``
+~~~~~~~~~~~~~~~~
+
+-  Type: List of Organisations (see below)
+-  Presence: optional
+
+A list of organisations that are currently known to be funding the
+development of this software.
+
+Key ``roadmap``
+~~~~~~~~~~~~~~~
+
+-  Type: string
+-  Presence: optional
+
+A link to a public roadmap of the software.
+
+Key ``developmentStatus``
+~~~~~~~~~~~~~~~~~~~~~~~~~
+
+-  Type: enumerated string
+-  Presence: mandatory
+-  Allowed values: ``concept``, ``development``, ``beta``, ``stable``,
+   ``obsolete``
+
+The keys are: 
+
+-  ``concept`` - The software is just a “concept”. No
+   actual code may have been produced, and the repository could simply be a
+   placeholder. 
+-  ``development`` - Some effort has gone into the
+   development of the software, but the code is not ready for the end user,
+   even in a preliminary version (beta or alpha) to be tested by end users.
+-  ``beta`` - The software is in the testing phase (alpha or beta). At
+   this stage, the software might or might not have had a preliminary
+   public release. 
+-  ``stable`` - The software has seen a first public
+   release and is ready to be used in a production environment.
+-  ``obsolete`` - The software is no longer maintained or kept up to date.
+   All of the source code is archived and kept for historical reasons.
+
+Key ``softwareType``
+~~~~~~~~~~~~~~~~~~~~
+
+-  Type: enumerated string
+-  Presence: mandatory
+-  Allowed values: ``"standalone/mobile"``, ``"standalone/iot"``,
+   ``"standalone/desktop"``, ``"standalone/web"``, ``"standalone/backend"``,
+   ``"standalone/other"``, ``"addon"``, ``"library"``, ``"configurationFiles"``
+
+The keys are:
+
+-  ``standalone/mobile`` - The software is a standalone application, typically
+   installed and run on a mobile operating system.
+-  ``standalone/iot`` - The software is suitable for an IoT context.
+-  ``standalone/desktop`` - The software is typically installed and run in
+   a desktop operating system environment.
+-  ``standalone/web`` - The software is a web application that runs on a server
+   and is accessible through a web browser.
+-  ``standalone/backend`` - The software is a backend application that provides
+   interfaces (e.g., APIs) for other services. Typically it does not provide
+   direct user interfaces.
+-  ``standalone/other`` - The software has a different nature from the ones
+   listed above.
+-  ``addon`` - The software is an addon, such as a plugin or a
+   theme, for a more complex software (e.g. a CMS or an office suite).
+-  ``library`` - The software is a library or SDK intended to be used
+   by developers in other software projects.
+-  ``configurationFiles`` - The software does not contain executable
+   script but a set of configuration files. They may document how to
+   obtain a certain deployment. They could be in the form of plain
+   configuration files, bash scripts, ansible playbooks, Dockerfiles, or
+   other instruction sets.
+
+Key ``supports``
+~~~~~~~~~~~~~~~~
+
+-  Type: array of objects
+-  Presence: optional
+
+A list of standards, regulations, frameworks or systems that the
+software supports or complies with.
+
+Each item is an object with a single property:
+
+-  ``id`` - **mandatory** - an identifier for the supported standard,
+   regulation, framework or system. It is either an alias in
+   the form ``alias:<name>`` (e.g. ``alias:gdpr``), resolved through the
+   :ref:`list of aliases <aliases-list>`, or any other valid URI (URL or
+   URN) referencing the resource directly.
+
+   An ``alias:`` value MUST exist in the
+   :ref:`list of aliases <aliases-list>`. An unknown alias is an error.
+   Any other value MUST be a syntactically valid URI. A value that is
+   well formed but not otherwise known is accepted as is.
+
+Example:
+
+.. code:: yaml
+
+   supports:
+     - id: alias:gdpr
+     - id: https://eur-lex.europa.eu/eli/reg/2016/679/oj
+
+Section ``organisation``
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+This optional section provides the organisation publishing the software.
+
+Key ``organisation/uri``
+''''''''''''''''''''''''
+
+-  Type: string
+-  Presence: mandatory
+-  Example: ``"https://example.org/my-organisation"``, ``"urn:x-foobar:my-organisation"``
+
+The URI identifying the organisation publishing the software. The value
+SHOULD be a stable, resolvable URI or a persistent identifier.
+
+Parsers MAY use the URI structure to extract additional information if it follows a
+recognized format (for example, inferring an institutional domain or an
+official code).
+
+It is RECOMMENDED that crawlers and consumers of publiccode.yml verify this
+information out-of-band, to ensure that the declared `organisationUri` actually
+corresponds to the organisation in control of the repository.
+The specific verification method depends on the implementation and policies of the
+platform consuming the file.
+
+Key ``organisation/name``
+'''''''''''''''''''''''''
+
+-  Type: string
+-  Presence: optional
+-  Example: ``"My organisation"``
+
+The canonical name of the organisation publishing the software.
+
+It MUST correspond to the same entity identified by ``organisation/uri`` and is
+intended to provide a human-readable label for that URI.
+It SHOULD be the canonical, widely recognized form of the name (such as the
+registered legal or institutional name).
+
+Section ``intendedAudience``
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Key ``intendedAudience/countries``
+''''''''''''''''''''''''''''''''''
+
+-  Type: array of strings
+-  Presence: optional
+
+This key explicitly includes certain countries in the intended audience,
+i.e. the software explicitly claims compliance with specific processes,
+technologies or laws. All countries are specified using lowercase (*deprecated*)
+or uppercase ISO 3166-1 alpha-2 two-letter country codes.
+
+Key ``intendedAudience/unsupportedCountries`` (*deprecated*)
+''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
+
+-  Type: array of strings
+-  Presence: optional
+
+This key explicitly marks countries as NOT supported. This might be the
+case if there is a conflict between how software is working and a
+specific law, process or technology. All countries are specified using
+lowercase (*deprecated*) or uppercase ISO 3166-1 alpha-2 two-letter country codes.
+
+This key is deprecated, use ``intendedAudience/countries`` to list the
+countries the software explicitly targets instead.
+
+Key ``intendedAudience/scope``
+''''''''''''''''''''''''''''''
+
+-  Type: array of strings
+-  Presence: optional
+-  Acceptable values: see :ref:`scope-list` 
+
+This key contains a list of tags related to the field of application of
+the software. 
+
+Section ``description``
+~~~~~~~~~~~~~~~~~~~~~~~
+
+This section contains a general description of the software. Parsers can
+use this section for instance to create a web page describing the
+software.
+
+**Note:** since all the strings contained in this section are
+user-visible and written in a specific language, you **must** specify
+the language you are editing the text in (using the IETF 
+`BCP 47 <https://www.rfc-editor.org/info/bcp47/>`__ specifications) by
+creating a sub-section with that name. The primary language subtag cannot be
+omitted, as mandated by the BCP 47.  
+
+An example for English:
+
+.. code:: yaml 
+
+   description:
+     en:
+       shortDescription: ...
+       longDescription: ...
+
+In the following part of the document, all keys are assumed to be in a
+sub-section with the name of the language (we will note this with
+``[lang]``).
+
+**Note:** it is mandatory to have *at least* one language in this
+section. All other languages are optional.
+
+Key ``description/[lang]/localisedName``
+''''''''''''''''''''''''''''''''''''''''
+
+-  Type: string
+-  Presence: optional
+-  Example: ``"Medusa"``
+
+This key is an opportunity to localise the name in a specific language.
+It contains the (short) public name of the product. It should be the
+name most people usually refer to the software. In case the software has
+both an internal “code” name and a commercial name, use the commercial
+name.
+
+Key ``description/[lang]/genericName`` (*deprecated*)
+'''''''''''''''''''''''''''''''''''''''''''''''''''''
+
+-  Type: string (max 35 chars)
+-  Presence: optional
+-  Example: ``"Text Editor"``
+
+This key is the “Generic name”, which refers to the specific category to
+which the software belongs. You can usually find the generic name in the
+presentation of the software, when you write: “Software xxx is a yyy”.
+Notable examples include “Text Editor”, “Word Processor”, “Web Browser”,
+“Chat” and so on… The generic name can be up to 35 characters long.
+
+Key ``description/[lang]/shortDescription``
+'''''''''''''''''''''''''''''''''''''''''''
+
+-  Type: string (max 150 chars)
+-  Presence: mandatory
+-  Example: ``"Advanced booking system for hospitals"``
+
+This key contains a short description of the software. It should be a
+single line containing a single sentence. Maximum 150 characters are
+allowed.
+
+Key ``description/[lang]/longDescription``
+''''''''''''''''''''''''''''''''''''''''''
+
+-  Type: Markdown string (min 150 chars, max 10000 chars)
+-  Presence: mandatory (for at least one language)
+
+This key contains a longer description of the software, between 150 and
+10000 chars. It is meant to provide an overview of the capabilities of
+the software for a potential user. The audience for this text should be
+that of users of the software, not developers. You can think of this
+text as the description of the software that would be in its website (if
+the software had one).
+
+The value of this key is Markdown, as defined by
+`CommonMark <https://commonmark.org/>`__. Keep the formatting basic:
+``*italic*``, ``**bold**``, bullet points and ``[links](#)``, since
+consumers MAY render only this subset.
+
+Key ``description/[lang]/documentation``
+''''''''''''''''''''''''''''''''''''''''
+
+-  Type: URL
+-  Presence: optional
+
+This key contains a reference to the user-level (not developer-level)
+documentation of the software. The value must be a URL to a hosted
+version of the documentation.
+
+It is suggested that the URL points to a hosted version of the
+documentation that is immediately readable through a common web browser
+in both desktop and mobile format. The documentation should be rendered
+in HTML and browsable like a website (with a navigation index, a search
+bar, etc.).
+
+If the documentation is instead available only as a document, put a
+direct view/download link as URL in this key. You should commit the
+document as part of the source code repository, and then link to it
+using the code hosting source browser URL (e.g.: GitHub URL to the file).
+Prefer using open formats like PDF or ODT for maximum interoperability.
+
+Whichever the format for the documentation, remember to make its source
+files available under an open license, possibly by committing them as
+part of the repository itself.
+
+Key ``description/[lang]/apiDocumentation``
+'''''''''''''''''''''''''''''''''''''''''''
+
+-  Type: URL
+-  Presence: optional
+
+This key contains a reference to the API documentation of the software.
+The value must be a URL to a hosted version of the documentation.
+
+It is suggested that the URL points to a hosted version of the
+documentation that is immediately readable through a common web browser.
+The documentation should be rendered in HTML and browsable like a
+website (with a navigation index, a search bar, etc.), and if there is a
+reference or test deployment, possibly offer an interactive interface
+(e.g. Swagger).
+
+If the documentation is instead available only as a document, put a
+direct view/download link as URL in this key. You should commit the
+document as part of the source code repository, and then link to it
+using the code hosting source browser URL (e.g.: GitHub URL to the file).
+Prefer using open formats like PDF or ODT for maximum interoperability.
+
+Whichever the format for the documentation, remember to make its source
+files available under an open license, possibly by committing them as
+part of the repository itself.
+
+Key ``description/[lang]/features``
+'''''''''''''''''''''''''''''''''''
+
+-  Type: array of strings
+-  Presence: optional
+
+This key contains a list of software features, describing what
+capabilities the software allows to do. The audience for this text
+should be that of public decision makers who will be commissioning the
+software. The features should thus not target developers; instead of
+listing technical features referring to implementation details, prefer
+listing user-visible functionalities of the software.
+
+The suggested number of features to list is between 5 and 20, depending
+on the software size and complexity. There is no need for
+exhaustiveness, as users can always read the documentation for
+additional information.
+
+Key ``description/[lang]/screenshots``
+''''''''''''''''''''''''''''''''''''''
+
+-  Type: array of strings (paths)
+-  Presence: optional
+-  Formats: PNG, JPEG, WebP, AVIF
+-  Example: ``"data/screenshots/configuration.png"``
+
+This key contains one or multiple paths to files showing screenshots of
+the software. They are meant to give a quick idea on how the software
+looks like and how it works.
+The key value can be the relative path to the file starting from the root of
+the repository, or it can be an absolute URL pointing to the screenshot in raw
+version. In both cases, the file must reside inside the same repository where
+the ``publiccode.yml`` file is stored.
+
+Screenshots can be of any shape and size; the suggested formats are:
+
+-  Desktop: 1280x800 @1x
+-  Tablet: 1024x768 @2x
+-  Mobile: 375x667 @2x
+
+Key ``description/[lang]/videos`` (*deprecated*)
+''''''''''''''''''''''''''''''''''''''''''''''''
+
+-  Type: array of strings (URLs)
+-  Presence: optional
+-  Example: ``"https://youtube.com/xxxxxxxx"``
+
+This key contains one or multiple URLs of videos showing how the
+software works. Like screenshots, videos should be used to give a quick
+overview on how the software looks like and how it works. Videos must be
+hosted on a video sharing website that supports the
+`oEmbed <https://oembed.com>`__ standard; popular options are YouTube
+and Vimeo.
+
+This key is deprecated, link videos from the documentation or the
+website of the software instead.
+
+Key ``description/[lang]/awards``
+'''''''''''''''''''''''''''''''''
+
+-  Type: array of strings
+-  Presence: optional
+
+A list of awards won by the software.
+
+Section ``legal``
+~~~~~~~~~~~~~~~~~
+
+Key ``legal/license``
+'''''''''''''''''''''
+
+-  Type: string
+-  Presence: mandatory
+-  Example: ``"AGPL-3.0-or-later"``, ``"EUPL-1.2 OR AGPL-3.0-or-later"``
+
+This string describes the license under which the software is
+distributed. The string must contain a valid SPDX expression, referring
+to one or multiple open-source licenses. Please refer to the `SPDX
+documentation <https://spdx.org/licenses/>`__ for further information.
+
+Key ``legal/mainCopyrightOwner``
+''''''''''''''''''''''''''''''''
+
+-  Type: string
+-  Presence: optional
+-  Example: ``"City of Amsterdam"``
+
+This string describes the entity that owns the copyright on “most” of
+the code in the repository. Normally, this is the line that is reported
+with the copyright symbol at the top of most files in the repo.
+
+It is possible to list multiple owners if required so, using an English
+sentence. It is also possible to informally refer to a community of
+group of people like “Linus Torvalds and all Linux contributors”.
+
+In case it is not possible to name a main copyright owner, it is
+possible to omit this key; in those cases, if the repo has a authors
+file, you can point to it through ``legal/authorsFile``.
+
+Key ``legal/repoOwner`` (*deprecated*)
+''''''''''''''''''''''''''''''''''''''
+
+-  Type: string
+-  Presence: optional
+-  Example: ``"City of Amsterdam"``
+
+This string describes the entity that owns this repository; this might
+or might not be the same entity who owns the copyright on the code
+itself. For instance, in case of a fork of the original software, the
+``repoOwner`` is probably different from the ``mainCopyrightOwner``.
+
+This key is deprecated, use ``organisation/name`` instead.
+
+Key ``legal/authorsFile`` (*deprecated*)
+''''''''''''''''''''''''''''''''''''''''
+
+-  Type: string (path to file)
+-  Presence: optional
+-  Example: ``"doc/AUTHORS.txt"``
+
+Some open-source software adopt a convention of identify the copyright
+holders through a file that lists all the entities that own the
+copyright. This is common in projects strongly backed by a community
+where there are many external contributors and no clear single/main
+copyright owner. In such cases, this key can be used to refer to the
+authors file, using a path relative to the root of the repository.
+
+Section ``maintenance``
+~~~~~~~~~~~~~~~~~~~~~~~
+
+This section provides information on the maintenance status of the
+software, useful to evaluate whether the software is actively developed
+or not.
+
+Key ``maintenance/type``
+''''''''''''''''''''''''
+
+-  Type: enumerate
+-  Presence: mandatory
+-  Values: ``"internal"``, ``"contract"``, ``"community"``, ``"none"``
+
+This key describes how the software is currently maintained.
+
+-  ``internal`` - means that the software is internally maintained by the
+   repository owner;
+-  ``contract`` - means that there is a commercial
+   contract that binds an entity to the maintenance of the software;
+-  ``community`` - means that the software is currently maintained by one
+   or more people that donate their time to the project;
+-  ``none`` - means that the software is not actively maintained.
+
+Key ``maintenance/contractors``
+'''''''''''''''''''''''''''''''
+
+-  Type: array of Contractor (see below)
+-  Presence: mandatory if ``maintenance/type`` **is** ``contract``; must not be present otherwise
+
+This key describes the entity or entities, if any, that are currently
+contracted for maintaining the software. They can be companies,
+organisations, or other collective names.
+
+Key ``maintenance/contacts``
+''''''''''''''''''''''''''''
+
+-  Type: List of Contacts (see below)
+-  Presence: mandatory if ``maintenance/type`` **is** ``internal`` or ``community``; optional otherwise
+
+One or more contacts maintaining this software.
+
+This key describes the technical people currently responsible for
+maintaining the software. All contacts need to be a physical person, not
+a company or an organisation. If somebody is acting as a representative
+of an institution, it must be listed within the ``affiliation`` of the
+contact.
+
+In case of a commercial agreement (or a chain of such agreements),
+specify the final entities actually contracted to deliver the
+maintenance. Do not specify the software owner unless it is technically
+involved with the maintenance of the product as well.
+
+Section ``localisation``
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+This section provides an overview of the localization features of the
+software.
+
+Key ``localisation/localisationReady``
+''''''''''''''''''''''''''''''''''''''
+
+-  Type: boolean
+-  Presence: mandatory
+
+If ``true``, the software has infrastructure in place or is otherwise
+designed to be multilingual. It does not need to be available in more
+than one language.
+
+Key ``localisation/availableLanguages``
+'''''''''''''''''''''''''''''''''''''''
+
+-  Type: list of IETF BCP 47 language tags
+-  Presence: mandatory
+-  Example: ``"it"``, ``"en"``, ``"sl-IT-nedis"``
+
+If present, this is the list of languages in which the software is
+available. Of course, this list will contain at least one language.
+The primary language subtag cannot be omitted, as mandated by the 
+`BCP 47 <https://www.rfc-editor.org/info/bcp47/>`__.
+
+Section ``dependsOn``
+~~~~~~~~~~~~~~~~~~~~~
+
+This section provides an overview on the system-level dependencies
+required to install and use this software.
+
+**NOTE:** do not list dependencies at the source code level (e.g.:
+software libraries being used), and focus only on runtime and/or
+system-level dependencies that must be installed and maintained
+separately. For instance, a database is a good example of such
+dependencies.
+
+Key ``dependsOn/open`` (*deprecated*)
+'''''''''''''''''''''''''''''''''''''
+
+-  Type: array of ``dependency`` (see below)
+-  Presence: optional
+
+This key contains a list of runtime dependencies that are distributed
+under an open-source license.
+
+This key is deprecated. Open source runtime dependencies are already
+declared in the SBOM or in the package manager manifests, and what
+needs to be installed belongs in the documentation and in the
+deployment scripts.
+
+Key ``dependsOn/proprietary``
+'''''''''''''''''''''''''''''
+
+-  Type: array of ``dependency`` (see below)
+-  Presence: optional
+
+This key contains a list of runtime dependencies that are distributed
+under a proprietary license.
+
+Key ``dependsOn/hardware``
+''''''''''''''''''''''''''
+
+-  Type: array of ``dependency`` (see below)
+-  Presence: optional
+
+This key contains a list of hardware dependencies that must be owned to
+use the software.
+
+Special data formats
+--------------------
+
+Dependency
+~~~~~~~~~~
+
+A ``dependency`` is a complex object. The properties are the following:
+
+-  ``name`` - **mandatory** - The name of the dependency (e.g. MySQL,
+   NFC Reader)
+-  ``versionMin`` - the first compatible version
+-  ``versionMax`` - the latest compatible version
+-  ``version`` - the only major version for which the software is
+   compatible. It assumes compatibility with all patches and bugfixes
+   later applied to this version.
+-  ``optional`` - whether the dependency is optional or mandatory
+
+Complex versioning
+~~~~~~~~~~~~~~~~~~
+
+It is of course possible to use the various keys to specify a complex
+compatibility matrix.
+
+*Ex. 1*
+
+.. code:: yaml
+
+   - name: PostgreSQL
+     version: "3.2"
+     optional: true
+
+This snippet marks an optional dependency on PostgreSQL exactly version
+3.2.
+
+*Ex. 2*
+
+.. code:: yaml
+
+   - name: MySQL
+     versionMin: "1.1"
+     versionMax: "1.3"
+
+This snippet marks a mandatory dependency on MySQL, allowing any version
+between 1.1 and 1.3.
+
+Contact
+~~~~~~~
+
+A Contact is an object with the following properties:
+
+-  ``name`` - **mandatory** - This key contains the full name of one of
+   the technical contacts. It must be a real person; do NOT populate
+   this key with generic contact information, company departments,
+   associations, etc.
+-  ``email`` - This key contains the e-mail address of the technical
+   contact. It must be an email address where the technical contact
+   can be directly reached; do NOT populate this key with mailing-lists
+   or generic contact points like “info@acme.inc”.
+-  ``phone`` - phone number. It SHOULD include the international
+   prefix, following the `E.164 <https://www.itu.int/rec/T-REC-E.164/en>`_
+   format (e.g. ``+3923113215112``). This has to be a string.
+-  ``affiliation`` - This key contains an explicit affiliation
+   information for the technical contact. In case of multiple
+   maintainers, this can be used to create a relation between each
+   technical contact and each maintainer entity. It can contain for
+   instance a company name, an association name, etc.
+
+Organisation
+~~~~~~~~~~~~
+
+An organisation is a structure (association, company, public
+authority, etc.) that can fund software development. An organisation
+has the following properties:
+
+-  ``name`` - **mandatory** - The name of the organisation, whether
+    it’s an association, a company, a public sector organisation, or
+    a physical person.
+-  ``uri`` - The URI identifying the organisation.
+
+Contractor
+~~~~~~~~~~
+
+A Contractor is an object with the following properties:
+
+-  ``name`` - **mandatory** - The name of the contractor, whether it’s a
+   company or a physical person.
+-  ``until`` - **mandatory** - This is a date (YYYY-MM-DD). This key
+   must contain the date at which the maintenance is going to end. In
+   case of community maintenance, the value should not be more than 2
+   years in the future, and thus will need to be regularly updated as
+   the community continues working on the project.
+-  ``email`` - This key contains the e-mail address of the technical
+   contact. It must be an email address where the technical contact
+   can be directly reached; do NOT populate this key with mailing-lists
+   or generic contact points like “info@acme.inc”.
+-  ``website`` - This key points to the maintainer website. It can
+   either point to the main institutional website, or to a more
+   project-specific page or website.
+
+Dates
+~~~~~
+
+All dates in ``publiccode.yml`` must follow the format “YYYY-MM-DD”,
+which is one of the ISO8601 allowed formats. This is the only allowed
+format though, so not the full ISO8601 is allowed for the date keys.
+
+Encoding
+~~~~~~~~
+`publiccode.yml` **MUST** be a UTF-8 encoded and **SHOULD** be a YAML 1.2 document,
+using YAML 1.1 is *deprecated*.
diff --git a/skills/generate-publiccode-yml/reference/scope-list.rst b/skills/generate-publiccode-yml/reference/scope-list.rst
new file mode 100644
index 00000000..6e7a4227
--- /dev/null
+++ b/skills/generate-publiccode-yml/reference/scope-list.rst
@@ -0,0 +1,36 @@
+.. _scope-list:
+
+Scope list
+==========
+
+Here follows a controlled vocabulary of useful tags for categorizing the
+software.
+
+==========
+Valid Tags
+==========
+
+- agriculture
+- culture
+- defence
+- education
+- emergency-services
+- employment
+- energy
+- environment
+- finance-and-economic-development
+- foreign-affairs
+- government (*deprecated*)
+- healthcare
+- infrastructures
+- justice
+- local-authorities
+- manufacturing
+- research
+- science-and-technology
+- security
+- society
+- sport
+- tourism
+- transportation
+- welfare
diff --git a/skills/generate-publiccode-yml/reference/validation.md b/skills/generate-publiccode-yml/reference/validation.md
new file mode 100644
index 00000000..68c6937f
--- /dev/null
+++ b/skills/generate-publiccode-yml/reference/validation.md
@@ -0,0 +1,68 @@
+# Validating a publiccode.yml
+
+The reference implementation is
+[libpubliccode](https://github.com/publiccodeyml/libpubliccode). Any
+validation path below uses it (or its schema) under the hood. Prefer the
+path that matches the user's environment.
+
+## GitHub Action (CI)
+
+Add a workflow to the user's repository:
+
+```yaml
+name: Validate publiccode.yml
+on: [push, pull_request]
+jobs:
+  validate:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: publiccodeyml/publiccode-parser-action@main
+```
+
+## GitLab CI
+
+Use the component documented at
+[publiccodeyml/publiccode-parser-gitlab-ci](https://github.com/publiccodeyml/publiccode-parser-gitlab-ci).
+
+## Locally, with don-checker (recommended)
+
+No toolchain needed — just Node for npx:
+
+```bash
+npx @developer-overheid-nl/don-checker@1.4.0 validate --standard publiccode --input ./publiccode.yml
+```
+
+don-checker detects the `publiccode.yml` format by **filename**, so validate
+a file actually named `publiccode.yml`. It picks the newest ruleset it
+ships (pin with `--version`).
+
+## Cross-check, with the publiccode-parser CLI
+
+
+```bash
+go install github.com/publiccodeyml/libpubliccode/v5/publiccode-parser@latest
+
+publiccode-parser --no-network path/to/publiccode.yml
+```
+
+Flags come **before** the file argument. The validator also checks whether
+URLs exist and locally referenced files (logo, screenshots) are present;
+use `--no-network` when offline or when the repository is not yet public,
+and `--no-external-checks` to skip local file checks as well. Precompiled
+binaries are on the [releases page](https://github.com/publiccodeyml/libpubliccode/releases/latest)
+— no Go toolchain needed.
+
+---
+
+## Known quirks
+
+- libpubliccode v5.5.1 reports `features must contain more than 0 items`
+  even when `description.[lang].features` is **absent**, although the
+  Standard marks the key optional. Work around it by listing a few real
+  features (5 or fewer meaningful ones is plenty) — this also improves how
+  the software shows up in catalogs.
+
+Errors must be fixed before considering the task done. Report warnings to
+the user instead of silently ignoring them; most warnings hint at drifted
+or deprecated keys.
diff --git a/skills/generate-publiccode-yml/scripts/sync-reference.sh b/skills/generate-publiccode-yml/scripts/sync-reference.sh
new file mode 100755
index 00000000..b0e152b5
--- /dev/null
+++ b/skills/generate-publiccode-yml/scripts/sync-reference.sh
@@ -0,0 +1,18 @@
+#!/usr/bin/env bash
+# Sync the skill's reference material from the Standard's source of truth.
+# Run after any change to docs/standard/ (or after bumping to a new
+# release tag) so the skill always documents the released Standard.
+set -euo pipefail
+
+REPO_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/../../.." && pwd)"
+SRC="$REPO_ROOT/docs/standard"
+DST="$REPO_ROOT/skills/publiccode/reference"
+
+for f in schema.core.rst categories-list.rst scope-list.rst aliases-list.rst; do
+  cp "$SRC/$f" "$DST/$f"
+done
+
+cp "$SRC/example/publiccode.minimal.yml" "$DST/examples/publiccode.minimal.yml"
+cp "$SRC/example/publiccode.yml"         "$DST/examples/publiccode.yml"
+
+echo "Reference material synced from docs/standard (revision $(git -C "$REPO_ROOT" rev-parse --short HEAD))."