mirror of
https://github.com/tiennm99/blog.git
synced 2026-10-11 12:09:02 +00:00
96 lines
4.3 KiB
Markdown
96 lines
4.3 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 eight 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-rewrite-newsletter` — rewrite existing newsletter summaries with a newer model, keeping handwritten lines and stamping a rewrite note
|
|
- `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-rewrite-newsletter [model] [scope]` — rewrite existing newsletters with a newer model
|
|
- `$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.
|