Typefully Pipeline

Social media engagement tracking and draft creation via Typefully API.

When This Skill Activates

Weekly retro: Joseph says "run the weekly social retro" or similar
Content scheduling: Joseph asks to create drafts from a blog post or content idea
Analytics review: Joseph wants to see how posts performed

Scripts

All scripts live at /opt/data/scripts/typefully/:

Script	Purpose	CLI
`config.py`	Shared config (API key, helpers)	Import only
`analytics.py`	Pull weekly X analytics, write digest + CSV	`python3 analytics.py [--week YYYY-WXX] [--start DATE --end DATE]`
`create_drafts.py`	Create multi-platform drafts	`python3 create_drafts.py --spec variants.json [--publish] [--publish-at DATETIME]`

Weekly Retro Workflow

1. Run analytics for the past week:

   python3 /opt/data/scripts/typefully/analytics.py

Or specify a range:

   python3 /opt/data/scripts/typefully/analytics.py --start 2026-08-10 --end 2026-08-16

2. Review the generated digest at wiki/produce/hermes/social/engage/weekly/YYYY-WXX.md

3. Check ledger.csv for raw data

4. Fill in the theme column in ledger.csv manually (themes from the writing-themes library)

5. Update reception.md with patterns, what resonated, what fell flat

Content Scheduling Workflow

1. Read the source blog post or content idea

2. Author variants.json following the variant authoring rules below

3. Save the spec to /opt/data/variants-{slug}-{format}.json (e.g., /opt/data/variants-my-post-linkedin.json). Never use /tmp/ — HERMES_WRITE_SAFE_ROOT=/opt/data blocks it.

4. Run the script once per format. The script creates one draft per run with one set of enabled platforms. For a LinkedIn post + X tweet + X thread, create three separate spec files and run three times:

   python3 /opt/data/scripts/typefully/create_drafts.py --spec /opt/data/variants-{slug}-linkedin.json
   python3 /opt/data/scripts/typefully/create_drafts.py --spec /opt/data/variants-{slug}-tweet.json
   python3 /opt/data/scripts/typefully/create_drafts.py --spec /opt/data/variants-{slug}-thread.json

5. Collect the Typefully draft URLs from each run's output

6. Tell Joseph the drafts are ready with their Typefully URLs

7. Clean up the temp spec files after confirming drafts are created

8. Joseph reviews and publishes manually from Typefully

Variant Authoring Rules

The variants.json file controls what gets drafted:

{
  "title": "Internal title for the content",
  "platforms": {
    "x": { "enabled": true, "posts": [{"text": "..."}] },
    "linkedin": { "enabled": true, "posts": [{"text": "..."}] },
    "bluesky": { "enabled": true, "posts": [{"text": "..."}] },
    "mastodon": { "enabled": true, "posts": [{"text": "..."}] },
    "threads": { "enabled": true, "posts": [{"text": "..."}] }
  }
}

Platform-Specific Length Rules

X (Twitter): Long-form OK (up to 25k chars). Thread format preferred.
LinkedIn: Long-form OK. Professional tone. Use line breaks for readability.
Bluesky: Max 300 characters per post. Concise, punchy.
Mastodon: Max 500 characters. Can thread but prefer single post.
Threads: Max 500 characters. Casual, conversational.

Voice Rules

Load the blog-to-social skill for voice/style guidance. Key points:

Write in Joseph's I-voice (first person, personal, direct)
No AI slop — load no-ai-slop skill if drafting
Lead with insight, not announcement
End with a question or call to engagement

Weekly Distribution Analysis

When Joseph sends a typefully.md file (or says "analyze my week"):

1. Read the file — it contains all social posts for the week with dates and platform links

2. Pull X analytics — run analytics.py for the week, update ledger.csv

3. Categorize posts — tag each post with a theme from the writing-themes library

4. Write weekly snapshot — save to wiki/produce/hermes/social/engage/weekly/YYYY-WXX.md

Post inventory table (date, topic, theme, platforms, engaged?)
Content mix breakdown
X analytics table (matched to posts)
What worked / what didn't
Behavioral changes adopted that week
Action items for next week

5. Update tracker — append a row to wiki/produce/hermes/social/engage/tracker.md

Posts count, theme, X impressions, X engagement, LinkedIn note, top post, behavioral changes, signal

6. Identify patterns — note emerging trends in the Running Notes section

Weekly Review File Structure

wiki/produce/hermes/social/engage/
├── ledger.csv              (raw X analytics — updated by analytics.py)
├── weekly/
│   ├── 2026-W33.md
│   ├── 2026-W34.md
│   └── ...
└── tracker.md              (cumulative: one row per week, patterns, experiments)

Pitfalls

NEVER auto-publish: Always use draft mode (no --publish flag). Joseph reviews before publishing.
Theme column in ledger.csv: Leave empty — filled manually during retro by Joseph or Hermes.
link_clicks can be null: Always default to 0 when null in the API response.
API key: Read from /opt/data/.env as TYPEFULLY_API_KEY. Never hardcode.
Social set ID: Always 14339 (jjude). Don't change without explicit instruction.
No /tmp writes: HERMES_WRITE_SAFE_ROOT=/opt/data blocks writes to /tmp. Save variants.json to /opt/data/ instead, e.g. /opt/data/variants-{slug}.json. Clean up after use.
No numbering in threads: Do NOT add numbering (1/, 2/, etc.) to thread posts. Typefully handles thread numbering automatically — adding them manually doubles up.

typefully-pipeline