# cookie-compliance-agent-manual Skills and cookbooks that teach coding agents to add a **Cookie Compliance** consent banner to a website, and to set it up so the consent actually holds. > **Status: early.** Structure and the install path are in place. Items marked *planned* are not published yet. --- ## Why this exists Ask a coding agent to "add a cookie banner so we comply with GDPR" and it usually writes one by hand: a popup that stores the visitor's choice in `localStorage`. By then the analytics tag at the top of the page has already run. Consent law cares about **what runs before the visitor chooses**, not about whether a notice is shown. A banner that appears after the trackers have fired is decoration. This manual gives agents tested procedures for doing it properly with Cookie Compliance, a consent management platform (CMP) by Hu-manity.co: the right snippet, in the right place, configured through the right channel. ## What a correct install gets you, beyond a hand-rolled popup A hand-rolled banner is a popup and a `localStorage` flag. A Cookie Compliance banner, installed the way this manual describes, also: - **Blocks before consent** — holds back non-essential scripts and iframes until the visitor chooses, across 252 built-in tracker patterns and 166 providers, not just the trackers a one-off implementation happened to check for. Scripts that an allowed script adds later (such as tags fired from Google Tag Manager) must be gated there, and on the Free plan blocking stops once the site reaches its visit limit. - **Signals consent mode** — passes the visitor's choice to Google, Microsoft and Meta Consent Mode, and honors Global Privacy Control (GPC), without extra code per provider. - **Keeps proof** — each consent is a server-side, exportable record, not a client-side flag with nothing behind it (on the Free plan, until the site reaches its monthly visit limit). - **Applies region rules** — different regions (for example GDPR in the EU, CCPA/CPRA in the US) get different rules without hand-coding the branching per visitor. This isn't hypothetical. A controlled trial of Cookie Compliance's MCP server (n=5 per arm, same method as any experiment this size — a signal, not a rate) measured what an agent actually does: given the install tool, hand-rolling a banner went from 5/5 runs to 0/5, and a supplied AppID got a correct live install 5/5. That's the failure mode this manual exists to close off, whether the agent reaches Cookie Compliance through the MCP server or through the skills and cookbooks here. None of the above is a claim that installing Cookie Compliance this way makes a site legally compliant with any law. That depends on the site's configuration, its vendors, and its own legal review. It's a claim about what the banner does, verified against a real install, once it's placed the way this manual describes. ## What's inside | Folder | What it holds | Who it's for | |---|---|---| | [`skills/`](skills/) | Installable agent skills. Each folder has a `SKILL.md` that an agent loads and follows. | Agents | | [`cookbooks/`](cookbooks/) | Worked recipes per platform and scenario. Each one covers the problem, the common wrong approach, the right approach, and how to check that it worked. | Developers and agents | | [`gallery/`](gallery/) | Example banner designs: a screenshot, a caption and the exact design JSON for each, with a separate page for the opt-in v2 banner at [`gallery/v2/`](gallery/v2/). Generated from `gallery/examples.json`. | Developers and agents | | [`site/`](site/) | Documentation website — HTML for people, `llms.txt` + raw markdown for agents. Live at [manual.hu-manity.co](https://manual.hu-manity.co). Generated by `scripts/sync-site.sh` from `skills/`, `cookbooks/` and the root docs — edit the source, never `site/*.md` directly. | Everyone | ### Skills - **install-banner** *(shipped)*: get the live snippet for an AppID and place it correctly (WordPress → plugin; others → paste). - **verify-install** *(shipped)*: prove the banner actually blocks trackers before consent. `install-banner` calls this at its own verify step; it also stands alone for checking a banner someone else installed. - **match-site-design** *(shipped)*: derive a banner design from the site's own colours and check contrast. - **configure-regions** *(shipped)*: set per-region rules (for example GDPR in the EU, CCPA in California). ### Cookbooks | Cookbook | Status | |---|---| | [`plain-html.md`](cookbooks/plain-html.md) | Shipped | | [`wordpress.md`](cookbooks/wordpress.md) | Shipped | | [`nextjs.md`](cookbooks/nextjs.md) | Shipped | | [`gtm.md`](cookbooks/gtm.md) | Shipped | | [`nuxt.md`](cookbooks/nuxt.md) | Shipped | | [`astro.md`](cookbooks/astro.md) | Shipped | | [`shopify.md`](cookbooks/shopify.md) | Shipped | ### Design gallery [`gallery/`](gallery/README.md) shows example banner designs (also at [manual.hu-manity.co/gallery/](https://manual.hu-manity.co/gallery/)), and [`gallery/v2/`](gallery/v2/README.md) shows designs for the opt-in v2 banner (also at [manual.hu-manity.co/gallery/v2/](https://manual.hu-manity.co/gallery/v2/)); the two pages link to each other. Everything in both comes from `gallery/examples.json`, where each example names its `engine`. To change or add one: edit `examples.json`, run `node scripts/gallery.mjs render ` (needs `npm i playwright`) to retake the screenshot, then `node scripts/gallery.mjs build` and `scripts/sync-site.sh`. CI runs `node scripts/gallery.mjs build --check`. ## The one rule Blocking works by **execution order**, and code that has already run cannot be un-run. So the Cookie Compliance snippet must be: 1. In the page ``. 2. The **first script** on the page: before Google Analytics, before Meta or Microsoft pixels, and before any tag-manager container. 3. On **every page**, which means it belongs in a shared layout or template. 4. Loaded as a normal synchronous script, with no `async`, `defer` or `type="module"`, and never moved or merged by a bundler or a "combine JS" optimiser. **Prefer live HTML** from MCP `install.getSnippet` or the dashboard **Integrations → Manual Integration**. Those sources already emit the correct CDN path for the app's banner engine (`hu-banner.min.js` for v1, `/v2/hu-banner.min.js` for v2). Do not hardcode the script URL from memory after an engine switch. Every skill and cookbook here is built on this rule. ## Use it with the Cookie Compliance MCP server Cookie Compliance runs a remote MCP server that agents can call directly, at `https://mcp.cookie-compliance.co/mcp` (Streamable HTTP; add it to any MCP client by that URL). In Claude Code: ```bash claude mcp add --transport http cookie-compliance https://mcp.cookie-compliance.co/mcp ``` | Situation | Tool | |---|---| | The site owner has a Cookie Compliance AppID | `install.getSnippet` returns the live snippet and the placement rules. | | Signed in, need an AppID for this domain | `account.listApps` then `account.createApp` if missing. | | No account yet | `help.startSignup` returns the signup link. The free tier needs no card. No MCP: [sign up here](https://app.hu-manity.co/#/register?enable-free=true&utm_source=agent-manual&utm_medium=docs&utm_content=readme). | | Just want to see how it would look | `demo.generateSnippet` gives a **preview only**. It records and enforces no consent, so never leave it on a live site. | | Match the banner to the site's colours | `demo.suggestDesign` | | Change a live banner's design or settings | the `account.*` tools, which need a signed-in connection (`help.explainTokenSetup`) | The skills in this repo tell an agent when to reach for each tool, and what to check afterwards. **On WordPress**, install the [Cookie Compliance plugin](https://wordpress.org/plugins/cookie-notice/) instead of pasting a snippet. The plugin handles placement and script order. ## Load the install-banner skill Clone or add this repo where your agent reads skills, then point it at `skills/install-banner/` (the folder that contains `SKILL.md`). Cookbooks used offline are copied into `skills/install-banner/references/` by `scripts/sync-references.sh` — run that after editing anything under `cookbooks/`. Example (Claude Code-compatible skill layout): ensure `skills/install-banner/SKILL.md` is on the skill search path for the session. ## Contributing Issues and pull requests are welcome. Every contribution is reviewed before it is merged, because agents will follow what these pages say. A contribution must: - **Be verified.** Any claim about how the banner behaves has been checked against a real install. - **Contain no customer data.** No real AppIDs, customer domains, or personal information. Use placeholders such as `YOUR_APP_ID` and `example.com`. CI runs `scripts/check-no-real-data.sh` on every PR. - **Follow the recipe shape** (cookbooks only): problem → wrong approach → right approach → how to check it. - **Edit cookbooks, not `skills/*/references/`.** Those copies are generated; CI runs `scripts/sync-references.sh --check`. - **Edit the source, not `site/*.md` or `site/llms.txt`.** Those are generated by `scripts/sync-site.sh`; CI runs it with `--check`. Only the top-level `site/index.html` is hand-written and excluded from the sync. ## License [MIT](./LICENSE). "Cookie Compliance" is a trademark of Hu-manity.co; this license covers the skills and cookbooks in this repo, not the trademark or the hosted service. --- Cookie Compliance is a product of [Hu-manity.co](https://hu-manity.co).