Creating Offers

Creating Offers on angebote.lenne.tech

This skill enables Claude Code to create, optimize, and manage business offers on the lenne.tech Offers platform via MCP tools.

Gotchas

• Content block order values must be ascending without gaps — Gaps in the sequence (e.g., 1, 3, 5) cause rendering glitches on the offers frontend. When deleting a block, re-normalize remaining orders; when inserting, pick the next consecutive integer. The API does not validate this — the bug only surfaces client-side.
• global-ref block type is NOT listed in the standard MCP tool catalog — It's created automatically by the /offers:create workflow when a block is promoted to the offers repository. Users attempting to use it directly via create_offer will get a schema error. The workflow guards this via the @lenne.tech git email check.
• OAuth session expires silently across sessions — The offers-api and offers-api-demo MCP OAuth cookies are tied to the current Claude session and tracked per-server. Resuming an earlier offers session (via --resume) often hits a 401 on the first MCP call without a clear error. Re-authenticate by running a trivial MCP tool first. The first call against offers-api-demo triggers its own OAuth flow even if offers-api is already authenticated.
• git config user.email detection is fragile — The reusable-block detection uses this to gate the lenne.tech-only flow. It fails for developers with a non-@lenne.tech email configured locally (CI machines, temporary clones, rebased-from-fork setups). The step silently skips in those cases, which is the intended fail-safe.
• Template offers cannot be published — only duplicated — Offers with isTemplate: true cannot be mark_sent. Attempting to publish a template silently returns the unchanged offer. To publish, first create_from_template to produce a regular offer, then send that one.
• Hardcoded colors in custom-html break in the other color mode — A block styled with inline colors for a light page turns unreadable when the viewer flips the theme toggle: dark headings and dark body text end up on the dark page background. colorMode: 'light' does NOT prevent this — it only sets the initial preference, the toggle stays available. Every custom-html block must paint its own background on the outermost element whenever it sets text colors. See custom-html-guide.md → "Readability in both color modes".
• cta.text is rendered as plain text, not HTML — Passing "<p>…</p>" prints the literal tags on the offer page. The block docs list it next to HTML-bearing fields, which invites the mistake. Pass a bare sentence. text blocks, custom-html and faq answers are unaffected.
• Embedded credentials in links (https://user:pass@host) are blocked by Chrome — The navigation fails with ERR_FAILED, so a "one-click" demo link built that way is dead on arrival for most recipients. Link the plain URL and list the basic-auth credentials next to it so the browser prompt can be answered.
• Customer quotes must be verbatim and complete — Shortening a testimonial or reference.quote to its "relevant" part, or silently fixing a typo in it, misrepresents a real person. Copying a quote out of an older offer is not safe either: it may already be truncated there. Pull the canonical wording from https://lenne.tech/kundenerfolge and diff it character by character — see best-practices.md → "Customer quotes are verbatim, always".
• File fields survive an update that omits them, so a new block inherits the old block at the same position — update_offer replaces the block array, but OfferService.update() first runs mergeContentBlockFiles(), which pairs stored and incoming blocks by ${order}-${type} and then protects every file field: imageFileId, fileId, animationFileId, previewFileId, fileIds, members[].imageFileId, files[].fileId. Omitting the field or sending "" means keep what is stored — only an explicit null clears it. Because the pairing is positional, a brand-new reference inserted where another reference used to sit silently adopts that block's imageFileId, and the offer then shows the wrong screenshot under the new project name. Whenever a block changes identity, send a real file id or null, never "". See content-blocks.md → "File fields on update".
• A reference block without an image renders an empty placeholder box — The renderer always reserves the image column and falls back to a grey box with an image icon, which reads as broken on a customer-facing page. Every reference needs a real imageFileId. When no product screenshot exists, a purpose-built diagram is a legitimate substitute; a screenshot of a different project is not.

When to Use This Skill

• User asks to create, edit, or optimize an offer/Angebot
• User references content blocks, pricing tables, or offer templates
• User mentions angebote.lenne.tech, demo-angebote.lenne.tech, or the offers platform
• Working inside the offers project repository
• User wants to generate sharing snippets or manage offer status
• User asks about offer analytics, views, downloads, or statistics

Skill Boundaries

Related Skills

Works closely with:

• lt-dev:generating-nest-servers — For backend development on the offers API
• lt-dev:developing-lt-frontend — For frontend development on the offers app

MCP Connection

All offer operations go through one of two MCP servers — the platform ships a production and a demo deployment:

Routing rule. If the user prompt mentions "demo" in an offers context, route ALL tool calls in that prompt to offers-api-demo. Otherwise — including for ambiguous prompts — default to offers-api (production). The UserPromptSubmit hook emits a one-line stage hint that names the correct server; honor that hint.

Both connections use OAuth 2.1 with automatic browser-based login. The OAuth session is per-MCP-server, so the first call against offers-api-demo triggers its own browser-auth flow even if offers-api is already authenticated.

When working inside the offers project repository (local development), the project-level .mcp.json overrides offers-api to http://localhost:3000/mcp so production-flavored tool calls hit your local API. offers-api-demo is unaffected — still points at the deployed demo stage — which is useful for testing demo-only flows from a local dev environment.

Available MCP Tools (identical on both servers):

• add_html_embed — Upload a self-contained HTML file (base64) and create an html-embed content block in one atomic call (validates the HTML, ≤ 5 MB). For larger files prefer create_upload_ticket + HTTP upload
• add_lottie_animation — Upload a Lottie JSON file and create a lottie content block in one atomic call (validates the JSON, rejects unsupported features, ≤ 2 MB)
• add_offer_source — Add a source (text/link/file) to an offer
• create_from_template — Create offer from template
• create_knowledge — Create a knowledge base entry
• create_offer — Create new offer (returns offer + access code). Accepts an optional theme: { enabled, light, dark } per-offer override and an optional colorMode: 'system' | 'light' | 'dark' (forces the offer page into light/dark; default system = browser preference)
• create_upload_ticket — Create a single-use upload URL (valid 15 min) for uploading files via plain HTTP instead of base64 through MCP. purpose selects validation: html-embed (validated HTML, ≤ 5 MB), image (image/*, ≤ 10 MB), file (any, ≤ 25 MB). POST multipart form-data with field file to the returned uploadUrl; the response contains the GridFS file id for use as fileId in content blocks
• delete_knowledge — Delete a knowledge base entry
• delete_offer — Delete offer permanently
• duplicate_offer — Clone offer with new slug + access code (theme is carried over)
• generate_snippet — Generate sharing text with link + access code
• get_default_theme — Read the app-wide default theme that the renderer applies to offers without their own theme
• get_global — Get global block with versions
• get_knowledge — Get a knowledge base entry with full content
• get_offer — Get offer with all content blocks (globals auto-resolved). Returns the effective theme — i.e. the per-offer override when enabled, otherwise the settings default merged in transparently
• get_offer_analytics — Get offer analytics (views, downloads, scroll depth, dwell time)
• get_offer_context — Get full AI context (knowledge + globals + optional offer/sources)
• get_offer_sources — Get all sources for an offer
• list_globals — List reusable global content blocks
• list_knowledge — List knowledge base entries
• list_offers — List offers (with optional status filter)
• list_templates — List template offers
• mark_draft — Reset to draft (sent → draft)
• mark_sent — Mark offer as sent (draft → sent)
• remove_offer_source — Remove a source from an offer
• set_default_theme — Configure the app-wide default theme (light/dark hex palettes). Admin-only on the underlying SettingsService
• update_knowledge — Update a knowledge base entry
• update_lottie_animation — Replace the Lottie JSON of an existing block (keeps the block ID + position; resets first-frame snapshot)
• update_offer — Update offer fields and content blocks. Accepts an optional theme to set/clear the per-offer palette and an optional colorMode ('system'/'light'/'dark')
• upload_knowledge_file — Upload file to knowledge entry (base64)
• upload_offer_source_file — Upload file as offer source (base64)

Reference Files

• ${CLAUDE_SKILL_DIR}/reference/content-blocks.md — All 18 block types with schemas (incl. lottie, html-embed) and upload-ticket usage
• ${CLAUDE_SKILL_DIR}/reference/offer-model.md — Offer model, status lifecycle, per-offer theme and colorMode fields
• ${CLAUDE_SKILL_DIR}/reference/knowledge-base.md — Knowledge base schema and categories
• ${CLAUDE_SKILL_DIR}/reference/custom-html-guide.md — HTML + Tailwind + NuxtUI guide (incl. WYSIWYG editor)
• ${CLAUDE_SKILL_DIR}/reference/theming.md — Per-offer theme override, app-wide default theme, MCP & UI workflows
• ${CLAUDE_SKILL_DIR}/reference/best-practices.md — Content structure and examples

Core Workflow

Creating an Offer

1. Load context — get_offer_context → Company knowledge + global blocks
2. Gather requirements — Title, customer, content, approach
3. Additional materials? — Ask if there are briefing docs/notes
4. Store sources — Via add_offer_source / upload_offer_source_file
5. Choose approach — From template or new
6. Build content blocks — Based on knowledge + sources + briefing
7. Create offer — create_offer
8. Review and refine — get_offer / update_offer
9. Share — mark_sent → generate_snippet

Optimizing an Offer

1. Fetch the offer — get_offer with the offer ID
2. Analyze content — Check structure, completeness, persuasiveness
3. Suggest improvements — Better block order, missing sections, text quality
4. Apply changes — update_offer with improved content blocks

Reusable Global Blocks (lenne.tech Developers Only)

This feature is exclusively for lenne.tech developers. Before evaluating reusable blocks, silently run git config user.email and check if the result contains @lenne.tech. If not, skip this entire section without any mention — the user must not see any hint of this feature.

Detection Logic

command -v git >/dev/null 2>&1 && git config user.email 2>/dev/null | grep -q '@lenne.tech'

• git not installed → skip silently
• git installed but no @lenne.tech email → skip silently
• git installed and @lenne.tech email → proceed with reusable block evaluation

When Detected as lenne.tech Developer

During offer creation or optimization, evaluate whether any content block could be useful across multiple offers (e.g., company introduction, standard team section, recurring FAQ, legal disclaimers, standard CTA). If so:

1. Ask the user: "Dieser Inhaltsblock könnte auch in zukünftigen Angeboten wiederverwendet werden. Soll er als wiederverwendbarer Block im Repository angelegt werden?"
2. If yes, locate or clone the offers repository and create the global block there
3. Verify availability via list_globals MCP tool
4. Automatically replace the original inline block in the current offer with a global-ref block pointing to the new global ID via update_offer

Repository Access

The offers platform repository is hosted at: https://gitlab.lenne.tech/intern/offers

Workflow:

1. Check whether the repo is already cloned on this machine. Checkout paths differ per developer, so search instead of assuming a workspace layout: find "$HOME" -maxdepth 5 -type d -name offers -not -path '*/node_modules/*' 2>/dev/null, then confirm the hit via its git remote get-url origin.
2. If not found, ask the user if they want to clone it: git clone https://gitlab.lenne.tech/intern/offers
3. Use lt-dev:generating-nest-servers / lt-dev:developing-lt-frontend skills for codebase changes

When to Suggest a Global Block

• Content that is not customer-specific (company info, team, legal, processes)
• Blocks that have been manually duplicated across offers
• Standardized sections like "Über uns", "Unser Prozess", "AGB-Hinweis"
• Recurring FAQ items that apply to most offers

Analyzing Offer Performance

Use get_offer_analytics to check how an offer performs. In Claude Desktop, an interactive dashboard with KPI cards, charts, and download stats renders directly in the chat.

Analytics Workflow

1. Check performance — get_offer_analytics with the offer ID
2. Interpret metrics — Views, scroll depth, dwell time, PDF/attachment downloads
3. Suggest improvements — Low scroll depth → restructure content; no downloads → better CTA placement
4. Apply changes — update_offer with optimized blocks

Key Metrics

Content Guidelines

• Language: Always German. Ask the user whether to use "du" (informal) or "Sie" (formal) for addressing the customer. Default is siezen (formal). Avoid direct address where possible.
• Structure: Start with greeting/intro, then main content, end with CTA
• Block order: text → image/video → pricing-table → testimonial/reference → cta
• Pricing: Always use pricing-table block for prices, not inline text
• File references: Reference existing fileId values, or upload new files via create_upload_ticket + HTTP POST (recommended), add_html_embed / add_lottie_animation (small files, base64).

Pre-Submission Checklist

• Offer has a meaningful title
• Content blocks are properly ordered (ascending order from 0)
• All blocks have visible: true unless intentionally hidden
• Customer name/company is set if known
• validUntil date is set if offer has an expiration
• No duplicate block titles
• CTA block included at the end