add-media-mmw

What this skill does

<references>
  <reference name="media-guide" path="references/media-guide.md" />
</references>

<purpose>
You are adding rich media -- diagrams, images, and video embeds -- to an existing blog post. Analyze the post for visual opportunities, then work through each one with the user.
</purpose>

<steps>

  <step id="load-config" number="1">
    <description>Load Configuration</description>

    <load-config>
      <action>Resolve the user's home directory.</action>
      <command language="bash" output="home" tool="Bash">echo $HOME</command>
      <constraint>Never pass `~` to the Read tool.</constraint>

      <read path="<home>/.things/config.json" output="config" />
      <if condition="config-missing">Tell the user: "Run `/things:setup-things` first." Then stop.</if>

      <read path="<home>/.things/mark-my-words/preferences.json" output="preferences" />
      <if condition="preferences-missing">Tell the user: "Run `/setup-mmw` first." Then stop.</if>
    </load-config>

    <action>Read `platform` from preferences.json (default to `quartz` if not set). Read the platform template from `../../platforms/<platform>.md` (relative to this skill's directory). This template defines the platform's image syntax, diagram support, and video embed conventions. Use it for all media insertion.</action>

    <action>Resolve `media_dir`.</action>
    <if condition="media-dir-configured">Compute the full path as `<content_root>/<media_dir>` and ensure the directory exists (`mkdir -p`).</if>
    <if condition="media-dir-null">
      <ask-user-question>
        <question>No media directory is configured. You can still add inline content like Mermaid diagrams and video embeds. For images, would you like to:</question>
        <option>Provide a one-time media directory path for this session</option>
        <option>Continue without image support (diagrams and embeds only)</option>
      </ask-user-question>
      <if condition="user-provides-path">Use it for this session but don't update the preferences file.</if>
    </if>
  </step>

  <step id="resolve-content-location" number="2">
    <description>Resolve Content Location</description>

    <if condition="source-type-remote">
      <action>Check if the repo is already cloned at `<workdir>` (read `workdir` from preferences.json, default `<home>/.mark-my-words`).</action>
      <if condition="not-cloned">
        <command language="bash" tool="Bash">git clone --branch <repo_branch> <repo_url> <workdir></command>
      </if>
      <if condition="already-cloned">Pull latest changes.</if>
      The content root is `<workdir>/<content_dir>/`.
    </if>
    <if condition="source-type-local">The content root is `<local_path>/<content_dir>/`.</if>
  </step>

  <step id="find-post" number="3">
    <description>Find the Post</description>

    <if condition="arguments-provided">
      <action>Search for matching posts by:</action>
      - Filename match (glob for `*<argument>*.md`)
      - Title match (grep for the argument in frontmatter `title:` fields)
      - Content match if no filename/title hits
    </if>

    <if condition="no-arguments">List the 10 most recently modified `.md` files in the content directory with their titles and dates.</if>

    <if condition="multiple-matches">
      <ask-user-question>
        <question>Which post?</question>
        Show title, date, and filename for each.
      </ask-user-question>
    </if>

    <if condition="no-matches">Tell the user and suggest checking the filename or trying a different search term.</if>
  </step>

  <step id="analyze-post" number="4">
    <description>Analyze the Post</description>

    <action>Read the full post content and scan for visual opportunities using the detection patterns from <reference name="media-guide"/>.</action>

    <validate name="diagram-candidates">Processes, architectures, workflows, decision logic, state changes, request/response flows, data models (only suggest Mermaid diagrams if the platform template indicates Mermaid support).</validate>
    <validate name="image-candidates">UI references, visual concepts, results/screenshots, before/after comparisons.</validate>
    <validate name="table-candidates">Comparisons, structured data, feature lists.</validate>
    <validate name="video-candidates">References to talks, demos, tutorials, recordings.</validate>

    <template name="visual-opportunities-output">

    > **Visual opportunities found:**
    >
    > **"How Authentication Works" (line 24)**
    > - Diagram: the login flow described here would work well as a sequence diagram
    >
    > **"Architecture Overview" (line 45)**
    > - Diagram: the three-service architecture could be a flowchart with subgraphs
    > - Image: the system diagram mentioned could be a screenshot or architecture image
    >
    > **"Results" (line 78)**
    > - Image: before/after comparison of the dashboard redesign
    >
    > **"Demo" (line 92)**
    > - Video: the conference talk mentioned could be embedded

    </template>

    <ask-user-question>
      <question>What would you like to do?</question>
      <option>Accept all suggestions</option>
      <option>Pick and choose which ones to add</option>
      <option>Add my own images/media instead</option>
      <option>Skip specific suggestions</option>
    </ask-user-question>
  </step>

  <step id="process-media" number="5">
    <description>Process Media</description>

    Work through each selected item one at a time.

    <phase name="mermaid-diagrams" number="1">
      <constraint>Only available if the platform template indicates Mermaid support (native or plugin-based).</constraint>

      <action>Read the relevant section carefully.</action>
      <action>Generate Mermaid diagram code following the syntax in <reference name="media-guide"/>.</action>
      <action>Show the diagram code to the user for review.</action>

      <ask-user-question>
        <question>Does this diagram look right?</question>
        <option>Looks good</option>
        <option>Revise it</option>
        <option>Skip this one</option>
      </ask-user-question>

      <if condition="diagram-approved">Use Edit to insert the diagram after the text that introduces the concept.</if>
      <if condition="diagram-revision-requested">Adjust and show again.</if>
    </phase>

    <phase name="user-provided-images" number="2">
      <action>Ask for the file path or URL and a description.</action>
      <action>Generate a descriptive kebab-case filename if the original name is generic.</action>
      <action>Generate concise alt text from the description.</action>
      <if condition="local-file">Copy to media dir with `cp`.</if>
      <if condition="remote-url">
        <command language="bash" tool="Bash">curl -L -o <media_dir>/<filename> <url></command>
      </if>
      <action>Insert the image reference using the platform's syntax from the template (e.g., `![[filename|alt text]]` for Quartz, `![alt text](path/filename)` for others).</action>
      <action>Place it following the placement rules in <reference name="media-guide"/>.</action>
    </phase>

    <phase name="web-search-images" number="3">
      <action>Ask the user for the topic or description of what they're looking for.</action>
      <action>Use WebSearch to find relevant images (search `site:unsplash.com <topic>` or `creative commons <topic> photo`).</action>
      <action>Present 2-3 options with descriptions.</action>
      <action>Download the selected image.</action>
      <command language="bash" tool="Bash">curl -L -o <media_dir>/<descriptive-filename> <url></command>
      <action>Generate alt text and insert the reference using the platform's image syntax.</action>
      <constraint>Always include alt text describing the image content.</constraint>
    </phase>

    <phase name="ai-generated-images" number="4">
      <constraint>Only offer this if `ai_image_generation: true` in preferences.json.</constraint>

      <action>Check if image generati