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.
Quick start
Paste this into your coding agent (Claude Code, Cursor, Windsurf, GitHub Copilot, Codex, or any agent that can read a web page):
Install the Cookie Compliance consent banner on this website, start to finish.
Read https://manual.hu-manity.co/start.md and follow it.
Mode: autopilot. Decide the technical steps yourself. Ask me only for what only I can do (sign in or register, the legal region choice, anything that costs money), one question at a time with your recommended answer first.
Do not write your own banner.
More prompts: prompts.md. Connect your AI app to your account: connect.md. The page the agent follows: start.md.
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 282 built-in tracker patterns and 181 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 |
|---|
start.md, connect.md, prompts.md | The page an agent follows to install start to finish, how to connect each AI app to the MCP server, and copy-paste prompts. | Everyone |
skills/ | Installable agent skills. Each folder has a SKILL.md that an agent loads and follows. | Agents |
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/ | Example banner designs: a screenshot, a caption and the exact design JSON for each, with a separate page for the v2 banner at gallery/v2/. Generated from gallery/examples.json. | Developers and agents |
site/ | Documentation website — HTML for people, llms.txt + raw markdown for agents. Live at manual.hu-manity.co. Generated by scripts/sync-site.sh from , and the root docs — edit the source, never directly. |
Skills
- install-banner (shipped): the whole journey, in Autopilot by default: look around, sign in or register, create the app, place the snippet correctly (WordPress → plugin; others → paste), match the design, set regions, verify.
- 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; set the banner font; supported CSS hooks for custom styling.
- configure-regions (shipped): set per-region rules (for example GDPR in the EU, CCPA in California).
Cookbooks
Design gallery
gallery/ shows example banner designs (also at manual.hu-manity.co/gallery/), and gallery/v2/ shows designs for the v2 banner (also at 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 <id> (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:
- In the page
<head>.
- The first script on the page: before Google Analytics, before Meta or Microsoft pixels, and before any tag-manager container.
- On every page, which means it belongs in a shared layout or template.
- 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. Once the app is published (a domain added in the dashboard is published automatically; after later edits, click Publish Now), those sources 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 (Streamable HTTP). Existing customers add https://mcp.cookie-compliance.co/mcp/account and sign in in the browser; to try it with no account, add https://mcp.cookie-compliance.co/mcp. Steps for each AI app: connect.md.
| 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. Ask the owner once about the GDPR starter (configure-regions). |
| No account yet | help.startSignup returns the signup link; pass the site's domain and the add-domain step is pre-filled. The free tier needs no card. A new paid subscription's first payment can use code JOIN-40D (details in start.md); the signup links here carry it. No MCP: sign up here. |
| 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 the account address and a signed-in connection (connect.md) |
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 instead of pasting a snippet. The plugin handles placement and script order.
Load the install-banner skill
The prompt above works without installing anything: the agent fetches the skill from this site. To keep the skill on hand, 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. "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.
