Cursor Ad Agent

Create AI marketing videos and images from inside Cursor. Supports a full creative stack — Seedance 2.0 (flagship video), Sora 2, Veo 3.1, Kling 3.0, Grok Video, Nano Banana 2 / Pro / Edit, ChatGPT Image 2, OmniHuman, and Audio-driven — plus a 37-template static Meta image-ad library and a pipeline for Pixar-style and claymation animated ads.

Generation runs on the Arcads API — you bring your own account and key.

📘 Prefer a guided tour? The operator walkthrough PDF covers the full lifecycle in 26 designed pages — setup and credentials, the 10 skills, competitor research, Arcads creative generation, validated Meta copy, PAUSED deploys, and performance measurement.

Optional community support

This repository works independently. If you want hands-on setup help, workflow discussion, or media-buying strategy beyond the documentation, the repository author also runs The Ai Ads Alchemists, a private community. The linked page is the source for its current offering, schedule, and pricing; participation is not required to use this project.

Prerequisites

The supported baseline is Python 3.9+. The setup checker enforces that minimum. Python 3.12+ is recommended for a single environment that can run every documented workflow; the shared image-ad-clone workflow currently declares Python 3.12+.

Basic image generation, video generation, and polling need only Python and the credentials configured during setup. Some multi-step pipelines need additional tools:

Tool	Required for	Install (macOS)
Python 3.9+ (3.12+ recommended)	Core scripts and readiness checks; 3.12+ for image-ad-clone	brew install python
Bash, curl, and Git	Setup, skill sync, API requests, and cloning	Included with macOS Command Line Tools
ffmpeg	Pixar-style ad, claymation ad, caption-video (stitching + chroma-key overlay)	brew install ffmpeg
jq and bc	Several multi-step media shell scripts	brew install jq bc
Node.js + npx hyperframes	Caption burn-in and local Whisper transcription	brew install node (HyperFrames manages whisper.cpp/model downloads)
openai-whisper Python package	Optional fallback for direct Python transcription	pip install openai-whisper (not needed when npx hyperframes transcribe works)
Pillow	YouTube thumbnail reference preparation	python3 -m pip install pillow
Research/performance deps	Competitor research and Meta Insights polling	python3 -m pip install -r skills/competitor-ad-research/requirements.txt
meta-ad-builder deps	Publishing to Meta Marketing API	python3 -m pip install -r shared/skills/meta-ad-builder/scripts/requirements.txt

The chatgpt-image-ad and nano-banana-image-ad generator scripts are intentionally stdlib-only. image-ad-clone orchestrates those generators and has the Python 3.12+ requirement noted above. Other dependencies are needed only for their matching multi-step workflows.

Linux users: install bash, curl, Git, Python 3, ffmpeg, jq, bc, and Node.js with the distribution package manager. Windows users: WSL2 is recommended; the shell scripts assume Bash.

Get started (5 minutes)

1. Clone this repo

git clone https://github.com/krusemediallc/cursor-ad-agent.git
cd cursor-ad-agent

2. Configure local credentials

The recommended path is the setup script:

./scripts/setup.sh

This will:

• Point you to sign up if you need a generation account: arcads.ai/?via=Cursor
• Ask for your API key (find it at app.arcads.ai/settings/api)
• Save it securely in .env (never committed to git)
• Verify the credential with a read-only API request; it does not generate an asset
• Create your personal MASTER_CONTEXT.md workspace file
• Sync the REST/local skills into .cursor/skills/ and prune stale skill entries
• Run a no-generation Cursor readiness check

For manual setup, copy the public templates and edit .env locally:

test -e .env || cp .env.example .env
chmod 600 .env
test -e MASTER_CONTEXT.md || cp MASTER_CONTEXT.template.md MASTER_CONTEXT.md
./scripts/sync-skill.sh
./scripts/check-cursor-setup.sh

Use either ARCADS_BASIC_AUTH or ARCADS_API_KEY from .env.example. Keep placeholder names in .env.example; put real values only in the ignored .env. Single-quote credential values that contain special characters. Never paste credentials into chat, command-line arguments, issues, screenshots, or committed files. Add optional META_* values only if you intend to use Meta workflows.

3. Open in Cursor

Open the folder. The skills are exposed at .cursor/skills/, and AGENTS.md tells the agent how to work in this repo.

The default Cursor setup uses the REST/local workflows backed by .env. Arcads MCP skills are optional because they require a separately connected MCP server. After configuring Arcads in Cursor Settings > MCP, expose those variants with:

./scripts/sync-skill.sh --include-mcp
./scripts/check-cursor-setup.sh --include-mcp

To verify the default installation and read-only API connection at any time:

./scripts/check-cursor-setup.sh --check-api

Want the orientation banner (installed skills, .env / MASTER_CONTEXT.md status, where the docs live)? Run it any time:

./shared/scripts/check-context.sh

Optional paths are deliberately excluded from the default setup:

• Arcads MCP: connect the Arcads server in Cursor first, then run ./scripts/sync-skill.sh --include-mcp. If the MCP tools are unavailable, use the equivalent default REST/local skill.
• Selenium creative extraction: install skills/competitor-ad-research/requirements-creatives.txt and Chrome/Chromium only when you need automated Ad Library creative downloads. Base competitor pulling and ranking do not require Selenium.

4. Confirm the default skills

The normal sync exposes exactly these 10 REST/local skills:

Skill	Purpose
ad-agent-orchestrator	Human-approved research → creative → deploy → measure lifecycle
arcads-external-api	Arcads endpoints, auth, generation, polling, and asset routing
competitor-ad-research	Meta Ad Library evidence, ranking, and BRIEF.md handoff
generate-youtube-thumbnail	Nano Banana thumbnail batches
human-ad-copy	Copy frameworks, claim receipts, and copy.json validation
meta-performance-loop	Read-only Insights polling and threshold classification
chatgpt-image-ad	Typography and UI-mimicry image ads
nano-banana-image-ad	Photoreal and multi-reference image ads
image-ad-clone	Reusable prompt templates from an existing image ad
meta-ad-builder	Destination discovery, PAUSED deployment, and separate activation

Arcads MCP variants are additional optional skills and are not included in that count.

Safety, cost, and validation boundaries

Meta is PAUSED by default

Campaigns, ad sets, and ads created by this repository are created PAUSED. Preview is the default for status changes. A real activation is a separate, operator-approved mutation and requires the exact confirmation string:

python3 shared/skills/meta-ad-builder/scripts/set-entity-status.py \
  --entity-type ad --entity-id <AD_ID> --status ACTIVE \
  --execute --confirm ACTIVATE

For an orchestrated run, the same command also requires the run ID and approved G9 receipt ID; the tool verifies that receipt and its current scope before the Meta request. See the meta-ad-builder activation flow.

An ACTIVE ad still cannot deliver while its ad set or campaign is PAUSED. Confirm the entire hierarchy, destination, account, and budget in Meta before activating anything.

Arcads costs are estimates

This repository cannot query a billing endpoint. Every Arcads credit total must be treated as an estimate, even when historical creditsCharged values are available. Duration, resolution, references, model, and plan can change the actual charge. Confirm current pricing and final usage in your Arcads dashboard before a paid generation when precision matters.

Offline coverage is not live validation

The end-to-end integration is verified with unit tests, mocks, fixtures, temporary files, compile checks, and CLI contract checks. Those checks do not generate Arcads assets, scrape the Ad Library, create or activate Meta entities, or query live Meta Insights.

The following integration surfaces are currently documented as offline/mock-covered, not operator-approved live-validated: Meta campaign and ad-set creation, multi-account destination listing, chunked video uploads, status changes, Insights polling, and competitor creative extraction. Any live validation requires an operator's credentials and explicit approval; it is not part of a normal test run. See INTEGRATION_HANDOFF.md and CONTRIBUTING.md for the exact boundary.

Workflows

The agent handles API calls, polling, prompt engineering, file organization, and cost confirmation. Workflows are grouped by what you want to make.

---

🔄 End-to-end ad agent (ad-agent-orchestrator)

"Run the full ad agent — research competitors, rank opportunities, generate creatives, write Meta copy, deploy PAUSED, measure performance, and recommend the next test"

The ad-agent-orchestrator skill is the top-level workflow for human-approved, end-to-end Meta campaigns. It is not an unattended spend bot — generation, paid API usage, Meta mutations, activation, and performance thresholds each require separate human approval gates.

Lifecycle:

competitor + first-party research
→ ranked opportunities and one-variable test plan
→ Arcads creative generation (or clone)
→ human-quality Meta copy
→ target account / campaign / ad-set selection
→ PAUSED deployment
→ separately confirmed activation
→ read-only performance polling
→ measured next-test recommendation

Component skills (routed by the orchestrator at each phase):

Phase	Skill
Competitor evidence, BRIEF.md, clone inputs	competitor-ad-research
Typography / UI-mimicry stills	chatgpt-image-ad
Photoreal / lifestyle stills	nano-banana-image-ad
Reverse-engineer a selected image ad	image-ad-clone
Video and other Arcads assets	arcads-external-api
Primary text, headlines, claim ledger	human-ad-copy
Destination discovery, dry-run, PAUSED deploy, activation	meta-ad-builder
Read-only Insights polling and winner/loser thresholds	meta-performance-loop

Runs are tracked in an append-only lineage ledger (outputs/ad-agent/lineage.jsonl). Real deploys must include --run-id so the performance loop can join automatically. Read skills/ad-agent-orchestrator/SKILL.md and run-contract.md before opening a run.

Optional: competitor creative extraction (extract_creatives.py) needs Selenium + Chrome — base Ad Library pulling works with requests only.

---

🎬 Seedance 2.0 videos (the flagship — start here)

Seedance 2.0 is the most flexible model in the stack — 4–15s clips, native audio, image-to-video or video-to-video, reference images, multiple shot styles. Five prompt formulas ship with the skill:

UGC selfie-style product review

"Make a 12-second Seedance UGC video — woman in a kitchen, holding the product, says she stopped buying [competitor]"

Uses the 9-layer UGC formula tuned for Seedance 2.0 (iPhone-shot aesthetic, natural eye-contact breaks, casual delivery). See skills/arcads-external-api/prompting/prompt-library/seedance-2-ugc.md.

Premium product reveal (no person)

"Premium reveal of [product] — dark void, text narrative, hero rotation"

Dark-void aesthetic, text overlays narrating the product's positioning, no person on screen. See skills/arcads-external-api/prompting/prompt-library/seedance-2-premium-reveal.md.

Product hero with elemental effects

"Seedance product hero — water splash, mist, slow rotation"

Splash, mist, light rays, slow rotation. See skills/arcads-external-api/prompting/prompt-library/seedance-2-product-hero.md.

Studio lookbook with voiceover

"Studio lookbook of [product] — multi-look, polished, with voiceover script"

Polished editorial / lookbook style, multi-shot, with embedded dialogue. See skills/arcads-external-api/prompting/prompt-library/seedance-2-studio-lookbook.md.

Feature walkthrough demo

"Seedance feature walkthrough — fast-paced, show off [features]"

Fast-paced product-demo cuts. See skills/arcads-external-api/prompting/prompt-library/seedance-2-feature-walkthrough.md.

---

🎬 Other video models

Sora 2 (text-to-video, up to 20s)

"Generate a 16-second Sora video of [scene]" — optionally drop a product photo as a style reference.

Sora 2 handles longer durations than Veo. The agent auto-selects duration from your script's word count (~2.5 words/sec). Sora 2 remix is also supported via POST /v1/sora2/remix/video for remixing an existing asset.

Veo 3.1 (starting-frame animation)

"Animate this Nano Banana still into an 8-second Veo with dialogue"

Veo 3.1 with startFrame is the standard path for UGC stills → video. The video starts from your exact image with natural human motion and embedded dialogue. The agent confirms the dialogue separately before generating (the MANDATORY dialogue gate).

Kling 3.0 (b-roll / scene)

"Make a 5-second b-roll clip of [scene]" or "Generate a scene of [environment]"

Kling 3.0 is the b-roll / scene workhorse: model: "kling-3.0" on POST /v2/videos/generate (3–15s). The separate POST /v1/b-roll and POST /v1/scene endpoints may also route to Kling depending on workspace configuration — confirm with Arcads.

Grok Video

"Generate a Grok video of [scene]"

Hits POST /v2/videos/generate with model: "grok-video".

OmniHuman / Audio-driven

"OmniHuman avatar of [person] delivering [script]" or "Audio-driven video lip-synced to [audio file]"

POST /v1/omnihuman for talking-avatar workflows; POST /v1/audio-driven for lip-sync against an audio file.

---

🖼️ Image generation (Nano Banana + ChatGPT Image 2)

Create a new AI influencer (10-image character sheet)

"Create a new AI influencer — 22-year-old college student with freckles, golden-hour kitchen lighting"

Two-pass workflow: (1) generate a hero front portrait via Nano Banana, get your approval, (2) generate 9 additional angles (3/4 views, profile, close-up, expressions) with the hero as the reference. All 10 saved to references/influencers/ for future reuse.

UGC product selfie still

"Generate a UGC selfie of Sofia holding [product] in her bedroom"

Combines your character hero + product photo + style references from references/aesthetics/ugc-selfie/ into an authentic-looking iPhone selfie frame grab. Includes skin realism and camera imperfections to fight AI's polished default.

Product showcase still (Nano Banana → Veo / Seedance video)

"AI person holding [product] talking about [feature]"

Two-step: Nano Banana still of person + product → user approves → start-frame → video via Veo 3.1 or Seedance 2.0.

Recreate an influencer from a reference photo

"Recreate this influencer's look from this reference photo"

Two-step: Nano Banana still from refImageAsBase64 → user approves → Veo 3.1 with startFrame.

Nano Banana model choice

Default is nano-banana-2. Use model: "nano-banana" for Nano Banana Pro (Gemini 3 Pro Image — higher fidelity, locks character identity tighter across reference batches). nano-banana-edit for inpainting.

---

📸 Static Meta image ad creative (37-template library)

"Make me an Apple Notes-style ad for my product" / "Generate a Forbes editorial ad" / "Clone this comparison-table ad as a template"

A three-skill family for static Meta image ads with a shared library of 37 prompt templates (Apple Notes lists, editorial hero, fake Google search, comparison tables, sticky-note flatlays, fake Slack threads, ChatGPT-conversation ads, iMessage screenshots, magazine cover, billboard, museum exhibit, weather forecast UI, scratch-off ticket, founder letter, dating-app card, and more).

• chatgpt-image-ad — typography-heavy / UI-mimicry creatives (gpt-image-2)
• nano-banana-image-ad — photoreal / lifestyle / multi-reference creatives (Nano Banana 2 / Pro / Edit)
• image-ad-clone — single backend-agnostic skill that reverse-engineers any existing ad image into a new library entry (asks which generator to validate against at Phase 1; optionally cross-validates against the other at Phase 8)

Output is image files. Pair with the meta-ad-builder skill to publish as paused Meta ads. Read shared/skills/image-ad-prompting/OVERVIEW.md first — it has the decision tree (which backend for which template), the aspect-ratio compatibility matrix per backend, and the standard generate / clone workflows. Generation uses live Arcads calls and is not part of offline verification.

---

🎞️ Multi-step animated ad pipelines

Pixar-style 3D animated ad

"Make a Pixar-style ad for [product] — anthropomorphized mascot, 8-beat story arc"

Lock cast sheet → ChatGPT Image 2 storyboard stills (sequential, prior frame as ref for identity lock, max 5 referenceImages) → Seedance 2.0 image-to-video per beat → ffmpeg stitch + burn captions. See shared/skills/pixar-style-ad/prompting/guide.md.

Claymation / Aardman-style ad

"Make a claymation ad — sculpted plasticine characters, narrator-driven, 60–115s"

Same backbone as Pixar with an 8-beat narrator-driven story arc and clay textures. ChatGPT Image 2 storyboard → Seedance 2.0 i2v → ffmpeg stitch with optional fps=12,fps=24 stop-motion judder. VO generated externally (ElevenLabs) and mixed in post. See shared/skills/claymation-ad/prompting/guide.md.

YouTube thumbnails (5 formulas)

"Make 6 YouTube thumbnail variations with my face and product"

Specialized generate-youtube-thumbnail skill: peace-sign/branding, real-vs-AI comparison, terminal flow, reaction shock, and before/after split. Likeness guidance can use multiple face references. Parallel batch generation uses Nano Banana 2. See skills/generate-youtube-thumbnail/.

Burn captions onto a finished video

"Add captions to this MP4"

Out-of-band post-step (no generation call) that works on any source — Pixar, claymation, UGC, B-roll. HyperFrames + Whisper medium.en for transcription → group word-level transcript into reading phrases → render captions-only HTML over #ff00ff magenta → ffmpeg chroma-key overlay. See shared/skills/caption-video/prompting/guide.md.

---

🔄 Reverse-engineer existing creative

Analyze a reference video into a Seedance template

"Reverse-engineer this video into a reusable Seedance template"

The analyze-video workflow under skills/arcads-external-api/prompting/analyze-video/ extracts the structure of a reference video into a parameterizable Seedance 2.0 prompt template.

Clone an existing video ad for a different product

"Clone this video ad for our new product"

skills/arcads-external-api/prompting/clone-ad/ — end-to-end: analyze the reference → adapt to the new product → generate. The companion to analyze-video when you want to ship the cloned version directly.

Clone a static image ad into the prompt library

"Reverse-engineer this image ad as a reusable template"

The image-ad-clone skill produces parameterizable entries for the 37-template library (see above).

---

📤 Publish creatives as paused Meta ads

"Publish this approved creative as a paused Meta ad in my account"

The meta-ad-builder skill (in shared/skills/) takes a finished creative path and uploads it via the Meta Marketing API. Every campaign, ad set, and ad is created PAUSED. Activation is a separate manual Ads Manager action or the separately confirmed status command shown above. The skill also has a research path to pull top-spending ads and competitor ads. Auth uses META_* values in .env.

What's in the box

Path	What it does
skills/arcads-external-api/	The core skill. API reference, prompting guide, per-model prompt libraries (Seedance / Sora / Veo / Kling / Nano Banana), analyze-video + clone-ad sub-workflows.
skills/generate-youtube-thumbnail/	5 YouTube thumbnail formulas with parallel batch generation against Nano Banana 2.
skills/chatgpt-image-ad/	Static Meta image-ad creatives via gpt-image-2 (typography / UI mimicry).
skills/nano-banana-image-ad/	Static Meta image-ad creatives via Nano Banana 2 / Pro / Edit (photoreal / lifestyle).
skills/image-ad-clone/	Reverse-engineer an existing ad image into a reusable library entry. Backend-agnostic — asks at Phase 1 whether to validate via gpt-image-2 or Nano Banana, optionally cross-validates against the other at Phase 8.
shared/skills/image-ad-prompting/	Shared brain for the image-ad ecosystem: 37 prompt templates, safety suffixes, entry format, and OVERVIEW.md.
shared/skills/pixar-style-ad/	8-beat anthropomorphized mascot ad via GPT Image 2 storyboard + Seedance 2.0 i2v.
shared/skills/claymation-ad/	Aardman-style 8-beat clay narrative ad; same backbone as Pixar with stop-motion judder option.
shared/skills/caption-video/	Out-of-band post step: HyperFrames + Whisper + ffmpeg chroma-key to burn captions onto any finished MP4.
skills/ad-agent-orchestrator/	Top-level end-to-end workflow: research → test plan → Arcads → copy → Meta → performance → next test. Human approval gates at every phase.
skills/competitor-ad-research/	Meta Ad Library competitor pull, ranking, optional creative extraction, and BRIEF.md handoffs.
skills/human-ad-copy/	Direct-response copy frameworks, claim/receipt workflow, and Meta copy.json validation.
skills/meta-performance-loop/	Read-only Meta Insights polling, threshold-based winner/loser status, and next-test recommendations.
scripts/lib/ad_agent_lineage.py	Append-only run ledger (init, event, show, manifest) for orchestrator lifecycle tracking.
shared/skills/meta-ad-builder/	Publish finished creatives as paused Meta ads via the Meta Marketing API.
shared/scripts/check-context.sh	Orientation banner — lists installed skills, checks .env / MASTER_CONTEXT.md status, surfaces ecosystem pointers. Run it manually.
MASTER_CONTEXT.template.md	Template for your workspace context (credit costs, brand voice, learnings).
MASTER_CONTEXT.md	Your personalized copy (created by setup, not committed to git).
.env	Your API key (created by setup, never committed).
scripts/setup.sh	One-time setup.
scripts/sync-skill.sh	Rebuilds .cursor/skills/ from canonical sources and prunes stale entries. Add --include-mcp only when Arcads MCP is connected in Cursor.
scripts/check-cursor-setup.sh	No-generation Cursor readiness check. Add --check-api for read-only Arcads auth verification.
scripts/check-arcads-env.sh	Tests API connectivity.
scripts/release-check.sh	Credential-free public release gate: skill sync, readiness, source/link/secret checks, and six offline test suites.
CONTRIBUTING.md	Canonical source rules, offline commands, and live-validation boundary.
SECURITY.md	Responsible disclosure and credential-handling policy.
references/	Drop reference images here (influencers, products, aesthetics) — gitignored.
logs/arcads-api.jsonl	Local, gitignored operational log: model, duration, resolution, reference counts, and creditsCharged. It is not part of the public snapshot.

Your API key

Your key authenticates with the generation API. During setup you paste it once and the agent uses it from .env automatically. You never need to paste it into chat.

Need an account first? Create one here: https://arcads.ai/?via=Cursor

Find your key: Dashboard > Settings > API

For Meta-ad publishing (the meta-ad-builder skill), you'll also need META_ACCESS_TOKEN and META_AD_ACCOUNT_ID in .env — the .env.example has placeholder rows.

Project memory

MASTER_CONTEXT.md is your workspace's living memory. The agent reads it at the start of every session and writes learnings back. It stores:

• Default product — auto-populated on first use so you're never asked "which product?" again
• Default project / folder — session output organized in the dashboard automatically
• Credit costs — you fill in once (or the agent asks), then every session has them
• Image hosting — where you stage reference images if a workflow needs hosted URLs
• Brand voice — optional tone, audience, and word preferences
• API learnings — universal quirks that help the agent work better
• Changelog — dated notes from each session

Supported models

Model	Type	Best for	Notes
Seedance 2.0	Video (4–15s)	Flagship video model. UGC, premium reveal, product hero, lookbook, feature walkthrough. Native audio.	model: "seedance-2.0". 5 prompt formulas ship. Mutually exclusive: referenceVideos vs referenceImages.
Sora 2	Video (up to 20s)	Long-duration text-to-video, image-to-video with product photo as style ref.	model: "sora2". Duration enum: [4, 8, 12, 16, 20]. Remix: POST /v1/sora2/remix/video.
Veo 3.1	Video (~8s)	Animating a starting frame (UGC stills → video). Best for character / influencer flows.	model: "veo31". startFrame and referenceImages are mutually exclusive — default startFrame for single person photos.
Kling 3.0	Video (3–15s)	B-roll and scene generation.	model: "kling-3.0" on POST /v2/videos/generate. The separate /v1/b-roll and /v1/scene endpoints may route to Kling depending on workspace configuration.
Grok Video	Video	Text-to-video via xAI's video model.	model: "grok-video".
Nano Banana 2	Image	Default still-image model. UGC stills, character sheets, product shots, influencer recreation, image-ad creatives.	model: "nano-banana-2".
Nano Banana Pro	Image	Premium image quality (Gemini 3 Pro Image). Locks character identity tighter across batches.	model: "nano-banana" (the bare string maps to Pro).
Nano Banana Edit	Image	Inpaint / edit an existing image.	model: "nano-banana-edit".
ChatGPT Image 2	Image	Typography-heavy / UI-mimicry static ad creatives. Used by chatgpt-image-ad skill + the Pixar / Claymation storyboard pipelines.	model: "gpt-image-2". Max 5 referenceImages. Aspect ratios: 1:1, 16:9, 9:16.
OmniHuman	Video	Talking-avatar / lip-sync workflows.	POST /v1/omnihuman.
Audio-driven	Video	Lip-sync a video to a supplied audio file.	POST /v1/audio-driven.

Cost is presented as an estimate before every generation; the agent reads logs/arcads-api.jsonl for historical creditsCharged values matching your config. Always confirm exact pricing in your dashboard if it matters for budgeting.

Reference images

Drop images into the references/ folder and the agent will use them automatically:

• references/influencers/ — Photos of people to recreate as AI-generated content (and saved character sheets)
• references/products/ — Product photos for showcase videos and hero images
• references/aesthetics/ — Style references organized by vibe (ugc-selfie/, cinematic/, etc.)

Images stay local — the folder contents are gitignored. The agent auto-upscales any reference below 1024px (the API's min-size floor) using Lanczos before submitting.

Editing skills

Repository-specific skills have canonical source under skills/<name>/. Content under shared/ is synchronized from an upstream source and carries its own generated-content warning; coordinate shared changes with the maintainers instead of editing the generated copy here. After changing a canonical skill, run:

./scripts/sync-skill.sh

This rebuilds .cursor/skills/ (which is gitignored and generated) from skills/ plus the available upstream-managed shared/skills/ content. Removed or renamed skills cannot linger, and ignored machine-specific files are not copied into Cursor discovery. Never edit .cursor/skills/ directly. If your Cursor instance has Arcads MCP configured, use ./scripts/sync-skill.sh --include-mcp.

See CONTRIBUTING.md for the offline test commands and publication checks.

Staying current

This repo updates regularly — new templates land in the prompt library, new workflows get added, bugs get fixed. To stay in sync with upstream:

• To pull updates: git pull origin main from the repo root. If you've made local changes to tracked files, stash them first: git stash && git pull && git stash pop. Re-run ./scripts/sync-skill.sh afterwards if skills changed.
• If you've forked the repo on GitHub: click the "Sync fork" button on your fork's page to bring it in line with this upstream, then git pull locally.
• Customizations: your .env, MASTER_CONTEXT.md, reference media, outputs/, and operational logs (logs/*.jsonl) are gitignored — they survive every update. If you customize a core skill file (e.g. tune a SKILL.md for your brand), expect potential merge conflicts on git pull — keep custom versions under a non-tracked path (e.g. local-skills/) if you don't want them affected by upstream updates.

Security

• .env is gitignored and must never be committed.
• MASTER_CONTEXT.md is gitignored and can contain account and workspace data.
• Never paste API keys or access tokens in GitHub issues or public chats.
• PAUSED-by-default reduces accidental spend; activation still requires an operator to review the hierarchy and take a separate action.

For responsible disclosure and credential-response guidance, read SECURITY.md.

Vendor prompting guides

Model	Guide
Seedance 2.0	Aligned to ByteDance's published Seedance prompting platform (the skill summarizes this in skills/arcads-external-api/prompting/prompt-library/seedance-2.md)
Sora 2	OpenAI — Sora 2 prompting guide
Veo 3.1	Google Cloud — Veo 3.1
Kling 3.0	Kling — user guide
Nano Banana	Google Cloud — Nano Banana
ChatGPT Image 2	OpenAI image-generation guidance (summarized in skills/chatgpt-image-ad/SKILL.md with model-specific strengths and limits)

API docs

Swagger UI

Other AI assistants

Point your assistant at AGENTS.md and MASTER_CONTEXT.md + the skill paths in skills/ and shared/skills/. See AGENTS.md for details.

Contributing and license

• Contribution workflow and offline checks: CONTRIBUTING.md
• Security reports and credential handling: SECURITY.md
• License: MIT
• Imported-content attribution: THIRD_PARTY_NOTICES.md
• Source classification: PROVENANCE.md