Index of every page on this site: llms.txt
All skills
jk-g avatar

/ai-content-labels

@a5d0c35
Run it yourself

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.

  • 47 files
  • 487.4 KB
  • MIT
  • Updated 3 weeks ago
  • GitHub
Use this Skill: https://skilld.dev/gh/jk-g/ai-content-labels/ai-content-labels

Nothing lands on disk. Nothing to clean up.

Fork this Skill

Edit a local copy. It keeps the author and licence.

SKILL.md

≈235 tokens for metadata: the name and description. ≈5.6k when used: this file. ≈46k more on demand in 5 files.

Description uses 11.7% of example budget

Before choosing a Skill, your Agent reads its name and description. All available Skills share that space.

  • A shorter description leaves more room for other Skills. This entry exceeds our 1% size suggestion.

In our Claude Code example, all Skill names and descriptions share 8,000 characters. This Skill uses ≈939 characters, or 11.7%.

The 1% threshold is a size suggestion. Longer descriptions can still fit.

Your model, settings, and other Skills decide how much text your Agent can read.

Example settings and source

The example uses a 200k-token context and default Claude Code settings. The count includes the name, description, separators, and when_to_use when present. Codex also counts local file paths.

Skit's source and limits: Codex 0.160.1, Claude Code 2.1.292.

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.

Source: SKILL.md on GitHub

skilld matched fixed text patterns in SKILL.md and file names. Patterns miss obfuscated code.

skilld run checks every file with the same patterns. It asks for approval before it loads a Skill with a behavior marked Needs approval.

No third-party reports yet.

Signed by skilld at a5d0c35. This ties the file your Agent reads to that commit on GitHub. It does not review the instructions.

Last checked against GitHub last week.

Activeupdated 3 weeks ago
Other metadata
metadata
{
  "version": "0.7.0",
  "homepage": "https://github.com/JK-G/ai-content-labels"
}

README badge

README badge for jk-g/ai-content-labels