mirror of
https://github.com/tiennm99/blog.git
synced 2026-10-11 03:13:10 +00:00
tiennm99
baab3d443a
Switches every call site to `node scripts/newsletter` and, in the same pass, fixes three structural problems in the skill layer. The seven subcommands were spelled out in five files; they are now enumerated once in docs/newsletter/engine-commands.md, and every other mention is a link except where a skill inlines the one or two commands it actually invokes. The shared post mechanics move out of mt-add-url's directory into docs/newsletter/, so no skill owns another skill's documentation and both runtimes reach it by a repository-relative path. The Codex adapters become symlinks to their canonical counterparts, which removes the parallel frontmatter that could drift. Two skills are renamed for a uniform mt-<verb>-<object> scheme: mt-add-post becomes mt-add-article, since it adds an article to a post, and mt-webfetch becomes mt-fetch-url. The other four already conformed. Note that $mt-add-post and mt-webfetch no longer resolve; no alias directories are left behind, because two names for one skill is the duplication this change removes. Trigger wording in the frontmatter descriptions is left alone apart from the renamed tokens and the corrected fetch-tier summary: those strings are how the runtimes decide whether to invoke a skill. Setup documentation now states the npm ci prerequisite. The engine has dependencies, so unlike its predecessor it does not run on a bare clone.
94 lines
4.1 KiB
Markdown
94 lines
4.1 KiB
Markdown
# 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
|
|
|
|
```bash
|
|
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
|
|
|
|
The portable newsletter engine lives in **`scripts/newsletter/`** (Node ESM, one
|
|
module per subcommand) and is invoked from the repo root:
|
|
|
|
```bash
|
|
node scripts/newsletter <command> [args]
|
|
```
|
|
|
|
The seven subcommands, their arguments, output shapes and exit codes are
|
|
documented once in **[docs/newsletter/engine-commands.md](docs/newsletter/engine-commands.md)**.
|
|
|
|
The engine has npm dependencies, so a fresh clone needs `npm ci` from the repo
|
|
root once before any skill will run.
|
|
|
|
The engine is shared by all three tools — no tool-specific copies.
|
|
|
|
---
|
|
|
|
## Newsletter Workflow Routing
|
|
|
|
The newsletter workflow adds URLs (articles, YouTube videos, images) to the target newsletter post — today's post, or an earlier unpublished draft the user pins for the session — 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-article` — 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-fetch-url` — fallback web fetch chain (local defuddle, the defuddle.md proxy, then a reader proxy); use only when built-in WebFetch is blocked
|
|
- **Codex** — discovers the repository-scoped adapters in `.agents/skills/`. Ask it to add a URL for implicit routing or invoke `$mt-add-url` explicitly.
|
|
|
|
`mt-add-url` dispatches `article` / `youtube` / `image`; other types (direct video files, documents, unknown) prompt the user to add or extend a handler.
|
|
|
|
Canonical skill implementations live in `.claude/skills/`; `.agents/skills/` symlinks to them so there is only ever one copy to edit.
|
|
|
|
### Using Codex
|
|
|
|
Codex automatically discovers checked-in skills from `.agents/skills/`. No install or copy step is required. Start Codex at the repository root, then either describe the task normally or explicitly mention a skill:
|
|
|
|
- `$mt-add-url <url>` — classify and dispatch one or more URLs
|
|
- `$mt-add-article <url>` — add an article directly
|
|
- `$mt-add-video <url>` — add a YouTube video directly
|
|
- `$mt-add-image <url>` — add an image directly
|
|
- `$mt-add-tags [post]` — add or update tags
|
|
- `$mt-fetch-url <url>` — fallback after the built-in fetch fails
|
|
|
|
Codex detects skill changes automatically; restart Codex if an update does not appear.
|
|
|
|
---
|
|
|
|
## 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.
|