{"id":"baoyu-format-markdown","name":"baoyu-format-markdown","summary":"前文、タイトル、要約、見出し、太字、リスト、コードブロックを含む平文またはマークダウンファイル。ユーザーが「マークダウンのフォーマット」「記事の美化」「フォーマットを追加」「記事レイアウトの改善」を求められた際に使ってください。","body":"# Markdown Formatter\n\nTransforms plain text or markdown into well-structured, reader-friendly markdown. The goal is to help readers quickly grasp key points, highlights, and structure — without changing any original content.\n\n**Core principle**: Only adjust formatting and fix obvious typos. Never add, delete, or rewrite content.\n\n## User Input Tools\n\nWhen this skill prompts the user, follow this tool-selection rule (priority order):\n\n1. **Prefer built-in user-input tools** exposed by the current agent runtime — e.g., `AskUserQuestion`, `request_user_input`, `clarify`, `ask_user`, or any equivalent.\n2. **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.\n3. **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.\n\nConcrete `AskUserQuestion` references below are examples — substitute the local equivalent in other runtimes.\n\n## Script Directory\n\nScripts 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.\n\n| Script | Purpose |\n|--------|---------|\n| `scripts/main.ts` | Main entry point with CLI options (uses remark-cjk-friendly for CJK emphasis) |\n| `scripts/quotes.ts` | Replace ASCII quotes with fullwidth quotes |\n| `scripts/autocorrect.ts` | Add CJK/English spacing via autocorrect |\n\n## Preferences (EXTEND.md)\n\nCheck EXTEND.md in priority order — the first one found wins:\n\n| Priority | Path | Scope |\n|----------|------|-------|\n| 1 | `.baoyu-skills/baoyu-format-markdown/EXTEND.md` | Project |\n| 2 | `${XDG_CONFIG_HOME:-$HOME/.config}/baoyu-skills/baoyu-format-markdown/EXTEND.md` | XDG |\n| 3 | `$HOME/.baoyu-skills/baoyu-format-markdown/EXTEND.md` | User home |\n\nIf none found, use defaults — no first-time setup required for this skill.\n\n**EXTEND.md supports**:\n\n| Setting | Values | Default | Description |\n|---------|--------|---------|-------------|\n| `auto_select` | `true`/`false` | `false` | Skip both title and summary selection, auto-pick best |\n| `auto_select_title` | `true`/`false` | `false` | Skip title selection only |\n| `auto_select_summary` | `true`/`false` | `false` | Skip summary selection only |\n| Other | — | — | Default formatting options, typography preferences |\n\n## Usage\n\nThe workflow has two phases: **Analyze** (understand the content) then **Format** (apply formatting). Claude performs content analysis and formatting (Steps 1-5), then runs the script for typography fixes (Step 6).\n\n## Workflow\n\n### Step 1: Read & Detect Content Type\n\nRead the user-specified file, then detect content type:\n\n| Indicator | Classification |\n|-----------|----------------|\n| Has `---` YAML frontmatter | Markdown |\n| Has `#`, `##`, `###` headings | Markdown |\n| Has `**bold**`, `*italic*`, lists, code blocks, blockquotes | Markdown |\n| None of above | Plain text |\n\n**If Markdown detected, use `AskUserQuestion` to ask:**\n\n```\nDetected existing markdown formatting. What would you like to do?\n\n1. Optimize formatting (Recommended)\n   - Analyze content, improve headings, bold, lists for readability\n   - Run typography script (spacing, emphasis fixes)\n   - Output: {filename}-formatted.md\n\n2. Keep original formatting\n   - Preserve existing markdown structure\n   - Run typography script only\n   - Output: {filename}-formatted.md\n\n3. Typography fixes only\n   - Run typography script on original file in-place\n   - No copy created, modifies original file directly\n```\n\n**Based on user choice:**\n- **Optimize**: Continue to Step 2 (full workflow)\n- **Keep original**: Skip to Step 5, copy file then run Step 6\n- **Typography only**: Skip to Step 6, run on original file directly\n\n### Step 2: Analyze Content (Reader's Perspective)\n\nRead the entire content carefully. Think from a reader's perspective: what would help them quickly understand and remember the key information?\n\nProduce an analysis covering these dimensions:\n\n**2.1 Highlights & Key Insights**\n- Core arguments or conclusions the author makes\n- Surprising facts, data points, or counterintuitive claims\n- Memorable quotes or well-phrased sentences (golden quotes)\n\n**2.2 Structure Assessment**\n- Does the content have a clear logical flow? What is it?\n- Are there natural section boundaries that lack headings?\n- Are there long walls of text that could benefit from visual breaks?\n\n**2.3 Reader-Important Information**\n- Actionable advice or takeaways\n- Definitions, explanations of key concepts\n- Lists or enumerations buried in prose\n- Comparisons or contrasts that would be clearer as tables\n\n**2.4 Formatting Issues**\n- Missing or inconsistent heading hierarchy\n- Paragraphs that mix multiple topics\n- Parallel items written as prose instead of lists\n- Code, commands, or technical terms not marked as code\n- Obvious typos or formatting errors\n\n**Save analysis to file**: `{original-filename}-analysis.md`\n\nThe analysis file serves as the blueprint for Step 3. Use this format:\n\n```markdown\n# Content Analysis: {filename}\n\n## Highlights & Key Insights\n- [list findings]\n\n## Structure Assessment\n- Current flow: [describe]\n- Suggested sections: [list heading candidates with brief rationale]\n\n## Reader-Important Information\n- [list actionable items, key concepts, buried lists, potential tables]\n\n## Formatting Issues\n- [list specific issues with location references]\n\n## Typos Found\n- [list any obvious typos with corrections, or \"None found\"]\n```\n\n### Step 3: Check/Create Frontmatter, Title & Summary\n\nCheck for YAML frontmatter (`---` block). Create if missing.\n\n| Field | Processing |\n|-------|------------|\n| `title` | See **Title Generation** below |\n| `slug` | Infer from file path or generate from title |\n| `summary` | One-sentence concise summary (see **Summary Generation** below) |\n| `description` | Longer descriptive summary (see **Summary Generation** below) |\n| `coverImage` | Check if `imgs/cover.png` exists in same directory; if so, use relative path |\n\n#### Title Generation\n\nWhether or not a title already exists, run the title optimization flow unless `auto_select_title` is set.\n\n**Preparation** — read the full text and extract:\n- Core argument (one sentence: \"what is this article about?\")\n- Most impactful opinion or conclusion\n- Reader pain point or curiosity trigger\n- Most memorable metaphor or golden quote\n\n**Generate candidates** using formulas from `references/title-formulas.md`:\n\n1. 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)\n2. Generate **1-2 straightforward titles** (descriptive or declarative, no formula — clear and accurate)\n3. If the user specifies a direction (e.g., \"make it suspenseful\"), prioritize that direction\n4. Total: **4-5 candidates**\n\nPresent via `AskUserQuestion`:\n\n```\nPick a title:\n\n1. [Hook title A] — (recommended) [formula name]\n2. [Hook title B] — [formula name]\n3. [Hook title C] — [formula name]\n4. [Straightforward title D] — straightforward\n5. [Straightforward title E] — straightforward\n\nEnter number, or type a custom title:\n```\n\nPut the strongest hook first and mark it `(recommended)`. See `references/title-formulas.md` for principles and prohibited patterns.\n\nIf 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.\n\n**Skip behavior**: If `auto_select: true` or `auto_select_title: true`, skip the user prompt and use the top candidate directly.\n\n#### Summary Generation\n\nGenerate two versions directly (no user selection), both stored in frontmatter:\n\n| Field | Length | Purpose |\n|-------|--------|---------|\n| `summary` | 1 sentence, ~50-80 chars | Concise hook — for feeds, social sharing, SEO meta |\n| `description` | 2-3 sentences, ~100-200 chars | Richer context — for article previews, newsletter blurbs |\n\n**Principles**:\n\n- Convey **core value** to the reader, not just the topic\n- Use concrete details (numbers, outcomes, specific methods) over vague descriptions\n- `summary` should be punchy and self-contained; `description` can expand with supporting details\n- If frontmatter already has `summary` or `description`, keep the existing one and only generate the missing field\n\n**Prohibited patterns**:\n\n- \"This article introduces...\", \"This article explores...\"\n- Pure topic description without value proposition\n- Repeating the title in different words\n\nOnce the title is in frontmatter, the body should NOT contain an H1 (avoid duplication).\n\n### Step 4: Format Content\n\nApply formatting guided by the Step 2 analysis. The goal is making the content scannable and the key points impossible to miss.\n\n**Formatting toolkit:**\n\n| Element | When to use | Format |\n|---------|-------------|--------|\n| Headings | Natural topic boundaries, section breaks | `##`, `###` hierarchy |\n| Bold | Key conclusions, important terms, core takeaways | `**bold**` |\n| Unordered lists | Parallel items, feature lists, examples | `- item` |\n| Ordered lists | Sequential steps, ranked items, procedures | `1. item` |\n| Tables | Comparisons, structured data, option matrices | Markdown table |\n| Code | Commands, file paths, technical terms, variable names | `` `inline` `` or fenced blocks |\n| Blockquotes | Notable quotes, important warnings, cited text | `> quote` |\n| Separators | Major topic transitions | `---` |\n\n**Formatting principles — what NOT to do:**\n- Do NOT add sentences, explanations, or commentary\n- Do NOT delete or shorten any content\n- Do NOT rephrase or rewrite the author's words\n- Do NOT add headings that editorialize (e.g., \"Amazing Discovery\" — use neutral descriptive headings)\n- Do NOT over-format: not every sentence needs bold, not every paragraph needs a heading\n\n**Formatting principles — what TO do:**\n- Preserve the author's voice, tone, and every word\n- **Bold key conclusions and core takeaways** — the sentences a reader would highlight\n- Extract parallel items from prose into lists only when the structure is clearly there\n- Add headings where the topic genuinely shifts — prefer vivid, specific headings over generic ones (e.g., \"3 天搞定 vs 传统方案\" over \"方案对比\")\n- Use tables for comparisons or structured data buried in prose\n- Use blockquotes for golden quotes, memorable statements, or important warnings\n- Fix obvious typos (based on Step 2 findings)\n\n### Step 5: Save Formatted File\n\nSave as `{original-filename}-formatted.md`\n\n**Backup existing file:**\n\n```bash\nif [ -f \"{filename}-formatted.md\" ]; then\n  mv \"{filename}-formatted.md\" \"{filename}-formatted.backup-$(date +%Y%m%d-%H%M%S).md\"\nfi\n```\n\n### Step 6: Execute Typography Script\n\nRun the formatting script on the output file:\n\n```bash\n${BUN_X} {baseDir}/scripts/main.ts {output-file-path} [options]\n```\n\n**Script Options:**\n\n| Option | Short | Description | Default |\n|--------|-------|-------------|---------|\n| `--quotes` | `-q` | Replace ASCII quotes with fullwidth quotes `\"...\"` | false |\n| `--no-quotes` | | Do not replace quotes | |\n| `--spacing` | `-s` | Add CJK/English spacing via autocorrect | true |\n| `--no-spacing` | | Do not add CJK/English spacing | |\n| `--emphasis` | `-e` | Fix CJK emphasis punctuation issues | true |\n| `--no-emphasis` | | Do not fix CJK emphasis issues | |\n\n**Examples:**\n\n```bash\n# Default: spacing + emphasis enabled, quotes disabled\n${BUN_X} {baseDir}/scripts/main.ts article.md\n\n# Enable all features including quote replacement\n${BUN_X} {baseDir}/scripts/main.ts article.md --quotes\n\n# Only fix emphasis issues, skip spacing\n${BUN_X} {baseDir}/scripts/main.ts article.md --no-spacing\n```\n\n**Script performs (based on options):**\n1. Fix CJK emphasis/bold punctuation issues (default: enabled)\n2. Add CJK/English mixed text spacing via autocorrect (default: enabled)\n3. Replace ASCII quotes with fullwidth quotes (default: disabled)\n4. Format frontmatter YAML (always enabled)\n\n### Step 7: Completion Report\n\nDisplay a report summarizing all changes made:\n\n```\n**Formatting Complete**\n\n**Files:**\n- Analysis: {filename}-analysis.md\n- Formatted: {filename}-formatted.md\n\n**Content Analysis Summary:**\n- Highlights found: X key insights\n- Golden quotes: X memorable sentences\n- Formatting issues fixed: X items\n\n**Changes Applied:**\n- Frontmatter: [added/updated] (title, slug, summary)\n- Headings added: X (##: N, ###: N)\n- Bold markers added: X\n- Lists created: X (from prose → list conversion)\n- Tables created: X\n- Code markers added: X\n- Blockquotes added: X\n- Typos fixed: X [list each: \"original\" → \"corrected\"]\n\n**Typography Script:**\n- CJK spacing: [applied/skipped]\n- Emphasis fixes: [applied/skipped]\n- Quote replacement: [applied/skipped]\n```\n\nAdjust the report to reflect actual changes — omit categories where no changes were made.\n\n## Notes\n\n- Preserve original writing style and tone\n- Specify correct language for code blocks (e.g., `python`, `javascript`)\n- Maintain CJK/English spacing standards\n- The analysis file is a working document — it helps maintain consistency between what was identified and what was formatted\n\n## Extension Support\n\nCustom configurations via EXTEND.md. See **Preferences** section for paths and supported options.","author":"@JimLiu","ownerProfile":null,"authorContacts":null,"sourceUrl":"https://github.com/JimLiu/baoyu-skills/tree/main/skills/baoyu-format-markdown","license":"MIT","category":"writing","lang":"en","tokens":3177,"stars":0,"calls30d":1,"claimed":false,"visibility":"public","origin":"crawler","version":"0.1.0","createdAt":"2026-08-22","updatedAt":"2026-08-22","files":[{"path":"references/title-formulas.md","size":2929,"sha256":"7c7da8ff605d35a15ef7fc5bae27a26c96bd6cb6c8e2e216774665d44f98233f"},{"path":"scripts/autocorrect.ts","size":352,"sha256":"dd26a4547d268d08efc733491e73f72924e61e40b92bc01dc664fc3d3c4d2cb8"},{"path":"scripts/bun.lock","size":21258,"sha256":"a58ac638d12995f767bc061cacbd9459aa8339f2253f81d46bf2e5f082b637c9"},{"path":"scripts/main.ts","size":4837,"sha256":"56fb2abe0526487b9807f0b82a9bb397ec652fc286cacd5fd18e9e28bac7a46a"},{"path":"scripts/package.json","size":275,"sha256":"9d96dc9af382bcf88916d5643c1275cca394b8e9b18a436ea88dc5534329facc"},{"path":"scripts/package-lock.json","size":31859,"sha256":"82f86c6467ef2fa733e44656f815db0507ed61838ee83eadf2f9df735a7dca6d"},{"path":"scripts/quotes.ts","size":173,"sha256":"4f60e5ab93de91033eac25718c3ed65db1bd6cb4c5aced41c38cebde055b7a42"}],"requires":{"mcp":[],"tools":[]},"safety":{"flags":[{"code":"net.endpoints","kind":"exfiltration","excerpt":"opencollective.com, registry.npmjs.org","message":"bundled scripts reach 2 external host(s)","severity":"warn"}],"scannedAt":"2026-08-22","hasScripts":true,"networkEndpoints":["opencollective.com","registry.npmjs.org"]}}