AGENTS.md

Canonical instructions for AI coding tools (Claude Code, OpenCode, Codex) working with this Hugo blog. This is the single source of truth; CLAUDE.md imports it.

Project Info

Type: Hugo static site with Vietnamese tech content
Theme: hugo-theme-stack
Post content language: Vietnamese (with common English tech words)
User communication: English by default; use another language only when the user explicitly requests it
Timezone: Asia/Ho_Chi_Minh (UTC+7)

Vietnamese language requirements apply only to prose written into Hugo posts, including summaries. Preserve article titles and image labels in their original source language, wording, capitalization, and punctuation; translate them only when the user explicitly asks. Keep questions, status updates, reports, and final responses in English unless the user asks for another language.

Directory Structure

content/post/
└── YYYY/
    └── MM/
        └── DD/
            └── index.md

Starting Local Development Server

hugo server -D

The site will be available at http://localhost:1313

Options:

-D or --buildDrafts: Include draft content
-F or --buildFuture: Include future-dated content
--disableFastRender: Full re-render on all changes

Shared Engine

All portable newsletter scripts live in scripts/newsletter/ and are invoked from the repo root with plain Node (stdlib only, no deps):

node scripts/newsletter/add-url.js "<url>"              # classify + dedup a URL → JSON route
node scripts/newsletter/find-newsletter-number.js       # next newsletter number
node scripts/newsletter/list-existing-tags.js           # existing tag frequencies
node scripts/newsletter/detect-image-source.js "<url>"  # detect Substack image + uuid
node scripts/newsletter/find-substack-post.js --uuid <uuid>
node scripts/newsletter/fetch-via-defuddle.js "<url>"   # fallback fetch (defuddle proxy)

These are shared by all three tools — no tool-specific copies.

The newsletter workflow adds URLs (articles, YouTube videos, images) to today's newsletter post and manages tags. How it surfaces depends on the tool:

Claude Code / OpenCode — invoke skills (both read .claude/skills/<name>/SKILL.md natively):
- mt-add-url — meta dispatcher: classifies each URL, auto-invokes the right handler. Default entry for adding URLs.
- mt-add-post — article/blog URL → newsletter main content
- mt-add-video — YouTube link → Bonus → Videos
- mt-add-image — image → Bonus → Images (labels Substack images via source-post lookup)
- mt-add-tags — add/update tags in post frontmatter
- mt-webfetch — fallback web fetcher (defuddle proxy); use only when built-in WebFetch is blocked
Codex — no skill auto-dispatch. Run /prompts:mt-add-url <url> (installed prompts; see "Using Codex" below), or read this file and call the scripts/newsletter/*.js scripts directly.

mt-add-url dispatches article / youtube / image; other types (direct video files, documents, unknown) prompt the user to add or extend a handler.

Skill implementations live in .claude/skills/.

Using Codex

Codex has no skill auto-dispatch and loads custom prompts only from ~/.codex/prompts/. Install the repo's prompt sources once, then invoke them as slash commands:

Linux/macOS: bash codex/install.sh
Windows: pwsh codex/install.ps1 (or powershell codex/install.ps1)

Then in a Codex session at the repo root: /prompts:mt-add-url <url> (also /prompts:mt-add-post, mt-add-video, mt-add-image, mt-add-tags, mt-webfetch).

The installer copies prompts (not symlinks — Windows symlinks need admin/Developer Mode). Re-run it after editing any codex/prompts/*.md so ~/.codex/prompts/ re-syncs. Even without installing, Codex can read this file and call the scripts/newsletter/*.js scripts directly.

Git Workflow Rules

Before any git commit, check all staged content/post/*/index.md files for minimal tags. If any have only ["AI-Assisted"] or empty tags, run the mt-add-tags workflow on them first before committing.

4.2 KiB Raw Blame History