mirror of
https://github.com/JimLiu/baoyu-skills.git
synced 2026-08-01 06:39:49 +08:00
[codex] Refactor skills into focused references (#135)
* docs: add runtime-neutral User Input Tools convention across skills Introduce docs/user-input-tools.md as the author-side canonical source and inline the tool-selection rule into every SKILL.md that prompts the user. Also add Skill Self-Containment and User Input Tools sections to CLAUDE.md and the copy-verbatim template to docs/creating-skills.md, so skills stay portable across Claude Code, Codex, Hermes, and other runtimes. * feat: runtime-neutral image generation convention across skills - Introduce inline `## Image Generation Tools` rule in every rendering SKILL.md so skills delegate backend choice instead of hard-coding one; author-side canonical copy lives in docs/image-generation-tools.md. - Add `## Reference Images` support (`--ref`, frontmatter `references:` with direct/style/palette usage) to all seven image-rendering skills. - Move build-batch.ts (with ref propagation into batch JSON) from baoyu-article-illustrator to baoyu-imagine so non-backend skills don't own backend-specific scripts; update baoyu-image-gen stub in sync and relax the CLAUDE.md deprecation note accordingly. * refactor: slim heavy SKILL.md files and move detail to references/ Trim the four largest active skills and move presets, option tables, and confirmation scripts into per-skill references/ so SKILL.md stays focused on the decision flow. - baoyu-slide-deck: 761→258, + styles-gallery.md, confirmation.md - baoyu-image-cards: 657→280, + gallery.md, confirmation.md - baoyu-post-to-wechat: 518→267, + multi-account.md, api-setup.md - baoyu-imagine: 500→230, + providers/, usage-examples.md Also un-deprecate baoyu-image-gen (drop stub warning) so it stays functional alongside baoyu-imagine, and update CLAUDE.md to reflect that both superseded skills are kept in sync rather than stubbed. * refactor: slim four medium SKILL.md files into references/ Continue the P2 pattern on the next tier of skills — move option catalogs, per-provider/adapter detail, and repeated EXTEND.md path boilerplate into their own references so SKILL.md stays focused on the decision flow. - baoyu-comic: 380→297 (art/tone/preset tables → auto-selection.md; Step 7 expanded detail → workflow.md) - baoyu-infographic: 312→207 (layouts/styles/combinations/keywords → gallery.md; ASCII box tables → markdown tables) - baoyu-format-markdown: 376→296 (title + summary generation → title-summary.md; ASCII box tables → markdown tables) - baoyu-url-to-markdown: 334→169 (quality gate + recovery → quality-gate.md; adapters + media download → adapters.md) * chore: sync deprecated skills with their replacements Per project policy, baoyu-xhs-images and baoyu-image-gen are kept functional alongside the active skills they were superseded by. Sync their SKILL.md bodies and references/ to the slimmed baoyu-image-cards and baoyu-imagine versions respectively, so cross-cutting fixes stay consistent. Only the frontmatter (name, description, version, homepage) differs — content is identical. - baoyu-xhs-images: 657→281 (synced with baoyu-image-cards + new confirmation.md, gallery.md) - baoyu-image-gen: 408→231 (synced with baoyu-imagine + new providers/, usage-examples.md) * refactor: collapse EXTEND.md boilerplate into priority tables Replace the dual bash/powershell existence-check blocks and ASCII box art with a single markdown priority table across nine SKILL.md files. The runtime-neutral phrasing removes shell-specific snippets without losing the priority semantics. * fix: address refactor-skills branch review findings - image-gen: restore EXTEND.md paths to baoyu-image-gen (were pointing at baoyu-imagine) and mark descriptions of both deprecated skills as [Deprecated]. - xhs-images: sync neon/warm palettes with image-cards to add the "do not render color names/hex as visible text" safety sentence. - infographic: restore Layout Gallery (21), Style Gallery (21), Recommended Combinations, and Keyword Shortcuts inline (previous refactor split them out but SKILL.md still depended on them), and add the missing references/config/first-time-setup.md + preferences-schema.md. - image-cards / xhs-images / slide-deck / format-markdown: restore the sections that got over-slimmed into references/ (galleries, presets, dimensions, auto-selection, style x layout matrix, title/summary flow) and drop the now-empty shell files. - docs/image-generation-tools.md: note that backend skills themselves (baoyu-imagine, baoyu-image-gen, baoyu-danger-gemini-web) are exempt from the ## Image Generation Tools section requirement. * feat(image-gen): sync Z.AI GLM-Image provider from baoyu-imagine Add Z.AI as a full provider in the deprecated baoyu-image-gen skill so it stays in sync with baoyu-imagine's provider list. - new scripts/providers/zai.ts + zai.test.ts (verbatim port; test factory trimmed to match image-gen's CliArgs shape). - types.ts: "zai" added to Provider union and default_model. - main.ts: rate-limit defaults, provider help text, env var help, --provider validation, loadProviderModule, detectProvider auto-detect chain, getModelForProvider, YAML parser allow-lists. - references/config: Q2e Z.AI model question + zai slot in the preferences schema and batch.provider_limits. Scope is intentionally limited to the Z.AI chain; unrelated drift between image-gen and imagine (OpenAI image-API dialect, aspectRatioSource, imageSizeSource) is left alone. * docs: align inline-convention wording and note backend-skill exemption - docs/user-input-tools.md: fix stale "links here" wording so it matches the inline convention already enforced everywhere else. - CLAUDE.md §Image Generation Tools: inline the backend-skill exemption so readers don't need to cross-reference docs/image-generation-tools.md.
This commit is contained in:
Jim Liu 宝玉
GitHub
@@ -17,6 +17,16 @@ Transforms plain text or markdown into well-structured, reader-friendly markdown
|
||||
|
||||
**Core principle**: Only adjust formatting and fix obvious typos. Never add, delete, or rewrite content.
|
||||
|
||||
## User Input Tools
|
||||
|
||||
When this skill prompts the user, follow this tool-selection rule (priority order):
|
||||
|
||||
1. **Prefer built-in user-input tools** exposed by the current agent runtime — e.g., `AskUserQuestion`, `request_user_input`, `clarify`, `ask_user`, or any equivalent.
|
||||
2. **Fallback**: if no such tool exists, emit a numbered plain-text message and ask the user to reply with the chosen number/answer for each question.
|
||||
3. **Batching**: if the tool supports multiple questions per call, combine all applicable questions into a single call; if only single-question, ask them one at a time in priority order.
|
||||
|
||||
Concrete `AskUserQuestion` references below are examples — substitute the local equivalent in other runtimes.
|
||||
|
||||
## Script Directory
|
||||
|
||||
Scripts in `scripts/` subdirectory. `{baseDir}` = this SKILL.md's directory path. Resolve `${BUN_X}` runtime: if `bun` installed → `bun`; if `npx` available → `npx -y bun`; else suggest installing bun. Replace `{baseDir}` and `${BUN_X}` with actual values.
|
||||
@@ -29,40 +39,17 @@ Scripts in `scripts/` subdirectory. `{baseDir}` = this SKILL.md's directory path
|
||||
|
||||
## Preferences (EXTEND.md)
|
||||
|
||||
Check EXTEND.md existence (priority order):
|
||||
Check EXTEND.md in priority order — the first one found wins:
|
||||
|
||||
```bash
|
||||
# macOS, Linux, WSL, Git Bash
|
||||
test -f .baoyu-skills/baoyu-format-markdown/EXTEND.md && echo "project"
|
||||
test -f "${XDG_CONFIG_HOME:-$HOME/.config}/baoyu-skills/baoyu-format-markdown/EXTEND.md" && echo "xdg"
|
||||
test -f "$HOME/.baoyu-skills/baoyu-format-markdown/EXTEND.md" && echo "user"
|
||||
```
|
||||
| Priority | Path | Scope |
|
||||
|----------|------|-------|
|
||||
| 1 | `.baoyu-skills/baoyu-format-markdown/EXTEND.md` | Project |
|
||||
| 2 | `${XDG_CONFIG_HOME:-$HOME/.config}/baoyu-skills/baoyu-format-markdown/EXTEND.md` | XDG |
|
||||
| 3 | `$HOME/.baoyu-skills/baoyu-format-markdown/EXTEND.md` | User home |
|
||||
|
||||
```powershell
|
||||
# PowerShell (Windows)
|
||||
if (Test-Path .baoyu-skills/baoyu-format-markdown/EXTEND.md) { "project" }
|
||||
$xdg = if ($env:XDG_CONFIG_HOME) { $env:XDG_CONFIG_HOME } else { "$HOME/.config" }
|
||||
if (Test-Path "$xdg/baoyu-skills/baoyu-format-markdown/EXTEND.md") { "xdg" }
|
||||
if (Test-Path "$HOME/.baoyu-skills/baoyu-format-markdown/EXTEND.md") { "user" }
|
||||
```
|
||||
If none found, use defaults — no first-time setup required for this skill.
|
||||
|
||||
┌──────────────────────────────────────────────────────────┬───────────────────┐
|
||||
│ Path │ Location │
|
||||
├──────────────────────────────────────────────────────────┼───────────────────┤
|
||||
│ .baoyu-skills/baoyu-format-markdown/EXTEND.md │ Project directory │
|
||||
├──────────────────────────────────────────────────────────┼───────────────────┤
|
||||
│ $HOME/.baoyu-skills/baoyu-format-markdown/EXTEND.md │ User home │
|
||||
└──────────────────────────────────────────────────────────┴───────────────────┘
|
||||
|
||||
┌───────────┬───────────────────────────────────────────────────────────────────────────┐
|
||||
│ Result │ Action │
|
||||
├───────────┼───────────────────────────────────────────────────────────────────────────┤
|
||||
│ Found │ Read, parse, apply settings │
|
||||
├───────────┼───────────────────────────────────────────────────────────────────────────┤
|
||||
│ Not found │ Use defaults │
|
||||
└───────────┴───────────────────────────────────────────────────────────────────────────┘
|
||||
|
||||
**EXTEND.md Supports**:
|
||||
**EXTEND.md supports**:
|
||||
|
||||
| Setting | Values | Default | Description |
|
||||
|---------|--------|---------|-------------|
|
||||
@@ -178,9 +165,9 @@ Check for YAML frontmatter (`---` block). Create if missing.
|
||||
| `description` | Longer descriptive summary (see **Summary Generation** below) |
|
||||
| `coverImage` | Check if `imgs/cover.png` exists in same directory; if so, use relative path |
|
||||
|
||||
**Title Generation:**
|
||||
#### Title Generation
|
||||
|
||||
Whether or not a title already exists, always run the title optimization flow (unless `auto_select_title` is set).
|
||||
Whether or not a title already exists, run the title optimization flow unless `auto_select_title` is set.
|
||||
|
||||
**Preparation** — read the full text and extract:
|
||||
- Core argument (one sentence: "what is this article about?")
|
||||
@@ -188,14 +175,14 @@ Whether or not a title already exists, always run the title optimization flow (u
|
||||
- Reader pain point or curiosity trigger
|
||||
- Most memorable metaphor or golden quote
|
||||
|
||||
**Generate titles** using formulas from `references/title-formulas.md`:
|
||||
**Generate candidates** using formulas from `references/title-formulas.md`:
|
||||
|
||||
1. Select the **2-3 best-matching hook formulas** based on the article's content, tone, and structure (see "When to pick each formula" in the reference)
|
||||
2. Generate **1-2 straightforward titles** (descriptive or declarative, no formula — clear and accurate)
|
||||
3. If the user specifies a direction (e.g., "make it suspenseful"), prioritize that direction
|
||||
4. Total: **4-5 candidates**
|
||||
|
||||
Use `AskUserQuestion` to present candidates:
|
||||
Present via `AskUserQuestion`:
|
||||
|
||||
```
|
||||
Pick a title:
|
||||
@@ -209,33 +196,35 @@ Pick a title:
|
||||
Enter number, or type a custom title:
|
||||
```
|
||||
|
||||
Put the strongest hook first and mark it (recommended). See `references/title-formulas.md` for title principles and prohibited patterns.
|
||||
Put the strongest hook first and mark it `(recommended)`. See `references/title-formulas.md` for principles and prohibited patterns.
|
||||
|
||||
If first line is H1, extract to frontmatter and remove from body. If frontmatter already has `title`, include it as context but still generate fresh candidates.
|
||||
If the first line is an H1, extract it to frontmatter and remove it from the body. If frontmatter already has a `title`, include it as context but still generate fresh candidates — the existing title may be weak.
|
||||
|
||||
**Summary Generation:**
|
||||
**Skip behavior**: If `auto_select: true` or `auto_select_title: true`, skip the user prompt and use the top candidate directly.
|
||||
|
||||
Generate two versions directly (no user selection needed), both stored in frontmatter:
|
||||
#### Summary Generation
|
||||
|
||||
Generate two versions directly (no user selection), both stored in frontmatter:
|
||||
|
||||
| Field | Length | Purpose |
|
||||
|-------|--------|---------|
|
||||
| `summary` | 1 sentence, ~50-80 chars | Concise hook — for feeds, social sharing, SEO meta |
|
||||
| `description` | 2-3 sentences, ~100-200 chars | Richer context — for article previews, newsletter blurbs |
|
||||
|
||||
**Principles:**
|
||||
**Principles**:
|
||||
|
||||
- Convey **core value** to the reader, not just the topic
|
||||
- Use concrete details (numbers, outcomes, specific methods) over vague descriptions
|
||||
- `summary` should be punchy and self-contained; `description` can expand with supporting details
|
||||
- If frontmatter already has `summary` or `description`, keep existing and only generate the missing one
|
||||
- If frontmatter already has `summary` or `description`, keep the existing one and only generate the missing field
|
||||
|
||||
**Prohibited patterns**:
|
||||
|
||||
**Prohibited patterns:**
|
||||
- "This article introduces...", "This article explores..."
|
||||
- Pure topic description without value proposition
|
||||
- Repeating the title in different words
|
||||
|
||||
**EXTEND.md skip behavior:** If `auto_select: true` or `auto_select_title: true` is set in EXTEND.md, skip title selection — generate the best candidate directly without asking.
|
||||
|
||||
Once title is in frontmatter, body should NOT have H1 (avoid duplication).
|
||||
Once the title is in frontmatter, the body should NOT contain an H1 (avoid duplication).
|
||||
|
||||
### Step 4: Format Content
|
||||
|
||||
|
||||
Reference in New Issue
Block a user