create-blog-post

Create Blog Post (EN → FR, with Image)

Create a complete blog post in Agility CMS from a short topic prompt. The post is authored in English (en-us), then translated into French (fr), and a main image is uploaded. Both locale versions share the same contentID.

Inputs

• Topic prompt — required. A short description of what the post should be about.
• Brand guidelines document — should be attached to the Claude project. Tone, voice, positioning, vocabulary, banned words, CTA patterns, etc. All generated copy MUST follow it.
• Image — required. Either:
  • An image the user attached to the conversation, OR
  • A reference image already in the Agility media library (use its existing CDN URL).

If the user has not supplied a brand guidelines document or an image, ask for them before generating anything.

Target Instance

• Default instanceGuid: 13f09fe2-u (project: Demo Site 2026 in the Starter Templates org).
• Confirm with mcp__Agility-CMS__get_available_instances if the user wants a different instance, or if the GUID is rejected.
• Locales: en-us (default) and fr. Verify with mcp__Agility-CMS__get_locales.

Content Model: Post (container Posts)

Fields that matter when saving (names are case-insensitive):

The Category, Tags, and Author fields themselves are reference-name strings (e.g. "categories", "tags", "authors") — the actual linking is done through the *ID / *Name companion fields.

Workflow

1. Gather context

1. Ask the user for the post topic if it wasn't supplied.
2. Confirm the brand guidelines document is available in the project — if not, ask for it.
3. Confirm how the image will be provided (attached now vs. pick an existing one).

2. Look up linked content (once per session is fine)

Run these in parallel:

• mcp__Agility-CMS__get_content_items → Categories (locale en-us) — pick the best-fit category.
• mcp__Agility-CMS__get_content_items → Authors (locale en-us) — pick an author. If the user hasn't specified, default to Joel Varty (contentID 4) unless the topic clearly suggests another author from the list.
• mcp__Agility-CMS__get_content_items → Tags (locale en-us) — pick 1–3 tags that match the topic. Do NOT invent new tags; only choose from existing ones.

Record the contentID and Name for each selection — you'll need both.

3. Draft the English post

Write the post in en-us, following the brand guidelines. Requirements:

• Heading: Compelling, ≤ 100 chars, aligned with brand voice.
• Slug: Derived from the heading. Lowercase, words separated by -, strip punctuation/stopwords where appropriate (e.g. ai-engine-helping-brands). 3–7 words is a good target.
• Content (HTML): Follow the patterns used by existing posts:
  • Opening paragraph (<p>) that hooks the reader.
  • <h2> section headings (not <h1> — the heading field supplies the H1).
  • Short paragraphs, <ul><li> bullet lists for enumerations, <blockquote><p> for pull quotes with attributions in <strong>.
  • Use semantic HTML — no inline styles or class attributes.
  • Target 500–900 words unless the user specifies length.
• Respect the brand guidelines' tone, terminology, and any banned phrasing.

4. Upload the main image

First, look at the image(s). Before uploading anything, use the Read tool on each image file the user provided. Claude can view JPEG/PNG/WebP directly — this is essential for writing accurate alt text, choosing a featured image, and making sure the image actually matches the post topic.

Featured image selection heuristics (when the user provides several and doesn't specify which is the hero):

1. Prefer landscape orientation — the blog header renders wide.
2. Prefer images with a clear subject and strong composition.
3. Prefer images that visually represent the post's main idea, not a minor detail.
4. Tell the user which one you picked and why in your final report.
5. If you can't analyze for some reason, use the first image.

Option A — user attached one or more new images:

1. Call mcp__Agility-CMS__initialize_media_upload for the chosen hero image with instanceGuid, a descriptive fileName (e.g. predict-iq-hero.jpg — don't carry through UUID-style filenames), and folderPath: "mcp-uploads" (or "blog-images" if the user prefers). If the user supplied multiple images, initialize all uploads in parallel (single tool-call batch).
2. Each response includes an uploadUrl (expires in 5 minutes). Upload the file via curl — also in parallel if there are multiple:

   curl -s -X POST "<uploadUrl>" -F "file=@/absolute/path/to/image.jpg"
   

3. The curl response body contains the final CDN asset URL. Use that URL in the Image field when saving.

Option B — reusing an existing image from the media library:

Skip the upload step and set Image to { "url": "<existing-cdn-url>", "label": "<alt text>" }.

Either way, the Image field on the content item takes the shape:

{
  "url": "https://cdn.agilitycms.com/.../hero.jpg",
  "label": "Short, descriptive alt text"
}

Do NOT duplicate the hero image inside the Content HTML body — the post detail template renders it above the body automatically via the PostImage component. If the user provides other supporting images for the body, those can go in the HTML.

5. Save the English post

Call mcp__Agility-CMS__save_content_items with:

• instanceGuid: 13f09fe2-u (or user-specified)
• locale: en-us
• items: one item with contentID: -1, referenceName: "Posts", and all fields from the "Content Model" table populated.

Capture the returned contentID — you'll reuse it for the French translation.

Example payload (English):

{
  "instanceGuid": "13f09fe2-u",
  "locale": "en-us",
  "items": [{
    "contentID": -1,
    "referenceName": "Posts",
    "fields": {
      "Heading": "…",
      "Slug": "ai-engine-helping-brands",
      "PostDate": "2026-04-21T00:00:00",
      "Category": "categories",
      "CategoryID": "6",
      "CategoryName": "Industry Event",
      "Tags": "tags",
      "TagIDs": "9,8",
      "TagNames": "Technology,A.I.",
      "Author": "authors",
      "AuthorID": "4",
      "AuthorName": "Joel Varty",
      "Content": "<p>…</p><h2>…</h2>…",
      "Image": {
        "url": "https://cdn.agilitycms.com/.../hero.jpg",
        "label": "Descriptive alt text"
      }
    }
  }]
}

6. Translate to French

Translate the post to Canadian French (fr). Requirements:

• Heading: Translated naturally — do not translate brand / product names.
• Slug: Keep IDENTICAL to the English slug (slugs are shared across locales).
• PostDate: Same value as English.
• Category / Tags / Author: Same *ID values as English (linked content is language-neutral). CategoryName, TagNames, AuthorName companion fields can stay as the English names OR be set to localized names if the user has localized them — default to keeping the English names since companions are mostly display helpers and translating them risks breaking filters.
• Content: Translate naturally. Preserve HTML structure exactly (same <h2>, <p>, <ul>, <blockquote> tree). Preserve brand names, product names, and proper nouns untranslated. Adjust idioms; don't machine-translate word-for-word.
• Image: Same url as English. Translate the label (alt text) to French.

7. Save the French translation

Call mcp__Agility-CMS__save_content_items AGAIN, but this time with:

• locale: fr
• The SAME contentID returned from step 5 (NOT -1 — this creates/updates the French version of the same content item).
• All fields translated per step 6.

8. Report back

Always end the response with the following block, filled in:

• Content ID: {contentID}
• Edit in Agility (en-us): https://app.agilitycms.com/instance/13f09fe2-u/en-us/content/list-9/listitem-{contentID}
• Edit in Agility (fr): https://app.agilitycms.com/instance/13f09fe2-u/fr/content/list-9/listitem-{contentID}
• Preview (en-us): https://demo.agilitycms.com/blog?ContentID={contentID}&lang=en-us&agilitypreviewkey=YSJChtivLrrzEdoJ6cric9bo7m%2fRLxAKsdDpcaVipHvA5kGPa1cTVkDVjWNeHlIGLfFTEW8Up6Gu4TOiYyBL3A%3d%3d&agilityts=20260421024609
• Preview (fr): `https://demo.agilitycms.com/blog?ContentID={contentID}&lang=fr&agilitypreviewkey=YSJChtivLrrzEdoJ6cric9bo7m%2fRLxAKsdDpcaVipHvA5kGPa1cTVkDVjWNeHlIGLf

Content truncated.