Article Writing

Use this skill for journal work on Robin's Eleventy site: ideation, outlines, drafts, rewrites, reviews, and post-file creation.

Source of truth

Before writing or editing in the site repo, read these live files when available:

• TONE.md for current voice, structure, mechanics, formatting, and things to avoid.
• AGENTS.md for post file conventions, front matter, build commands, and repo gotchas.

If either file is missing or the task happens outside the repo, read the bundled references:

• references/voice.md for the distilled voice guide.
• references/site.md for journal file and verification conventions.

Prefer the live project files over bundled references when they disagree.

Workflow

1. Clarify the article type from the request: product/library introduction, technical walkthrough, reflective lessons-learned piece, or copy review.
2. Gather the technical facts needed to make the post defensible. Verify current facts from official sources or the local codebase when claims may have changed.
3. Choose the opening frame:
   • Use second person for product/library posts: open on a concrete problem the reader has.
   • Use first person for reflective posts: open on the path Robin took through the problem.
4. Build the post around problem -> solution -> proof -> reflection, but treat that as an arc rather than a repeated section template.
5. Use real examples. Code should be complete enough to run or understand, fenced with the correct language, and followed by a short explanation of the interesting result.
6. Sprinkle in reference links where they help the reader verify or continue. Prefer official docs, source repositories, specs, package docs, MDN, HexDocs, Rails guides/API docs, or local project pages. Link the first meaningful mention of a library, API, method, browser feature, spec, or package. Do not link every repeated mention, and do not add a references section unless the post is explicitly research-heavy.
7. Do a structural rhythm pass after the factual/editing pass. Check whether paragraphs keep using the same claim -> explanation -> tidy closer shape. If they do, vary the form: combine paragraphs, add a short standalone beat, use bullets for example runs, or start from the concrete case instead of the abstraction.
8. Keep copy warm, direct, and practical. Preserve existing user copy unless asked to rewrite it.
9. If creating a post file, use post/YYYY-MM-DD-title-slug.md with only title and description in front matter unless the user asks for something else.
10. Verify with npm run build when a file is changed. Use npm start only when rendered-page inspection is needed.

Writing Checklist

• Open on a felt problem, not the tool name.
• Get to the useful part quickly.
• Admit the messy or naive first attempt when it helps the reader trust the conclusion.
• Prefer "you", "we", and "let's"; use contractions.
• Back claims with working examples, output, or concrete behavior.
• Use ## headings in sentence case.
• Use bold lead-in bullets for benefits and use cases.
• Link to the project repo or official docs near first introduction and again in a short getting-started close when relevant.
• Add light inline reference links for APIs and concepts a reader may want to inspect. Good anchors are names like useEffect, URLSearchParams, Ecto.Changeset, Rails.application.credentials, Jason.decode!/2, and Content Security Policy.
• Keep reference links sparse. One useful link at the first meaningful mention is better than linking every occurrence.
• End on the practical lesson and, for complete posts, invite replies.
• Read the draft aloud for cadence. Adjacent paragraphs should not all begin the same way, run the same length, or end with the same kind of punchline.

Avoid

• Corporate filler, hype words, passive padding, and over-explaining the roadmap of the post.
• Walls of prose; split paragraphs over roughly four sentences.
• Repeating paragraph architecture: claim, explanation, neat closer; claim, explanation, neat closer.
• Defaulting to em dashes, tricolon endings, or "no more X, no more Y" benefit slogans just because older posts used them.
• Link farms, generic "read more here" links, or references sections on ordinary posts.
• Repeating signature phrases too often.
• Raw color values or template styling changes when the task is article copy.
• Editing generated data under _data/strava.json or _data/webmentions/.