name: weeknotes-blog-post-composer description: Compose weeknotes blog posts in Jekyll-style Markdown from multiple data sources including Mastodon and Linkding. Use this skill when the user requests to create, draft, or generate weeknotes content for a blog post.

Weeknotes Blog Post Composer

Overview

This skill enables composing weeknotes blog posts by automatically fetching content from multiple sources (Mastodon posts and Linkding bookmarks) and combining them into a well-formatted Jekyll-style Markdown document with YAML frontmatter. The skill handles data collection, formatting, and composition into a ready-to-publish blog post. Optionally, the skill can reference past weeknotes to match the user's personal writing style and voice.

Quick Start

When a user first requests to create weeknotes, check if the skill is configured:

# Check if config exists
if [ ! -f "$HOME/.claude/config/weeknotes-blog-post-composer/config.json" ]; then
  echo "First-time setup required."
  # Run setup script from wherever the skill is installed
  ./scripts/setup.sh
fi

If configuration doesn't exist:

Inform the user that first-time setup is needed
Ask for their Mastodon server URL and access token
Ask for their Linkding instance URL and API token
Optionally ask for their weeknotes archive URL for style reference
Run scripts/setup.sh with their inputs

Getting API Credentials

Mastodon Access Token:

Log into the Mastodon instance
Go to Settings → Development → New Application
Give it a name (e.g., "Weeknotes Composer")
Grant "read" permissions
Copy the access token

Linkding API Token:

Log into the Linkding instance
Go to Settings → Integrations
Click "Create Token"
Copy the generated token

Composing Weeknotes

The primary workflow for composing weeknotes follows these steps:

Step 1: Determine Date Range

By default, use the last 7 days (from 7 days ago to today). If the user specifies a different timeframe, parse their request and extract start/end dates.

Examples of user requests:

"Draft weeknotes for this week" → 7 days ago to today
"Create weeknotes for last week" → 14 days ago to 7 days ago
"Generate weeknotes from November 4-10" → 2025-11-04 to 2025-11-10

Default date calculation:

from datetime import datetime, timedelta
today = datetime.now()
end_date = today.strftime("%Y-%m-%d")
start_date = (today - timedelta(days=7)).strftime("%Y-%m-%d")

So if today is Thursday November 14, 2025:

Start date: Thursday November 7, 2025
End date: Thursday November 14, 2025

Step 2: Fetch Source Data

Run the fetch script to collect data from all configured sources:

# For current week (automatic date calculation)
./scripts/fetch-sources.sh

# For specific date range
./scripts/fetch-sources.sh --start YYYY-MM-DD --end YYYY-MM-DD

# For custom output directory
./scripts/fetch-sources.sh --start YYYY-MM-DD --end YYYY-MM-DD --output-dir PATH

This fetches:

Mastodon posts from the specified date range
Linkding bookmarks from the specified date range

Output files are saved to ~/.claude/cache/weeknotes-blog-post-composer/data/latest/ (or specified directory):

mastodon.md - Formatted Mastodon posts
linkding.md - Formatted bookmarks

Step 3: Read and Analyze Source Data

Verify the fetched data is ready and understand what content is available:

./scripts/prepare-sources.py

This shows which source files are available and their sizes.

Then read the fetched markdown files to understand the content:

# Read Mastodon posts
cat ~/.claude/cache/weeknotes-blog-post-composer/data/latest/mastodon.md

# Read Linkding bookmarks
cat ~/.claude/cache/weeknotes-blog-post-composer/data/latest/linkding.md

Step 3.5: Review Past Weeknotes for Style Reference (Optional)

Check for configured style reference:

# Check if weeknotes_archive URL is configured
cat ~/.claude/config/weeknotes-blog-post-composer/config.json

If the config contains a weeknotes_archive URL, fetch and review 1-2 of the user's past weeknotes to understand their writing style and voice. Use the WebFetch tool to analyze the archive page and individual posts.

If no weeknotes_archive is configured, skip this step and compose in a conversational blog post style.

Key style elements to look for in past weeknotes:

Voice & Tone:
- Conversational and self-deprecating
- Frequent parenthetical asides and tangents
- Playful language (e.g., "Ope", casual interjections)
- Self-aware meta-commentary about the writing process itself
Structure:
- Starts with an opening paragraph containing inline "TL;DR: ..." summary
- Followed by  on its own line (marks intro for Jekyll excerpt)
- 2-3 deeper dives into specific projects or topics (main body)
- "Miscellanea" section near the end (just before conclusion) for brief observations and items that didn't fit elsewhere
  - CRITICAL: Use bullet points for each item in Miscellanea
  - CRITICAL: Include ALL bookmarks/links here as bullet points, not in a separate section
  - CRITICAL: Wrap the Miscellanea bullet points in <div class="weeknote-miscellanea"> tags
  - Miscellanea is a catch-all grab bag for everything else: short observations, bookmarks, reading, random thoughts
- Concluding reflection on the week
Content Balance:
- Equal weighting of technical depth and personal reflection
- Mixed technical projects, personal observations, and humor
- Philosophy embedded in technical writing
- Comfortable with digression and associative thinking
Transitions:
- Uses bullet points and whitespace rather than formal prose bridges
- Ideas progress through thematic gravity or personal relevance
- Stream-of-consciousness feel ("notes accumulated throughout the week")
Distinctive Elements:
- Metaphorical thinking (uses analogies to explain technical challenges)
- Acknowledges when feeling scattered or self-doubting
- References to ongoing projects and past posts
- Comfortable admitting uncertainty or work-in-progress status

When composing, aim to match this voice rather than writing in a generic blog style.

Step 4: Compose Conversational Weeknotes

Important: Do not use template substitution. Instead, read the source markdown and compose it into readable prose.

Style guidance: Match the user's voice from past weeknotes (see Step 3.5) - conversational, self-deprecating, with parenthetical asides and comfortable with tangents. Start with an opening paragraph containing an inline "TL;DR: ..." summary (not a header), followed by  on its own line. Use a "Miscellanea" section near the end (just before the conclusion) as a grab-bag for brief observations and items that didn't fit under other thematic sections. CRITICAL: Format ALL Miscellanea items as bullet points, including bookmarks and links - do NOT create a separate "Bookmarks and Reading" section.

Analyze the fetched content and compose a conversational weeknotes post that:

Summarizes Mastodon activity - Don't just list every post. Instead:
- Identify themes and topics from the week
- Highlight interesting conversations or thoughts
- Group related posts together
- Write in a natural, conversational tone
- Include specific details that are interesting or noteworthy
- Link to actual Mastodon posts using the URLs from the source (e.g., [posted about X](https://masto.hackers.town/@user/12345))
- CRITICAL - AVOID PLAGIARISM: Only use the user's own words from "My Posts" sections directly in prose. Content from "Posts I Boosted" or "Posts I Favorited" should ONLY be:
  - Referenced/cited with attribution (e.g., "Someone on Mastodon pointed out that...")
  - Summarized in your own words, not quoted verbatim as if the user wrote them
  - Alternatively, include blocks of text using blockquotes where it seems interesting
  - Linked to without incorporating their text into the narrative
  - This is extremely important to avoid unintentional plagiarism
- IMPORTANT: Embed images inline when they add value (e.g., ![Alt text](image-url))
- Look for posts with Media entries in the mastodon.md file - these contain images that should be included
- Images are especially important for: cats, interesting screenshots, funny visuals, project photos, etc.
Integrates bookmarks meaningfully - Don't just list links. Instead:
- CRITICAL: ALL bookmarks MUST go in the Miscellanea section as bullet points
- Do NOT create a separate "Bookmarks and Reading" section
- Group related bookmarks together within Miscellanea bullets when possible
- Explain why things were interesting or relevant in the bullet text
- Connect bookmarks to larger thoughts or projects
- Include actual bookmark URLs with descriptive link text (e.g., [Article title](https://example.com))
- Format as bullet points with links in the Miscellanea section
Creates a cohesive narrative - The post should read like a blog post, not a data dump:
- Write in first person
- Use conversational language
- Connect different activities together
- Add context and reflection
- Include section headings that make sense for the content
Uses proper formatting:
- Jekyll-style YAML frontmatter with title, date, tags ("weeknotes" should always be used, along with 3-7 additional tags relevant to the content), and layout
- Opening paragraph with inline "TL;DR: ..." summary (NOT a header)
-  comment on its own line immediately after the opening paragraph (marks excerpt boundary)
- Table of contents nav on its own line after  if there are multiple sections (2+ headings): <nav role="navigation" class="table-of-contents"></nav>
- Markdown headings (##, ###) for structure in the main body
- Links to interesting posts or bookmarks
- Inline images from Mastodon posts where relevant
- Code blocks or quotes where appropriate

Example opening structure:

TL;DR: Our 15-year-old solar inverter died this week, which kicked off a lot of thinking about technology longevity and IoT device lifecycles. Also spent time tinkering with Claude Code skills and bookmarking way too many articles about AI coding tools.

<!--more-->

<nav role="navigation" class="table-of-contents"></nav>

## Technology Longevity
...

Critical: Always include the actual URLs!

When referencing content:

Mastodon posts: Link to the post URL with short link text (3-5 words) for aesthetics (e.g., This week I [posted](https://masto.hackers.town/@user/12345) about solar inverters...)
Bookmarks: Include the bookmark URL with descriptive text (e.g., I found [this article about AI coding](https://example.com/article) particularly interesting...)
Images: Embed Mastodon images inline using ![Description](image-url) when they're interesting or funny
- For multiple consecutive images (3+), wrap them in <image-gallery> tags with newlines before/after the opening and closing tags:
```
<image-gallery>

![First image](url1)

![Second image](url2)

![Third image](url3)

</image-gallery>
```

Example composition approach:

Instead of listing every post, write something like:

This week I spent a lot of time thinking about technology longevity. Our 15-year-old solar inverter died, which kicked off a whole thread about IoT devices and how frustrating it is when tech doesn't have a 15-20 year plan.

CRITICAL - Only use the user's own posts this way! If you want to reference a boosted/favorited post or bookmark:

There's been this interesting article making the rounds about BBS-era communication patterns - explaining how those carefully drafted essay-like responses created a distinctive writing style. But nope, it's just how we learned to write when bandwidth was scarce.

Then for bookmarks in Miscellanea, reference them naturally wrapped in the weeknote-miscellanea div:

## Miscellanea

<div class="weeknote-miscellanea">

* [*Thinking About Thinking With LLMs*](https://example.com/article) - explores how new tools make it easier to code with shallower understanding
* [Another piece](https://example.com/article2) argues that the best programmers still dig deep to understand what's happening underneath

</div>

IMPORTANT: Always scan the mastodon.md for images!

The mastodon.md file includes Media: entries with image URLs and descriptions. Look for these and include them in your weeknotes. Example from the source:

Media: [image](https://cdn.masto.host/.../image.jpg) - Description of the image

When you find these, embed them in the weeknotes like this:

Single image:

Miss Biscuits discovered a new perch:

Multiple images (3+) - use image gallery:

I shared some photos of my 3D printing projects:

Step 5: Review and Revise the Draft

Before finalizing, review the composed weeknotes and make light revisions:

Structure check:
- Ensure Miscellanea section is at the end (just before the conclusion)
- Move any straggling bookmark bullets that didn't fit into main sections into Miscellanea
- Verify all sections flow logically
Prose polish:
- Tighten up verbose sentences
- Remove unnecessary repetition
- Ensure transitions between sections make sense
- Check that the voice remains conversational and natural
Content verification:
- All Mastodon post links are present (3-5 word link text)
- All bookmark URLs are included
- Images are properly embedded (single images inline, 3+ images in <image-gallery>)
- Opening has inline "TL;DR: ..." followed by 
- Table of contents nav is present if there are multiple sections
Final touches:
- Verify 3-7 tags (including "weeknotes")
- Check that conclusion ties things together
- Ensure Miscellanea items are formatted as bullet points

Step 6: Write the Final Blog Post

Create the Jekyll blog post file with:

YAML frontmatter:

---
title: "[Date Range]"
date: YYYY-MM-DD
tags:
  - weeknotes
  - [contextual-tag-1]
  - [contextual-tag-2]
  - [contextual-tag-3]
layout: post
---

Important - Title Format: Use the date range format without the word "Weeknotes" (e.g., "2025 Week 48" or "November 22-26, 2025"). The "weeknotes" tag already categorizes the post, so the title should be concise.

Important - Tags: Always include "weeknotes" as the first tag, then add 2-6 additional contextually appropriate tags based on the content (3-7 tags total). Tags should reflect major themes, technologies, topics, or projects discussed in the post. Examples:

Technical topics: ai, javascript, golang, docker, apis
Project types: side-projects, open-source, blogging
Activities: learning, refactoring, debugging
Themes: productivity, tools, workflows

Analyze the composed content and choose tags that genuinely reflect what the post is about.

Composed content - The conversational weeknotes you composed in Step 4 and revised in Step 5

CRITICAL: Do NOT include "Generated with Claude Code" or similar AI attribution footer in weeknotes posts. These are personal blog posts that should maintain the author's authentic voice throughout.

Save to the appropriate location and filename:

Detecting the blog directory: Check if the current working directory contains content/posts/ - if so, you're in the blog directory.

if [ -d "content/posts" ]; then
  echo "In blog directory - using blog naming convention"
fi

If running from the user's blog directory, use this naming convention:

content/posts/{YYYY}/{YYYY-MM-DD-wWW}.md

Where:

{YYYY} = 4-digit year (of today's date)
{YYYY-MM-DD} = Today's date (the publication date)
{wWW} = ISO week number for today (e.g., w16, w17, w42)

Examples:

content/posts/2025/2025-04-18-w16.md (Week 16, published April 18, 2025)
content/posts/2025/2025-11-13-w46.md (Week 46, published November 13, 2025)

To calculate the week number and filename, use the helper script:

cd /path/to/weeknotes-blog-post-composer
./scripts/calculate-week.py

# Or for a specific date:
./scripts/calculate-week.py --date 2025-11-13

# Or get JSON output:
./scripts/calculate-week.py --json

This script uses today's date (not the start date) and calculates the ISO week number, generating the correct filename format: content/posts/{year}/{date}-w{week}.md

Important: Ensure the year directory exists before saving:

import os
year_dir = f"content/posts/{start_date.year}"
os.makedirs(year_dir, exist_ok=True)

If not in the blog directory, save to a temporary location (e.g., /tmp/weeknotes-YYYY-MM-DD.md) and ask the user where they'd like to move it

Step 7: Select Cover Image Thumbnail

Review the images already embedded in the post and select one to use as the cover thumbnail:

Analyze embedded images:
- Review all images included in the post (from Mastodon posts)
- Consider their alt text/descriptions
- Evaluate which image best represents the overall themes of the weeknotes
Selection criteria:
- Thematic relevance: Image should represent main topics/themes, not just incidental content
- Visual interest: Choose images that are visually distinct and engaging
- Quality: Avoid low-quality screenshots or purely text-based images
- Context: Consider the image's role in the narrative - is it central to a main section or just a side note?
Priority order:
- Images related to primary themes/topics in the post
- Project photos, interesting technical subjects
- Noteworthy screenshots or visual examples
- Cat photos (only if cats are a significant theme of the week)
- Last resort: use the first image in the post

Add to frontmatter:

Update the YAML frontmatter to include the thumbnail: property
Use the full URL of the selected image

---
title: "Weeknotes: [Date Range]"
date: YYYY-MM-DD
thumbnail: "https://cdn.masto.host/.../selected-image.jpg"
tags:
  - weeknotes
  - [other-tags]
layout: post
---

If no suitable images exist in the post:
- Omit the thumbnail: property for now
- The blog software will use the first image as a fallback
- Note: Future enhancement will add public domain image search

Step 8: User Feedback and Final Refinement

Present the composed weeknotes to the user
Ask if they want any adjustments:
- Different tone or style
- More/less detail in certain areas
- Additional context or reflection
- Restructuring of content
Make requested edits
Offer to add a final reflection section if desired

Additional Operations

Updating Binaries

To update the Go CLI binaries to the latest releases:

cd /path/to/weeknotes-blog-post-composer
./scripts/download-binaries.sh

This downloads the latest versions of:

mastodon-to-markdown
linkding-to-markdown

For all supported platforms (darwin-arm64, darwin-amd64, linux-amd64).

Reconfiguring

To update API credentials, change data source settings, or add/update style reference URL:

cd /path/to/weeknotes-blog-post-composer
./scripts/setup.sh

The setup script will detect existing configuration and ask for confirmation before reconfiguring. This includes:

Mastodon server URL and access token
Linkding URL and API token
Weeknotes archive URL for style reference (optional)

Customizing the Output Style

The composition process is flexible and can be customized based on user preferences:

Tone and Style:
- More formal or casual
- Technical vs. personal
- Detailed vs. high-level summaries
Structure:
- Different section organization
- Thematic groupings vs. chronological
- Depth of technical detail
Content Selection:
- Which topics to emphasize
- What to skip or summarize briefly
- Which links/posts deserve more attention

Ask the user about their preferences for these aspects when composing weeknotes.

Adding New Data Sources

To extend the skill with additional data sources:

Add the new Go CLI binary to bin/{platform}-{arch}/
Update scripts/fetch-sources.sh to fetch from the new source
Update the SKILL.md Step 3 to instruct Claude to read the new source files
Update Step 4 composition guidance to explain how to integrate the new content

Platform Detection

All scripts automatically detect the current platform and use the appropriate binary:

macOS ARM64: bin/darwin-arm64/
macOS Intel: bin/darwin-amd64/
Linux AMD64: bin/linux-amd64/

Platform detection is handled automatically via uname commands. No manual configuration needed.

Resources

scripts/

setup.sh - First-time configuration for API credentials
fetch-sources.sh - Fetch data from all configured sources
prepare-sources.py - Verify fetched data and prepare for composition
calculate-week.py - Calculate ISO week number and generate filename for weeknotes
download-binaries.sh - Update Go CLI binaries to latest releases

Runtime Data Directories

All runtime data is stored under ~/.claude/ to keep it separate from skill source code:

Config (~/.claude/config/weeknotes-blog-post-composer/):

config.json - User configuration with API credentials and optional settings (created by setup.sh)
- Contains Mastodon server URL and access token
- Contains Linkding URL and API token
- Optionally contains weeknotes_archive URL for style reference
- This file contains sensitive tokens and is secured with 600 permissions

Binaries (~/.claude/share/weeknotes-blog-post-composer/bin/):

Pre-compiled Go CLI binaries organized by platform:
- darwin-arm64/ - macOS ARM64
- darwin-amd64/ - macOS Intel
- linux-amd64/ - Linux AMD64
mastodon-to-markdown - Fetch Mastodon posts as markdown
linkding-to-markdown - Fetch Linkding bookmarks as markdown
Binaries are platform-specific and automatically selected at runtime

Cache (~/.claude/cache/weeknotes-blog-post-composer/data/):

latest/ - Most recently fetched source data
Other directories for historical or custom fetches
Contains mastodon.md and linkding.md after fetching
This is temporary/ephemeral data that can be safely deleted

Troubleshooting

Configuration Issues

If setup fails:

Verify API credentials are correct
Check that server URLs are accessible
Ensure tokens have appropriate permissions

Binary Not Found

If platform detection fails:

# Check current platform
uname -s  # Should show: Darwin or Linux
uname -m  # Should show: arm64, x86_64, etc.

# Verify binary exists
ls -la bin/darwin-arm64/  # Or appropriate platform directory

Empty Content

If fetched data is empty:

Verify the date range includes actual activity
Check that API credentials have read permissions
Run fetch scripts with --verbose flag for debugging

Template Errors

If composition fails with template errors:

Verify assets/weeknotes-template.md exists and is readable
Check that all required placeholders are present
Ensure no syntax errors in template YAML frontmatter

weeknotes-blog-post-composer

SKILL.md