菜单
Compose weeknotes blog posts in Jekyll-style Markdown from six sources of personal signal (Mastodon, Linkding, GitHub, Spotify, YouTube, Pocket Casts) via the me-to-markdown orchestrator. Use this skill when the user requests to create, draft, or generate weeknotes content for a blog post.
用 Codex 或 Claude 帮你安装 复制这段 Prompt，粘贴到 Codex、Claude 或其他助手里，让它检查 Skill 页面并帮你完成安装。
基于 SOC 职业分类
| name | weeknotes-composer |
| description | Compose weeknotes blog posts in Jekyll-style Markdown from six sources of personal signal (Mastodon, Linkding, GitHub, Spotify, YouTube, Pocket Casts) via the me-to-markdown orchestrator. Use this skill when the user requests to create, draft, or generate weeknotes content for a blog post. |
This skill composes weeknotes blog posts in Jekyll-style Markdown by fetching personal signal from six sources — Mastodon, Linkding, GitHub, Spotify, YouTube, and Pocket Casts — through the me-to-markdown orchestrator, then synthesizing that signal into a readable, first-person blog post. The skill is a pure delegation layer: it calls me-to-markdown export to collect all data in one combined file, then reads and composes from that file. It does not manage tokens, install binaries, or run auth flows — those are me-to-markdown's job. Output is a Jekyll-style Markdown file with YAML frontmatter saved to the blog's standard post directory structure.
me-to-markdown is on $PATH — verify with me-to-markdown versionme-to-markdown install has been run to populate its managed binariesme-to-markdown auth has been run (or the user has hand-written the env file at $XDG_CONFIG_HOME/me-to-markdown/env)me-to-markdown list — all six tools should show status path or managed, not missingme-to-markdown command and stop. The skill MUST NOT attempt to install binaries or run auth flows on the user's behalf.# Determine the week's date range (default: last 7 days).
# Then fetch combined signal:
mkdir -p ~/.claude/cache/weeknotes-composer/data/latest
me-to-markdown export --since YYYY-MM-DD --until YYYY-MM-DD \
-o ~/.claude/cache/weeknotes-composer/data/latest/combined.md
# Optional: also render YouTube transcripts if the cache has any.
# Offline-only; produces a "no transcripts available" file if cache is empty.
youtube-to-markdown transcripts render --since YYYY-MM-DD --until YYYY-MM-DD \
-o ~/.claude/cache/weeknotes-composer/data/latest/youtube-transcripts.md
# Then read both files and compose per the workflow below.
The primary workflow for composing weeknotes follows these steps:
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:
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:
Use ISO date format (YYYY-MM-DD) for both flags. The orchestrator handles end-of-day inclusivity natively — pass --until YYYY-MM-DD directly with no adjustment.
With start/end dates from Step 1, run the orchestrator to collect all six sources in parallel:
mkdir -p ~/.claude/cache/weeknotes-composer/data/latest
me-to-markdown export --since YYYY-MM-DD --until YYYY-MM-DD \
-o ~/.claude/cache/weeknotes-composer/data/latest/combined.md
If the exit code is non-zero, the orchestrator has already written per-tool error sections into combined.md. Surface those error sections to the user (so they know which source failed and why), but continue composing with whatever signal did come through. A partial run is better than no post.
youtube-to-markdown ships an optional companion command, transcripts render, that emits transcript text for liked videos in the window — actual prose, not just titles. This is offline-only (reads from a local cache; no yt-dlp, no network), so it's safe to run unconditionally:
youtube-to-markdown transcripts render \
--since YYYY-MM-DD --until YYYY-MM-DD \
-o ~/.claude/cache/weeknotes-composer/data/latest/youtube-transcripts.md
If youtube-to-markdown is on $PATH (it should be after me-to-markdown install), run this. If the binary isn't found, skip silently.
Look at the resulting file. Three outcomes:
### [Title](URL) blocks each followed by prose. Use this content when composing the YouTube section; transcripts are the actual signal here, not the title-only listings in combined.md._No transcripts available in this window._ — the user has not run youtube-to-markdown transcripts fetch for this window. The cache is empty for this period. Compose YouTube content from titles only (as in combined.md), and at the END of the workflow (Step 9 feedback) mention the user can run youtube-to-markdown transcripts fetch --since YYYY-MM-DD --until YYYY-MM-DD (requires yt-dlp installed) before re-running the skill if they want richer YouTube context next time.The skill MUST NOT run transcripts fetch itself — that step requires yt-dlp, makes network calls, takes time, can fail, and is intentionally a user-driven workflow.
Read ~/.claude/cache/weeknotes-composer/data/latest/combined.md. The file contains six section headers in registry order:
## Mastodon## Linkding## GitHub## Spotify## YouTube## Pocket CastsSkim each section. Identify themes, note interesting items, get a sense of what this week was actually about. If a source's section is empty or contains an error block, mention it briefly to the user — but treat the active sources (Mastodon, GitHub, Linkding) differently from passive ones (Spotify, YouTube, Pocket Casts). For active sources, absence may be worth flagging ("no Mastodon activity this week — was that intentional?"). For passive sources, absence usually just means a quiet week and you can silently omit them from the composed post.
If Step 2.5 produced a populated transcripts file, also read ~/.claude/cache/weeknotes-composer/data/latest/youtube-transcripts.md. For videos with transcripts, the prose body is the substantive content — the title alone is rarely enough to know whether a video was thematically central. Skim for ideas, arguments, vivid moments, or things that connect to the week's other threads.
Check for configured style reference:
# Check if weeknotes_archive URL is configured
cat ~/.claude/config/weeknotes-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 the config file doesn't exist, prompt the user once for an optional archive URL. Write the config file with either the provided URL or "weeknotes_archive": null if the user declines or has no archive — this prevents re-prompting on future runs.
If no weeknotes_archive is configured (or the file has null), skip this step and compose in a conversational blog post style.
Key style elements to look for in past weeknotes:
Voice & Tone:
Structure:
<!--more--> on its own line (marks intro for Jekyll excerpt)<div class="weeknote-miscellanea"> tagsContent Balance:
Transitions:
Distinctive Elements:
When composing, aim to match this voice rather than writing in a generic blog style.
Step 3.5 was about voice and style. This step is different — it's about content continuity, specifically what NOT to repeat from the previous post.
CRITICAL — Check Previous Weeknotes: Before composing, if running from a blog directory (i.e., content/posts/ exists), find the most recently modified post and read it to identify topics and content already covered. If not in a blog directory, skip this step and note that you're composing without prior-week continuity context. Weeknotes should build on previous posts, not repeat them:
Catchup-window caveat: When the composing window spans multiple weeks (more than ~7 days), the previous post is older than "last week" and is less load-bearing as a continuity anchor. Still skim it briefly, but it's expected that this post will re-introduce some context the reader hasn't seen recently — that's a feature of catchup posts, not a violation of the no-repetition rule. A reasonable touchpoint: "Last weeknote was [N] weeks ago; here's what's happened since…"
Style guidance: Match the user's voice from past weeknotes (see Step 3.5), and avoid repeating topics from the most recent post (see Step 4) — 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 <!--more--> 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:
[posted about X](https://masto.hackers.town/@user/12345)))## Mastodon section of combined.md — these contain images that should be includedIntegrates bookmarks meaningfully — Don't just list links. Instead:
[Article title](https://example.com))Creates a cohesive narrative — The post should read like a blog post, not a data dump:
Uses proper formatting:
<!--more--> comment on its own line immediately after the opening paragraph (marks excerpt boundary)<!--more--> if there are multiple sections (2+ headings): <nav role="navigation" class="table-of-contents"></nav>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:
This week I [posted](https://masto.hackers.town/@user/12345) about solar inverters...)I found [this article about AI coding](https://example.com/article) particularly interesting...) when they're interesting or funny
<image-gallery> tags with newlines before/after the opening and closing tags:
<image-gallery>
</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.
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 section of combined.md for images!
The Mastodon section 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:
Mastodon — Primary narrative driver. Write in first-person prose. Only quote your own posts directly; summarize boosts/favorites with attribution ("someone on Mastodon pointed out...") or use blockquotes. Always link to posts with 3-5 word link text. Embed images inline (single) or use <image-gallery> (3+). All the plagiarism-guard rules from the Mastodon composition section above apply.
Linkding — Default to Miscellanea bullets inside the weeknote-miscellanea div. Group related bookmarks together; explain why something was interesting in the bullet text rather than just pasting a title. Promote to a top-level section when a cluster of 2+ bookmarks shares a thematic arc that's load-bearing for the week — e.g., "a month of bookmarks all circling the same question about coding-with-agents" wants a real section (with quoted excerpts and connecting prose), not a flat list. The mirror of the GitHub rule: bullets when light, section when thematically central. Plagiarism guard applies to bookmark excerpts the same way it does to Mastodon boosts — quote sparingly, attribute, and link.
GitHub — Thematic project-by-project treatment when there's enough signal. Group events by repo/project. Write about what you actually did this week ("spent the week on X, fixed Y") — don't dump raw event lists. Link to specific PRs/commits/issues where they illustrate the story. If GitHub activity was light this week, demote to one or two Miscellanea bullets.
Spotify — Passive consumption signal. Default to Miscellanea bullets if anything at all. Promote to a dedicated section ONLY when listening was thematically central to the week (e.g., a specific album in heavy rotation tied to a mood or project). Keep volume proportionate — a week of background music ≠ a week's narrative.
YouTube — Liked-videos signal (deliberate, more meaningful than Spotify plays, but still passive consumption). Default to Miscellanea bullets. Promote to a section only when a video or theme was notably influential. When transcripts are available (see Step 2.5), prefer the transcript prose over the title as your composition source — titles like "How America Experienced Classic Doctor Who" only hint at the content; the transcript reveals the actual argument. Quote sparingly (videos are someone else's words, not yours — same plagiarism guard as boosts/favorites applies), but cite specific moments or claims to make the bullet substantive.
Embed component (<youtube-embed>). The blog has a custom element for inline YouTube players. Use it like this, on its own line as its own paragraph (blank line before and after):
<youtube-embed video-id="VIDEO_ID"></youtube-embed>
VIDEO_ID is the 11-character YouTube identifier (the v= parameter from a youtube.com/watch?v=... URL, or the path from a youtu.be/... URL). Do NOT manually set a thumbnail attribute. The blog has a localize-images build task that discovers <youtube-embed> elements, downloads the YouTube thumbnail, saves it into the post's page bundle with a content-addressed filename, and rewrites the markup to add thumbnail="<hash>.jpg". Older posts in the archive already show this rewritten form — that's the build pipeline's output, not what the author types.
When to embed (heuristic — be selective, embeds are heavy):
Pocket Casts — Podcast listening signal. Miscellanea bullets by default; dedicated section only when a specific episode or show drove the week's thinking.
The composer's job is to identify what actually mattered this week, not to give every source equal column inches. A week with no GitHub activity but heavy Mastodon discussion produces a post dominated by Mastodon. A week of deep work on one project produces a GitHub-thematic post. The combined.md file is raw signal; the post is curated narrative.
Before finalizing, review the composed weeknotes and make light revisions:
Structure check:
Prose polish:
Content verification:
<image-gallery>)<!--more-->Final touches:
Create the Jekyll blog post file with:
---
title: "{descriptive lead} (Week {week})"
date: YYYY-MM-DD
tags:
- weeknotes
- [contextual-tag-1]
- [contextual-tag-2]
- [contextual-tag-3]
layout: post
---
Important — Title Format: The title is the post's discovery surface. On feed readers and aggregators (Bubbles, RSS, link blogs), the title is often all a reader sees, so a bare {year} Week {week} tells them nothing about a post that may contain a genuinely good story. Lead the title with what the week was actually about, then append the week marker so the weeknotes cadence stays legible.
The slug and URL are decoupled from the title: the output directory is always …/{YYYY-MM-DD}-w{WW}/ (see "Computing the output path"), which is what fixes ordering, archive, and permalinks. The title: field is free prose and changing it never moves the URL. So a descriptive title costs nothing structurally.
{descriptive lead} (Week {week}) — e.g. "A masochist and his MacBook (Week 26)" or "starnet ate the month (Week 25)". Derive the lead from the post's dominant section — the thread that got the most column inches — phrased in the author's voice (reusing a strong section heading is encouraged). Keep it short; one clause, not a summary of every topic. Harley's bar is low and correct: just give the reader some idea what the post is about.{descriptive lead} (Catching up: {date range}) — e.g. "Cat drama and a month of starnet (Catching up: May 29 – June 18)". The plain {year} Week {week} form is doubly wrong here: opaque and it implies a single ISO week when the window spans several.If the week genuinely had no single dominant thread (a true grab-bag), it's acceptable to fall back to {year} Week {week}, but treat that as the exception, not the default — most weeks have a lead.
In all cases: do NOT use a "Weeknotes:" prefix — the weeknotes tag already categorizes the post.
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:
ai, javascript, golang, docker, apisside-projects, open-source, blogginglearning, refactoring, debuggingproductivity, tools, workflowsAnalyze the composed content and choose tags that genuinely reflect what the post is about.
Catchup-window tags: Even for posts covering multiple weeks (window > 7 days), keep weeknotes as the first tag and do NOT add monthly, catchup, multi-week, or similar meta-tags. Catchup posts are still weeknotes — same voice, same archive, same RSS feed. The meta-tag would partition the archive arbitrarily.
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.
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
Computing the output path:
The path is content/posts/{YYYY}/{YYYY-MM-DD}-w{WW}/index.md where:
{YYYY} is the calendar year of the publication date{YYYY-MM-DD} is the publication date in ISO format{WW} is the ISO week number for the publication date, zero-padded to two digits (e.g. w03, w42)You can compute this two ways:
Inline (path-independent): Use the bash tool with a one-liner. Today's path:
python3 -c "from datetime import datetime as d; t=d.now(); s=t.strftime('%Y-%m-%d'); w=t.isocalendar()[1]; print(f'content/posts/{t.year}/{s}-w{w:02d}/index.md')"
Or for a specific date:
python3 -c "from datetime import datetime as d; t=d.strptime('2026-05-20','%Y-%m-%d'); s=t.strftime('%Y-%m-%d'); w=t.isocalendar()[1]; print(f'content/posts/{t.year}/{s}-w{w:02d}/index.md')"
Via the helper script: The skill includes scripts/calculate-week.py (located inside this skill's directory, not in the blog directory). If you know the skill's install path, you can invoke it with --json to get all path components at once:
/path/to/weeknotes-composer/scripts/calculate-week.py --date 2026-05-20 --json
Output includes slug, directory, filename, week_marker, and title fields. Use week_marker (e.g. (Week 21)) as the suffix on your content-derived title; title is only the bare {year} Week {week} fallback for grab-bag weeks (see the Title Format guidance in Step 7).
Use whichever method is more convenient. The inline form works from any directory; the script gives the week marker and the fallback title as a bonus.
The path uses today's date (not the start date) for the publication date. Examples:
content/posts/2025/2025-04-18-w16/index.md (Week 16, published April 18, 2025)content/posts/2025/2025-11-13-w46/index.md (Week 46, published November 13, 2025)Why use a directory structure? Using a directory (page bundle) instead of a flat file provides several benefits:
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.
Review the images already embedded in the post and select one to use as the cover thumbnail:
Analyze embedded images:
Selection criteria:
Priority order:
Add to frontmatter:
thumbnail: property---
title: "A masochist and his MacBook (Week 26)"
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:
thumbnail: property for nowThe skill's only config is an optional style reference URL:
{
"weeknotes_archive": "https://blog.example.com/tags/weeknotes/"
}
Config path: ~/.claude/config/weeknotes-composer/config.json
This file has one field and may be null. It does NOT contain API tokens, per-source credentials, or any other settings. Those live in me-to-markdown's shared env file at $XDG_CONFIG_HOME/me-to-markdown/env (default: ~/.config/me-to-markdown/env).
If the config file is absent, the skill prompts the user once and creates it — either with the provided URL or "weeknotes_archive": null if the user declines.
me-to-markdown: command not found — Install per the orchestrator's README: https://github.com/lmorchard/me-to-markdown. Then run me-to-markdown install to populate the per-source binaries and me-to-markdown auth to authorize each source.
One or more sources missing from combined.md — Run me-to-markdown list to see which binaries resolve. Any showing missing need to be installed: me-to-markdown install (all tools) or me-to-markdown install <slug> (one at a time).
A source's section in combined.md contains an error block — The most common cause is expired auth. Fix: me-to-markdown auth walks each tool interactively; skip ones that are already working. Re-run me-to-markdown export once auth is refreshed.
Empty content despite the date range covering activity — Verify the env file is loaded correctly. Quick single-source smoke test: me-to-markdown export --since 24h --include mastodon -o /tmp/test.md. If that returns content, the issue is per-tool auth for the failing sources.
scripts/calculate-week.py — ISO week number + output filename helper. Run with --json to get machine-readable directory and filename fields.~/.claude/config/weeknotes-composer/config.json — Optional skill config. Contains only the weeknotes_archive style reference URL (or null).~/.claude/cache/weeknotes-composer/data/latest/combined.md — Most recent fetched signal from me-to-markdown export. Ephemeral; safe to delete.~/.claude/cache/weeknotes-composer/data/latest/youtube-transcripts.md — Optional companion file from youtube-to-markdown transcripts render. Contains prose bodies for liked videos with cached transcripts; present only when the user has run youtube-to-markdown transcripts fetch for the window. Ephemeral; safe to delete.Compose daily blog posts in a multi-post single-file format from multiple data sources including Mastodon and Linkding. Use this skill when the user requests to create, update, or revise daily blog posts throughout the day.
Build Go-based command-line tools following established patterns with Cobra CLI framework, Viper configuration, SQLite database, and automated GitHub Actions workflows for releases. Use when creating new Go CLI projects or adding features to existing ones that follow the Cobra/Viper/SQLite stack.
Use when Les asks what he was up to yesterday, wants a standup report, or needs to reconstruct recent work from his Claude Code sessions — surveys transcripts in ~/.claude/projects and reports what actually shipped.
Use when working through a multi-phase feature, bugfix, or GitHub issue that warrants tracked spec/plan/notes artifacts. Triggers: /dev-session command, /dev-session phase names (start/brainstorm/plan/execute/pr/retro/express), starting a new feature branch, picking up a GitHub issue.
Use when Les asks to log, capture, or journal what was worked on this session, jot a quick note or TIL down for later, or flag something as a blog candidate — anything destined for his daily Obsidian journal.
Use when a brainstorming or design question would be clearer shown than told — mockups, wireframes, layout comparisons, architecture diagrams, side-by-side visual options — and Les has Television running. A display-only alternative to the superpowers brainstorming browser server: renders visuals as Television artifacts instead of spinning up a separate web server and tab.