Way Into AI - Logging Skill

Way Into AI - Logging Skill

This skill documents how to create log entries for the Way Into AI repository.

Quick start: Read the sections below when adding entries. For workspace instructions, see AGENTS.md.

Repository Structure

wayintoai/
├── logs/           # Daily logs with wiki links
│   └── YYYY-MM-DD.md
├── ref/            # Detailed reference entries
│   └── topic-name.md
├── links/          # Quick link collections
├── backlog/        # Items to process
└── SKILL.md        # This file

Log Entry Process

1. Determine Entry Type

Full reference entry:

  • Use when topic warrants detailed documentation
  • Include frontmatter, links, screenshots, full context
  • File location: ref/topic-name.md

Simple log entry:

  • Use for quick notes, links without deep dive
  • Just bullet point in daily log
  • No separate ref file

2. Creating Reference Entries

Default: Keep it concise

  • Brief description + screenshot is often enough
  • Add detail only when specifically requested or clearly warranted
  • Avoid massive essays unless the topic demands it

File naming:

  • Use descriptive, URL-friendly names
  • Examples: msgvault.md, inference-sh.md, pi.dev.md
  • Hyphens for multi-word names

Frontmatter (required):

---
created: YYYY-MM-DD  # Date the entry was added to the repo (required)
author: Author Name (if applicable)
tags: [tag1, tag2, tag3]
---

Important: The created field should always be set to the date the entry was added to the repository in YYYY-MM-DD format, not the original publication date of the content.

Minimal content structure (default):

  1. Title (H1) - Project/tool name
  2. Tagline/Description - One-sentence summary
  3. Screenshot (if web-based) - Using screenshotit.app/URL — place immediately after the tagline, before Links
  4. Links section - Website, GitHub, docs, announcement
  5. Overview - Brief what/why (2-3 paragraphs)
  6. Key Features (optional) - If notable
  7. Use Cases (optional) - If helpful

Comprehensive structure (when requested or clearly warranted):

  • Add: Why It Exists / Why Interesting
  • Add: Technical Details (stack, architecture, specs)
  • Add: Detailed sections on features, philosophy, comparisons
  • Add: Related topics, commentary, significance

YouTube videos: put the bare YouTube URL on its own line; Flowershow renders it as an embed. No iframe or screenshot needed.

Screenshots (REQUIRED for web content):

  • ALWAYS include for web-based tools, articles, or any public URL — except tweets
  • Skip tweets (x.com / twitter.com): X blocks screenshotit.app, which returns an "Access to x.com was denied" 403 image. Quote the tweet text instead.
  • Use screenshotit.app: https://screenshotit.app/{url}
  • Format: ![Description](https://screenshotit.app/https://example.com/)
  • Place immediately after title/tagline, BEFORE the Links section
  • Service auto-caches, provides stable URLs
  • Advanced options: @full, @mobile, @refresh
  • Examples:
    • Website: ![Tool](https://screenshotit.app/https://dmux.ai/)
    • Article: ![Article](https://screenshotit.app/https://anthropic.com/news/article)

3. Updating Existing Entries

When to add updates:

  • User provides feedback after trying a tool/product
  • New significant features or developments
  • Changed assessment or experience report
  • Corrections or clarifications

Format for user feedback/experience:

> **User Experience Note (YYYY-MM-DD):**  
> [User's feedback or experience report] — [Name]

Placement:

  • Add near the top, after "What Is It?" or similar intro section
  • Before detailed features/documentation
  • Use blockquote format with bold heading for visibility

Example:

> **User Experience Note (2026-02-26):**  
> After playing with this for a few weeks, haven't found it so satisfying yet. Maybe haven't got the knack. — Rufus Pollock

Git workflow for updates:

cd ~/src/datopian/wayintoai
git add ref/updated-file.md
git commit -m "Update: [item name] - add user experience note"
git push

When NOT to update:

  • Minor typos or formatting fixes (batch these)
  • Speculative changes without verification
  • Opinions that contradict documented facts (add as separate note instead)

4. Daily Log Entries

File location: logs/YYYY-MM-DD.md

Format:

# YYYY-MM-DD

## [[ref-file-name]] - Short Title

Brief description with key details. Maximum 1-2 sentences.

Wiki links:

  • Use Obsidian-style: [[filename]] (without .md)
  • Links resolve to ref/ entries
  • Keep description to 1-2 sentences maximum — concise but captures the essence

Featuring and newsletter selection

Record editorial selection on the canonical post or reference entry:

featured: true
newsletter: standalone
  • featured: true means selected for homepage coverage. The homepage is manually curated: also add its link to the existing post list in index.md. Metadata alone does not change the site.
  • newsletter: weekly means a candidate for the weekly roundup.
  • newsletter: standalone means strong enough to consider for a dedicated email; it can still be included in the weekly roundup if no dedicated email is sent.
  • Omit newsletter when there is no selection. These values record editorial intent, not approval to send or evidence of delivery.

Keep the selection on one canonical item to avoid counting both a reference entry and its write-up. In a daily log, point to the selected item using repository-relative paths:

newsletter_candidates:
  - posts/2026-09-18-typesafe-jev-system-one.md

For a log-only item, add a small reference entry when selecting it for newsletter coverage, put the selection metadata there, and link it from the log. This keeps selection at item level when a day contains several entries. Log prose remains limited to 1–2 sentences per entry.

During newsletter preparation, find candidates with rg -n '^newsletter: (weekly|standalone)$' posts ref, then read each item. After an item is actually emailed, add newsletter_sent: YYYY-MM-DD and, when available, newsletter_url to the canonical item; skip sent items by default in subsequent reviews. Selection and delivery are manual; no email automation is implied. The infrastructure changelog's promote flag remains a separate convention.

5. Git Workflow

Add files:

cd ~/src/datopian/wayintoai
git add logs/YYYY-MM-DD.md ref/new-entry.md

Commit message format:

Add [topic] reference and YYYY-MM-DD log

- Created ref/topic.md: detailed reference for [description]
- Added logs/YYYY-MM-DD.md: daily log with [[topic]] wiki link
- [Key details about the entry]
- [Any notable features/context]

Beads sync: git push also pushes the Beads Dolt data (refs/dolt/data) via .beads/hooks/pre-push. If the hook reports a failure, run bd dolt push by hand.

Push — auto-push on commit (no wait):

cd ~/src/datopian/wayintoai
git push
  • GitHub PAT configured in remote URL
  • Push immediately on commit — repo auto-pushes in the same step, no waiting for user.
cd ~/src/datopian/wayintoai
git push
  • GitHub PAT configured in remote URL
  • Wait for user to request push - don't push automatically after commit

Examples

Full Reference Entry (msgvault)

Created files:

  • ref/msgvault.md - Full reference
  • Updated logs/2026-02-04.md - Added wiki link

Features:

  • Frontmatter with created date, author, tags
  • Links to GitHub, announcement tweet
  • Overview, key features, why interesting
  • Technical details, context

Log entry:

## [[msgvault]] - Local-first Email Archive

Wes McKinney (pandas/Arrow creator) built msgvault: local-first email archive 
powered by DuckDB with MCP server for AI agent integration. Handles 20 years 
of Gmail (2M emails, 150K attachments) in a single Go binary.

Full Reference with Screenshot (inference.sh)

Created files:

  • ref/inference-sh.md
  • Updated logs/2026-02-04.md

Special:

  • Included screenshot via screenshotit.app
  • Hyphenated filename for domain name

Screenshot:

![inference.sh homepage](https://screenshotit.app/https://inference.sh/)

Domain/URL in Filename (pi.dev)

Filename: pi.dev.md

  • Preserves dot for domain names
  • User explicitly requested this format

Guidelines

Post authors: Every post in posts/ (except posts/index.md) needs authors in its frontmatter. For posts by Rufus Pollock, use authors: [rufus-pollock]. Flowershow links this to authors/rufus-pollock.md and displays its title and avatar in the post header. Keep profile details and the Gravatar URL on that shared author page. For another author, create a separate profile page and use its filename stem in authors; the singular author field used by reference entries does not configure Flowershow post bylines.

Conciseness:

  • Log entries: 1-2 sentences capturing essence
  • Reference entries: comprehensive but organized
  • Use headers to break up long content

Paragraphs, numbers and charts (posts and refs): follow docs/numbers-and-charts.md.

  • Paragraphs of at most about 60 words; break where the thought turns.
  • Three or more comparable figures go in a small Markdown table with a source caption, not a sentence.
  • Where it shows the point faster, add a small house-style SVG chart in assets/ next to the table.

Links:

  • Always include primary website
  • GitHub if open source
  • Announcement tweet/blog post if relevant
  • Related documentation

Tags:

  • Be specific and useful for search
  • Include: technology stack, category, key features
  • Examples: [ai-agents, platform, durable-execution]

Images the user supplies (pasted into chat or as files): save to assets/<slug>.png (a pasted image is only on the clipboard; see the weekly-roundup skill for the osascript one-liner), embed near the top of the ref with descriptive alt text and a one-line italic caption.

Screenshots:

  • Only for web-based tools/platforms
  • Use screenshotit.app for automatic caching
  • Place at the TOP of the ref file — after title/tagline, before Links and all other sections

Tools

screenshotit.app:

Obsidian wiki links:

  • [[filename]] - links to ref/filename.md
  • No need for path or extension
  • Works in Obsidian and compatible Markdown renderers

Workflow Checklist

  • Decide: full reference or simple log entry?
  • If reference: create ref/topic-name.md with frontmatter
  • If reference: include links, overview, features
  • If web tool: add screenshot via screenshotit.app
  • Paragraphs ≤ ~60 words; 3+ comparable figures in a table (chart if it helps)
  • Update logs/YYYY-MM-DD.md with wiki link entry
  • Git add both files
  • Git commit with descriptive message
  • Wait for user to request push (don't auto-push)

Notes

  • Filename format can vary (hyphens, dots) based on topic
  • User may specify preferred filename format
  • Always use Obsidian wiki link syntax in logs
  • Screenshots are optional but recommended for web tools
  • Maintain consistent frontmatter format
Edit this page

Links to this page:

  1. Way Into AI