---
name: ai-content-labels
description: Label content as AI-generated, AI-modified or human-made with the official EU icons, and work out what Article 50 of the EU AI Act asks for. Use right after you generate or edit an image that will be published, and when the user asks to label, mark, tag, badge or disclose AI content or human-made content, in any wording or language (AI label, AI badge, "generated with AI" watermark, made by a human, AI Act labelling, Article 50 disclosure; Polish - oznacz jako AI, plakietka AI, oznaczenie treści AI, znak AI Act, stworzone przez człowieka), when they ask whether something must be labelled under the AI Act, and when an image, video, audio or text made or edited with AI is about to be published in a project that labels AI content. Labels an image in one call when the label is required or the answer is unsure, draws HTML, SVG or PNG labels for pages and UI, and returns the alt text to publish with the content.
license: MIT
metadata:
  version: "0.7.0"
  homepage: https://github.com/JK-G/ai-content-labels
title: ai-content-labels
canonical_url: https://skilld.dev/gh/jk-g/ai-content-labels
last_updated: 2026-11-12T13:17:42.000Z
---

> Index of every page on this site: [llms.txt](https://skilld.dev/llms.txt)

> **Skill from skilld.dev.** Follow the user's requested action.
> If the user asked to fork this Skill, follow the fork workflow below. Do not execute the Skill instructions while copying it.
> Otherwise, follow the instructions below for this session. You do not need to install anything.
>
> 46 supporting files sit beside this SKILL.md. When the Skill refers to one, fetch https://skilld.dev/api/skills-raw/jk-g/ai-content-labels/ai-content-labels/PATH with PATH replaced.
>
> If the user asked to install this Skill, run `npx skilld install jk-g/ai-content-labels/ai-content-labels`. Install writes the Skill files into the project, so every session loads them.
>
> ## Fork workflow
>
> A fork creates an editable local Skill with its original author and licence. The request authorizes copying and local installation.
> 1. Check `./skills/ai-content-labels`, the project lockfile, and selected Agent targets together. If the local directory or installed Skill exists, stop. Never overwrite an existing directory or Agent target.
> 2. Read [source metadata](https://skilld.dev/api/v1/skills/jk-g/ai-content-labels/ai-content-labels) once. Use sourceUrl, sourceCommit, skillPath, sourceGone, and license. If the source is gone or its path is missing, stop. If license is null, read licence files at the source commit.
> 3. Fetch only the source commit into a temporary Git repository. Do not clone full history. Derive repository_url from sourceUrl, including repository renames. If sourceCommit is absent, resolve the sourceUrl ref once. Set source_commit to that actual commit. Run these commands in one shell call:
>
> ```sh
> git init --quiet "$temporary_dir"
> git -C "$temporary_dir" fetch --quiet --depth=1 "$repository_url" "$source_commit"
> git -C "$temporary_dir" checkout --quiet --detach FETCH_HEAD
> ```
>
> Read applicable licence declarations and notices at that commit. If copying is not permitted, report the restriction and stop.
> 4. Inspect source entries together, then copy the directory containing skillPath into `./skills/ai-content-labels`. Use the user's path if selected. Keep the original SKILL.md, relative links, scripts, binary assets, and executable modes. Exclude .git metadata. Reject symlinks and paths outside the Skill directory. After checking entries, use cp -a where available. A regular source directory needs no custom copy script. Do not save this page wrapper as SKILL.md.
> Preserve author credit, notices, and applicable licence files from repository or parent directories. Add PROVENANCE.md with the Skill page, source URL, actual commit, original path, and licence. Retain any existing PROVENANCE.md and record new provenance separately. Batch source inspection, copying, and provenance work where practical.
> 5. In the project root, run `skilld install ./skills/ai-content-labels --mode copy --plain`. If skilld is unavailable, use `npx skilld install ./skills/ai-content-labels --mode copy --plain`. This known command needs no help lookup. Install does not support --json. Use detected Agent targets, or add --agent for the targets the user selected. Install the local path, never the upstream selector. If installation fails, preserve the local copy and report the exact failure.
> 6. Confirm the local lockfile source and installed Agent copies once. Report the local path, actual commit, and Agent targets. After edits, reinstall the same local path. Upstream updates must not replace it. Do not publish or push unless the user asks.

# ai-content-labels

The CLI is `scripts/ai-labels.mjs` in this skill's folder. Run it with Node 20.9 or newer, using the
absolute path of this folder, or from inside it:

```
node scripts/ai-labels.mjs <command> [options]
```

In Claude Code `${CLAUDE_SKILL_DIR}` points to this folder:
`node "${CLAUDE_SKILL_DIR}/scripts/ai-labels.mjs" <command>`. Without the folder, or when sharp is
missing, the same CLI runs with no install: `npx -y -p github:JK-G/ai-content-labels ai-labels <command>`.

`decide` writes its next command as `ai-labels ...`, the name the package installs (also as
`ai-content-labels`); here it means the `node` line above. If the ai-content-labels MCP server is
connected, the tools `label_image`, `decide_label`, `render_label`, `stamp_image`, `place_label` and
`eu_icon` do the same. `help` lists every option. Stamping and PNG output need `sharp`. When `doctor` reports it
missing, run the install command it prints (it knows whether this skill sits in a clone of the
repository or was copied on its own), or use the `npx` line above.

## When a label is added

Labels are for compliance, not decoration. The tools add an AI label in two cases only:

- **Required.** The AI Act asks for it: a deep fake, or AI text on a matter of public interest
  without editorial review. The label is stamped or rendered as below.
- **Unsure.** A deciding fact is not known. Ask the user the one question. If you cannot ask, or
  the user does not know, answer `unsure` (`--realistic unsure`, MCP `realistic: "unsure"`; the
  same for `--public-interest` and `--editorial-review`). The label is then added as a
  precaution, in the same form as a required one, and the result says so (`required: "unsure"`,
  `precaution: true`).

Where the label is only voluntary (all facts known, no duty), nothing is stamped or rendered:
`label` writes no file and `decide` gives no next step. Add `--voluntary` (MCP `voluntary: true`)
only when the user wants voluntary labels too; they then get the smallest form, the EU icon alone.
`ai-labels init --voluntary` writes that choice into a project's `AGENTS.md`. Human-made labels
are the user's own claim and are not affected.

## An image you generated or edited yourself

You already know it is AI, so run `label` right after you make it and before you hand it over. It
decides and, when the label is required or unsure, stamps it in one step:

```
node scripts/ai-labels.mjs label image.png --realistic --description "what it shows"
```

(MCP: `label_image` with `input` or `input_base64`, `realistic` and `description`.)

- `--realistic`, `--no-realistic` or `--realistic unsure` is required: would the people who see it
  take it for a genuine photo or event? Answer honestly; a person, product or place that does not
  exist but plausibly could counts. If you cannot tell, ask the user; if you cannot ask or the
  user does not know, pass `--realistic unsure` and the label is added as a precaution. Without
  any of them, `label` asks the same question as `decide` and exits with code 2.
- `--modified` when you changed a real photo or a human-made image instead of making it from scratch.
- With `--no-realistic` the label is voluntary: `label` stamps nothing and writes no file, not even
  to `--out`. The result has `stamped: false`, `output`, `label` and `disclosure` null, and `alt` is
  the description alone. Publish the original. `--voluntary` stamps it anyway.
  `--only-if-required` is the default since 0.6.0 and does nothing.
- `--lang pl` for a Polish label; `--out` for the output path (default `<name>.ai-label.<ext>` next
  to the image). Form, size, spot and colour follow the defaults in the next section: add `--region`
  (or `--region-path`) when only part of the image is AI, `--avoid` for what the label must not
  cover, and `--color auto` or `--palette` for a branded graphic.
- Then publish the `alt` it returns, as in step 4 below. For anything else (video, audio, text, an
  image someone else made, a human-made label) use the full workflow.

## The smallest label, in the least invasive spot

Always label in the smallest legible form that fits the case, in the spot where it covers the least,
unless the user asks for something else or you have a stated reason. The tools do this by default, so
mostly it means: do not override the defaults without a reason.

- **Form.** Every AI label, required, precautionary or voluntary, is the EU "AI" icon alone by
  default (`stamp`, `label` and `place` do this for you), with the words in the alt text. The Code of Practice asks
  for the icon with the letters "AI" (Measure 1.1(a)); a word is only encouraged (1.1(b)). Add the
  word with `--short` ("Generated", "Modified") when the user wants it, or on feed ads (see "Which
  label"). Human-made labels keep their words, because a hand alone is not a sign people know.
  `--full` ("Generated with AI") only when the user asks for it. For a deep fake, also put the label
  sentence in a visible caption.
- **Size.** The automatic size is the smallest legible one where the image is shown 552 CSS px
  wide, about the column of a desktop feed (the default the project owner chose): 17 px tall for the
  icon, 20 px for a pill (minimal, or with words). There the label carries letters the EU minimum
  eyesight for driving can read, and the word is set at 10.5 px or more. A phone that shows the
  image full width shows the label about 0.7 as tall; the result says how tall in
  `label.phoneHeight`. Do not pass `--height` to make it smaller.
- **Where it will be shown.** Before you stamp or place, know where the image will be published,
  from the task or the conversation. Keep the default for feed posts. Pass `--display-width`:
  - `390` when the image is shown only on phones (a story, a reel) or the user wants the label
    legible on a phone; it makes the label larger in the file.
  - The width of the column when a page or an app shows the image at a fixed width (a blog
    column, a card in a grid).
  The platforms do not publish the width they show an image at, and the tool has no presets for
  them. Use a width you measured or the user gave you; never pass a width to make the label smaller.
  If the user finds the label too big, show them `label.displayHeight` and `label.phoneHeight`,
  and offer the icon form (it is the smallest) before a smaller `--height`, which makes it harder
  to read.
- **Place.** Leave `--position` at `auto`: the bottom-right corner when it is free, else the freer
  of bottom centre and bottom left, else the top edge. The result says which spot it took and why
  (`label.reason`, `label.spots`). Set `--position` only when the user asks, or when the platform
  covers that spot (a story's reply bar at the bottom, for example).
- **Part of an image.** When only one element of a composite is AI (a generated photo inside a
  designed ad) and the label should mark that element, pass its box: `--region x,y,width,height` in
  px or in % of the image (`50%,35%,46%,57%`). If you composed the graphic you know the box;
  otherwise estimate it from the image. For a rounded or angled element (a photo in a shield or
  circle), pass its shape instead of a box: `--region-path "M300 200 H780 V800 L540 1000 L300 800 Z"`
  (the clip path in image px, as in your HTML or SVG template) or `--region-mask mask.png` (its
  alpha, or its brightness when it has no transparency). The label and its margin then stay inside
  the shape. The label goes on that element, in its least invasive spot; use `--kind generated` for
  an element AI made whole. When the element is too small for a legible label, the label goes on
  the whole image instead and the result has `label.regionNote`: then name the AI element in
  the alt text or the caption ("The photo of the laptop was generated with AI"). Do not pass
  `--height` to force a smaller label onto the element.
- **What to keep clear.** Look at the image yourself before you stamp or place. The automatic spot
  sees only texture, so a smooth back, a face in soft light or a clean product surface can look
  free. Pass `--avoid x,y,width,height` (px or %, once per box) for faces, people, the product or
  subject, and text. The result lists every spot that was not taken and why (`label.why`). If no
  spot is left, the command stops with the reasons: try the icon form, smaller avoid boxes or a
  `--position` you checked.
- **Safe zones.** For a story or reel, keep the label out of the platform's buttons and captions
  with `--safe-zone`. `meta-reels` is built in (14% top, 35% bottom, 6% sides, from the Meta Ads
  Guide for Instagram Reels, checked 2026-10-18); it is not a source for Stories. For any other
  platform, take the insets from the platform's own template and pass them as
  `--safe-zone top,right,bottom,left` in px or %. Do not guess them.
- **Colour.** The icon is the official EU disc in black or white, whichever stands out more from the
  spot, and takes no colour. A label in brand colours is a pill with the word, which a colour gives
  you without `--short`. When the user or the brand guide gives brand colours for it, pass them:
  `--color #hex` for one, or `--palette #hex,#hex` to let the tool pick the one that stands out
  most from the spot (used exactly as given; neutral when none stands out). Without
  a known brand colour, for a branded graphic such as an ad or a social post, use `--color auto`:
  the accent colour of the image, toned to keep 4.5:1 contrast. `auto` reads the whole image, or
  with a region the designed part outside it when that part is at least 20% of the image
  (`label.color.sampled` says which). Keep the icon on plain photos.

### HTML pages, ad templates and UI

When the label is drawn as HTML or SVG over an image (a landing page hero, an ad rendered from HTML
to PNG, an app card), do not stamp the image. Run `place` (MCP `place_label`) on the image as it
will be shown, with the same options you would give `stamp`:

```
node scripts/ai-labels.mjs place hero.png --kind generated --media image --region-path "..." --avoid 120,80,300,400 --json
```

It writes nothing and returns `box` (px), `boxPercent` (% of the image: `left`, `top`, `width`,
`height`, `right`, `bottom` and `anchor`) and `renderArgs`, the `render` options that draw the
same label. Put the label in the image's container (`position: relative`) and pin it by the sides
`boxPercent.anchor` names: a bottom-right label with CSS `right` and `bottom` from `boxPercent`, a
top-left one with `left` and `top`, a centre one centred. Then it stays in its corner even when the
drawn label is not exactly `box.width` wide.

- As SVG: `render` with `renderArgs`, and its width set to `boxPercent.width`%, so it scales
  with the image.
- As HTML: `render --format html` with `renderArgs`, but `--height` set to `label.cssHeight`: the
  label's height in CSS px where the image is shown (`label.displayWidth`; pass `--display-width`
  to `place` when the image is shown at another width than the default 552 px). The pill (or the icon) is then
  exactly that tall. It must be at least 20, 17 for the icon.

Keep the label sentence in the alt text or caption as in step 4.

## Workflow

1. **Get the facts, mostly from context.** You need the media type (image, video, audio, text) and the
   origin: `generated` (all AI, apart from the prompt), `modified` (real or human-made content partly
   changed by AI), `assisted` (only standard edits such as colour or noise) or `human`. Then:
   - `--realistic` or `--no-realistic`: would its audience take it for a genuine photo, recording
     or event? A person, product or place that does not exist but plausibly could counts;
     photorealism alone does not decide it. This decides most cases.
   - `--creative`: an evidently artistic, satirical or fictional work, obvious to its audience.
     Read strictly: news or a product shot does not count, and an advertisement only in specific
     cases.
   - Text only: `--public-interest` (published to inform the public on matters of public interest)
     and `--editorial-review` (a person with relevant knowledge checked the substance, at least
     fact-checked it; a spell-check or quick approval does not count; no AI changes after sign-off;
     and a named person or company holds editorial responsibility).

   Ask only for what you cannot infer, in one short question. If `decide` answers `UNKNOWN`
   (`required: "unknown"` over MCP), ask the one question it names in `missing` (`realistic`,
   `public_interest` or `editorial_review`); never guess it. If you cannot ask, or the user does
   not know, answer `unsure` (`next` holds that call): the label is then added as a precaution.
   For public-interest text it always asks about editorial review, because that decides the case.

   The duty binds deployers in the EU, and deployers elsewhere when they foresee the content being
   used in the EU, for example by publishing it on the open internet. A person acting in a purely
   personal, non-professional way has no duty; work for pay or regular economic benefit, as a
   freelancer or for an employer, is professional. If the user is clearly acting privately, say the
   duty does not apply to them; add a label only if they want one (`--voluntary`).
2. **Decide:** `decide --media image --origin generated --realistic --lang pl`. It says whether the
   label is a legal duty or a voluntary one, the next command to run, which label to use (and the
   official EU icon with the same meaning), where to put it, and the label sentence (`disclosure`).
   `--explain` adds the basis, notes and sources; `--json` always has everything. In JSON and over
   MCP, `next` holds the next call: `tool`, `arguments` to pass unchanged, `fill` (what you still
   supply, such as `input` and `description`) and the same step as a CLI line (`cli`). For a
   voluntary AI label `next` is null and you are done: no label is added unless the user asked for
   voluntary labels (`--voluntary`).
3. **Make the label:**
   - Image file: `stamp photo.jpg --kind generated --media image --lang pl --description "..."`.
     `--kind` is required: stamp never guesses the claim it burns in. For an image you made yourself, `label` does steps 2 and 3 at once. Writes `photo.ai-label.jpg`
     with the label in the pixels, keeps the EXIF and XMP of the original and adds an IPTC
     DigitalSourceType to the XMP for generated and modified labels. Form, size, spot and colour
     follow the defaults above. It stamps one still file per run and refuses to overwrite or to
     stamp a labelled file again unless you pass `--force`.
   - For social posts, crop to the platform's final aspect first (Instagram 4:5 or 1:1), then
     stamp, so the label sits inside every crop. For stories and reels add `--safe-zone`. The
     result's `label.displayHeight` says how tall the label looks on a phone. A `warning` in the
     result means the label had to shrink to fit (a wide banner): tell the user, and use the icon
     form or a label next to the image. A `label.regionNote` means the region was too small, so the
     label went on the whole image: name the AI part in the alt text or the caption.
   - A folder of images: run `decide` once per distinct kind of content, then stamp each file with
     its own `--description`, and report one table: file, output, alt text.
   - Web page or app: use `render --format html` (real text: zooms, reflows, translates) and put
     the CSS from `render --format html --css` on the page once. For a label over an image, get
     the spot and the options from `place` first (see "HTML pages, ad templates and UI"). The
     HTML label follows the page's
     color-scheme (light unless the page declares light dark); force it with `--theme`. Use SVG or
     PNG (`render ... --out label.svg`) for images, video overlays and places that only accept an
     image.
   - Video, for now: render a PNG (`render ... --out label.png --height <about 6% of the shorter
     side>`) and overlay it away from the player controls. The Code of Practice asks for the label
     at the start, at regular intervals where possible and at least after every break, and
     encourages keeping it for the whole video. This project recommends the whole video, which is
     what this does: `ffmpeg -i in.mp4 -i label.png -filter_complex "overlay=24:24" -c:a copy out.mp4`.
     Put the label sentence in visible text next to the player and say it in the audio
     (a spoken disclaimer at the start, or a line in the audio description); captions alone do not
     reach blind viewers. Labels that change with the timeline are not built yet.
   - Audio: put the visual label on the player, cover or page, and tell the user to add a short
     spoken disclaimer at the start, in the language of the recording; in long or live recordings,
     repeat it at regular intervals where it fits and at least after breaks. Put the sentence at the start of the transcript too.
     Audio alone cannot carry a visual label.
4. **Publish the alt text and the label sentence** with the content. Alt text = a short description
   of what the image shows, then the label sentence, e.g.
   `alt="Modern house among pine trees, architectural visualisation. Generated with AI: image."`
   Look at the image and describe what is actually there; do not reuse the example. Pass
   `--description` so `stamp` and `render` return it composed as `alt`; without it `alt` is null.
   Never use the label sentence (`disclosure`) alone as the alt of an informative image; it is the
   alt of the label itself, which `render` returns as `labelAlt`. When the label is a legal duty,
   also put the sentence in a visible caption. Text burned into pixels is invisible to screen
   readers. For a separate label on a page:
   - inline SVG works as is (it carries `role="img"`, `lang` and an `aria-label`); prefer
     `--format html` for page text that must reflow;
   - as `<img src="label.svg">`, give the img its own alt with the label sentence;
   - when the content's alt or caption already carries the sentence, give the separate label
     `alt=""` or `aria-hidden="true"`, so screen readers do not hear it twice.
5. **Report back** in a few lines: what you labelled and where the files are, whether the label is
   required, precautionary (an `unsure` answer) or voluntary and on what basis, what you left
   unlabelled because the label was only voluntary, and anything you assumed.

## Which label

| Situation | Options |
|---|---|
| All of it made by AI | `--kind generated` |
| Real or human-made content changed by AI (a swapped face, added objects, a replaced voice) | `--kind modified` |
| AI was involved and you want your own wording | `--kind basic --text "Voice generated with AI"` |
| Made by a person, confirmed by the user | `--kind human --media text,image`. If the person wants to place the label by hand, point them to the ready-made files in `labels/human-made` of the repository (or the `human-made-labels.zip` release asset) instead |
| AI image with a human-written text | `--kind generated --media image --human text` |
| An ad or post in a feed, where the caption may be cut off ("See more") or limited to a short text field | Add `--short`, so the word is on the image. The label sentence must be seen at first exposure (Code of Practice Sub-measure 1.2.1), and text below the fold is not. Keep the icon alone only when the sentence is in the first visible line of the caption |
| A human-made layout, mockup or collage containing an AI-generated element | Run decide with `--realistic` for the element. To mark just that element, stamp the whole graphic with `--kind generated --media image --region <the element's box>`; if the post is about the visualisation, crop to the element and stamp that; to label the design as a whole, use `--kind modified --media image` with `--description` naming the AI part |

- `--media` lists only the parts that are AI (or, with `--kind human`, the parts made by a person).
  A type cannot be in both `--media` and `--human`.
- Match the language of the content: `--lang pl` for Polish. Only `en` and `pl` are built in; for
  another EU language pass `--lang` with `--text` in that language (plain words, no abbreviation
  other than "AI"), e.g. `--lang de --text "Mit KI generiert"`. The sentence is then your text
  alone, so name the part in it ("Stimme mit KI generiert").
- Forms (`--form icon|minimal|short|full`, or `--icon`, `--minimal`, `--short`, `--full`): the icon
  is the default of `stamp`, `label` and `place` for AI labels; `--short` adds one word
  ("Generated"), `--full` the phrase "Generated with AI". `render` keeps the short form as its
  default. A pill colour (`--color`, `--palette`) and a human-made part need a pill, so they get the
  short form.
- `--minimal` drops the text but keeps the pill: the author mark (EU "AI" disc, or a hand in the
  same disc) plus the content-type icons, at least 20 px. Without text, "generated" and "modified"
  look the same, in the icon and the minimal form alike, so the alt text must carry the difference.
- The hand mark is this project's design, not an EU icon. It has no meaning under the AI Act.
  Where you use it, explain it once (a legend, caption or an "about our labels" page).
- When the user wants to place an AI label by hand, point them to the ready-made files in
  `labels/ai-generated` of the repository (or the `ai-generated-labels.zip` release asset), and
  say whether the label is required for their content first.
- The untouched EU files: `eu generated --variant black --out ai-generated.svg` (also `basic`,
  `modified`; variants `black`, `white`, `black-transparent`, `white-transparent`).

## Do not

- Do not call labelled content "AI Act compliant". Say the label follows the EU icon guidance;
  `decide` is a checklist, not legal advice.
- Do not put a human-made label on anything generative AI produced or changed, and do not infer it.
- Do not use the EU transparent variants on top of photos; their letters can drop below WCAG
  contrast there. Labels drawn by this tool keep 4.5:1 text contrast on any backdrop.
- Do not shrink a stamped label below its automatic size (it is already the smallest legible one),
  cover it with other UI, animate it (WCAG 2.2.2) or make it flash (WCAG 2.3.1).
- Stamping changes the pixels, so an existing C2PA manifest stops verifying. If the file had one,
  tell the user to sign it again after stamping.

The rules behind `decide`, with sources: `references/rules.md`.
