article-creator

name	article-creator
description	(🥑) Expert guide for authoring, building, testing, and publishing technical articles to ricc.rocks and Medium.
version	1
tags	devrel, article, publishing, ricc.rocks, medium

🥑 Article Creator & Publisher Workflow

This skill guides the preparation, compilation, validation, and post-publication steps for articles targeted to ricc.rocks and Medium.

[!NOTE] For Riccardo, new articles and drafts should always be initialized and managed under the root articles directory: work/articles/ (which is the parent folder relative to individual article projects).

📐 Authoring & Pipeline Rules

1. Source of Truth: Always edit ARTICLE.md only. Never manually edit files inside the generated out/ or ricc.rocks/ directories, as they are overwritten by build.py.
2. Image Notation: Write standard Markdown images: ![Caption](local-image.png). The build script translates these to Hugo image shortcodes for ricc.rocks and absolute URLs for Medium.
3. Cross-Article Links: Write cross-article links using their full https://ricc.rocks/... absolute URLs in ARTICLE.md. The build script translates them to root-relative paths for ricc.rocks while preserving absolute links for Medium.

🚀 Publishing Checklist & Steps

Step 1: Pre-Publishing Compilation & Review

Before finalizing, compile the article assets and check for spelling/readability:

1. Readability & Slop Check: Use Daniela's awesome speedgrapher MCP server to lint and analyze the article. The MCP server provides the following tools:
   • fog: Calculates the Gunning Fog readability index (Optimal target: 12.0 - 15.0).
   • slop: Analyzes text for common AI clichés, tropes, and structural patterns (Target: < 40%).
   • vale: Performs static style linting against project guidelines.
2. Spelling Whitelist: Ensure any technical terms, names, or jargon are whitelisted in the local speedgrapher.json config.
3. Run Build: Compile Dot diagrams and target formats:

   just build
   

Step 2: Local Staging & Testing

Verify that generated HTML builds correctly and links are functional:

1. Run the tests to check for broken links and metadata errors:

   just test-ricc-rocks-articles
   

2. Inspect output folder contents:
   • out/ricc.rocks/index.md (Hugo compatible Markdown output for ricc.rocks).
   • out/medium/index.html (Compiled HTML output ready for Medium).
   • out/apps-portfolio/ (Copy of index & assets for the portfolio).

Step 3: Medium Manual Upload (One-time)

1. Open the Medium editor and paste the content from out/medium/index.html.
2. CRITICAL SEO STEP: Open Medium Story Settings -> Advanced Settings -> Canonical URL.
   • Set the Canonical URL to: https://ricc.rocks/en/posts/technology/<SLUG>/
3. Publish the article on Medium.
4. Copy the final published Medium URL.

Step 4: Post-Publishing Canonical Sync

1. Update the frontmatter of ARTICLE.md by setting canonicalURL: <Medium_URL>.
2. Re-run just build. This auto-appends the italic Originally published at... footer to the ricc.rocks output file.
3. Commit and push to ricc.rocks repository to trigger deployment.

Step 5: Portfolio & Social Promotion

1. Run the add-to-portfolio-app skill to register this new post in ~/git/vibecoding/apps-portfolio.
2. Update the my-sessions-and-bio repository listings.
3. Draft and schedule social announcements on LinkedIn, Bluesky, and Twitter using Buffer.