medium-article-drafter

name	medium-article-drafter
description	Use this skill when a topic has been selected and you need a full Medium-ready article draft. Research the topic with current sources, write a polished Markdown article with title, subtitle, featured-image prompt, sections, tags, and read time, save it to ~/drafts/, and send it over WhatsApp.
user-invocable	true
cron-invocable	false

Medium Article Drafter

Take a selected topic and turn it into a strong, publication-ready Medium draft for a technical audience.

When to Use This Skill

Use this skill when:

• the user selected a shortlist item by number or topic name
• the pipeline has a resolved topic and needs the full draft
• the user asks for a Medium-ready article rather than just research notes

Do not use this skill to discover topics or publish to Medium. Its job is research plus draft generation.

Mission

Produce a full article draft that feels like it could be published with minimal edits by a serious tech writer. The article should be engaging, evidence-driven, conversational, SEO-friendly, and technically credible.

Your output must always be:

• complete
• clean Markdown
• readable in Medium with minimal cleanup
• grounded in current, verifiable research

Accepted Inputs

You may receive:

• a topic name
• a topic number that maps to the latest shortlist
• a full shortlist entry from tech-news-researcher
• a user request that references "the second one", "draft #4", or similar phrasing

If the request is ambiguous, resolve it from shared memory. If ambiguity remains, ask a short clarification question instead of guessing.

Shared Memory Contract

Read from the shared namespace:

• namespace: tech-medium-pipeline
• key: latest_shortlist

If a shortlist exists, map numeric references to the corresponding topic.

Write results back to:

• namespace: tech-medium-pipeline
• key: selected_topic
• namespace: tech-medium-pipeline
• key: latest_draft
• namespace: tech-medium-pipeline
• key: conversation_state

Use a structure equivalent to:

{
  "topic": {
    "headline": "Selected topic",
    "angle": "Chosen article angle",
    "sources": [{"label": "Source", "url": "https://..."}]
  },
  "draft": {
    "title": "Final title",
    "subtitle": "Final subtitle",
    "tags": ["tag1", "tag2"],
    "read_time_minutes": 8,
    "markdown_path": "/Users/.../drafts/2026-04-04-topic.md",
    "featured_image_path": "/Users/.../drafts/images/2026-04-04-topic.png",
    "featured_image_prompt": "The exact prompt used to generate the image"
  }
}

Set featured_image_path to null if image generation was skipped or failed. Never store a path that does not point to an existing file.

Update conversation state to:

```json
{
  "phase": "awaiting_publish_confirmation",
  "last_action": "draft_sent",
  "last_updated_at": "ISO-8601 timestamp"
}

Defaults and Gotchas

• Default to the shortlist's stored angle unless the user explicitly requests a different angle.
• Default to a single coherent argument, not a grab-bag roundup.
• If current reporting is thin or conflicting, narrow the claim rather than padding the draft with generic commentary.
• If the selected topic is too weak for a high-quality article, stop and recommend choosing another topic instead of forcing a draft.

Research Standard

Do real research before writing. Use web_search, web_fetch, and browser tools when needed.

Minimum expectations:

• validate the core story from multiple current sources
• collect concrete facts, dates, product details, or technical signals
• identify the deeper implication for builders, founders, engineers, or AI practitioners
• avoid single-source narratives whenever possible

When the topic is fast-moving:

• distinguish confirmed facts from interpretation
• note uncertainty internally and avoid overstating claims
• prefer language like "suggests", "signals", or "appears to indicate" when evidence is incomplete

Writing Standard

Write like a top Medium tech writer:

• sharp opening hook
• clear point of view
• specific examples
• useful technical framing
• short to medium paragraphs
• scannable headings
• no robotic filler
• no generic hype language

The draft should feel opinionated but evidence-based.

Required Output Structure

Every draft must contain all of the following in this order:

1. # Title
2. ## Subtitle
3. Featured image prompt: followed by a high-quality image prompt
4. Estimated read time: in minutes
5. article introduction
6. 5 to 7 clearly titled sections
7. conclusion
8. Tags: with 6 to 8 Medium-friendly tags

Title

The title should be catchy but precise. Aim for curiosity plus clarity, not clickbait.

Subtitle

The subtitle should explain the promise of the article in one sentence.

Featured Image Prompt

Create a polished prompt suitable for generating a hero image later. It should be visually specific and aligned with the article angle. One or two sentences is enough.

Introduction

Open with why the story matters now. The first 2 to 4 paragraphs should create momentum and orient the reader quickly.

Main Sections

Write 5 to 7 sections. Each section should advance the argument, not repeat the same point. Strong section types include:

• what happened
• why this matters
• technical implications
• product or market implications
• lessons for builders
• risks and counterarguments
• what to watch next

Conclusion

End with a clear takeaway. The conclusion should make the article feel complete, not abruptly stopped.

Tags

Provide 6 to 8 tags that are realistic for Medium discoverability. Use tags a reader or editor would actually search for.

Markdown Format Rules

• Use clean Markdown only.
• Use #, ##, and ### headings appropriately.
• Do not emit HTML unless absolutely required.
• Do not include raw research notes in the final article.
• Do not include inline citations unless the topic truly demands them.
• Do not add placeholder text such as "insert screenshot here".

Read Time Estimation

Estimate read time using approximately 200 words per minute. Round to the nearest whole minute, but do not show the word-count math.

File Saving Rules

Save the finished draft to ~/drafts/ using a timestamped, slugified filename.

Preferred filename shape:

~/drafts/YYYY-MM-DD-topic-slug.md

If the ~/drafts/ directory does not exist, create it.

Featured Image Generation

After saving the Markdown draft, attempt to generate a hero image from the featured image prompt you wrote in the article.

Generation process

1. Extract the Featured image prompt: line from the draft.
2. Use the runtime's image generation tool to produce a high-quality image from that prompt. Preferred settings when configurable: landscape aspect ratio (16:9), photorealistic or clean digital-illustration style, no text overlays.
3. Save the result to ~/drafts/images/ using the same slug and date as the Markdown file:

~/drafts/images/YYYY-MM-DD-topic-slug.png

If ~/drafts/images/ does not exist, create it.

4. Store the absolute image path in the featured_image_path field in shared memory (see Shared Memory Contract).

Fallback

If image generation is unavailable or fails:

• Do not block draft delivery.
• Store null as featured_image_path in memory.
• Note at the end of the WhatsApp message that no featured image was generated and the user can upload one manually before publishing.

Never store a fake or placeholder path. If the image was not saved to disk, the path must be null.

WhatsApp Delivery Rules

Send the full Markdown draft to the user over WhatsApp after saving it.

The WhatsApp message should:

• include the full article body
• remain clean and readable
• end with a direct approval prompt

End with a short call to action such as:

Reply "publish" to post this on Medium, or send edits if you want changes first.

If no featured image was generated, append:

Note: no featured image was generated. Upload one manually in the Medium editor before publishing if you want one.

Quality Filters

Before sending the draft, confirm that:

• the argument is coherent from start to finish
• the article is not just a news recap
• at least one non-obvious insight is present
• the title and subtitle match the actual content
• the article contains 5 to 7 sections, not fewer and not more
• the tone is human, not templated

Guardrails

• Do not hallucinate usage numbers, revenue, users, benchmarks, or quotes.
• Do not present speculation as fact.
• Do not plagiarize source wording.
• Do not turn the article into a bullet-list memo unless the topic truly demands that structure.
• Do not write a shallow "Top 5 things to know" article unless explicitly requested.
• If the topic is too weak to support a high-quality article, say so and suggest choosing another shortlist item.

Completion Checklist

Before ending:

1. Resolve the correct topic from direct input or shared memory.
2. Research the topic with multiple current sources.
3. Write the full Medium-ready Markdown draft.
4. Save the draft to ~/drafts/.
5. Attempt to generate and save the featured image to ~/drafts/images/.
6. Store draft metadata — including featured_image_path (or null) — in shared memory.
7. Send the full draft over WhatsApp.
8. Leave the pipeline in awaiting_publish_confirmation state.