# Baoyu Format Markdown

> Da formato a textos planos o markdown: añade frontmatter, títulos, resúmenes, encabezados, negritas, listas y bloques de código, guardando el resultado en {filename}-formatted.md.

Fuente: https://skillsagentes.com/skills/jimliu/baoyu-skills/baoyu-format-markdown
Markdown: https://skillsagentes.com/skills/jimliu/baoyu-skills/baoyu-format-markdown.md

Repositorio: https://github.com/JimLiu/baoyu-skills
Autor: JimLiu
Licencia: MIT
Actualizado: hace 4 meses
Coste de contexto: 64 tok instalada, 3.5k tok al activarse, 18.9k tok con todos los archivos del bundle
Bundle: 8 archivos, 74 KB
Permisos que pide: ninguno declarado

## Instalación

Un skill son archivos markdown: los mismos archivos valen para cualquier agente y lo único que cambia es el directorio de destino, es decir la bandera `--agent`. Añade `-g` para instalarlo en todos los proyectos de la máquina.

```bash
# Claude Code
npx -y skills add JimLiu/baoyu-skills --skill baoyu-format-markdown --agent claude-code
# Cursor
npx -y skills add JimLiu/baoyu-skills --skill baoyu-format-markdown --agent cursor
# Codex
npx -y skills add JimLiu/baoyu-skills --skill baoyu-format-markdown --agent codex
# Gemini CLI
npx -y skills add JimLiu/baoyu-skills --skill baoyu-format-markdown --agent gemini
# Windsurf
npx -y skills add JimLiu/baoyu-skills --skill baoyu-format-markdown --agent windsurf
# Cline
npx -y skills add JimLiu/baoyu-skills --skill baoyu-format-markdown --agent cline
```

## Qué hace

- Analiza el contenido y genera un archivo {filename}-analysis.md con hallazgos clave, estructura y typos
- Crea o completa frontmatter YAML (title, slug, summary, description, coverImage)
- Genera candidatos de título con fórmulas de referencia y pide al usuario elegir uno
- Aplica formato: encabezados, negritas, listas, tablas, bloques de código y citas sin alterar el contenido original
- Ejecuta scripts/main.ts para corregir espaciado CJK, énfasis y comillas, guardando en {filename}-formatted.md

## Cuándo usarla

- El usuario pide 'formatear markdown', 'embellecer artículo' o 'añadir formato'
- Se quiere mejorar la maquetación de un artículo en texto plano o markdown
- Se necesita generar título, resumen y frontmatter para un artículo

## Qué la activa

- "Formatea este artículo en markdown"
- "Embellece este texto y añádele formato"
- "Mejora la maquetación de este archivo y genera un resumen"

## Antes de instalar

- Requiere tener instalado bun o npx para ejecutar los scripts de tipografía.
- Variables de entorno: BUN_X
- makes network requests
- reads environment config

## Archivos

- SKILL.md — 14 KB
- references/title-formulas.md — 3 KB
- scripts/autocorrect.ts — 352 B
- scripts/bun.lock — 21 KB
- scripts/main.ts — 5 KB
- scripts/package-lock.json — 31 KB
- scripts/package.json — 275 B
- scripts/quotes.ts — 173 B

## SKILL.md

Reproducido tal cual desde JimLiu/baoyu-skills bajo MIT. Esta sección es el documento original y está en inglés.

# Markdown Formatter

Transforms 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.

**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.

| Script | Purpose |
|--------|---------|
| `scripts/main.ts` | Main entry point with CLI options (uses remark-cjk-friendly for CJK emphasis) |
| `scripts/quotes.ts` | Replace ASCII quotes with fullwidth quotes |
| `scripts/autocorrect.ts` | Add CJK/English spacing via autocorrect |

## Preferences (EXTEND.md)

Check EXTEND.md in priority order — the first one found wins:

| 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 |

If none found, use defaults — no first-time setup required for this skill.

**EXTEND.md supports**:

| Setting | Values | Default | Description |
|---------|--------|---------|-------------|
| `auto_select` | `true`/`false` | `false` | Skip both title and summary selection, auto-pick best |
| `auto_select_title` | `true`/`false` | `false` | Skip title selection only |
| `auto_select_summary` | `true`/`false` | `false` | Skip summary selection only |
| Other | — | — | Default formatting options, typography preferences |

## Usage

The 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).

## Workflow

### Step 1: Read & Detect Content Type

Read the user-specified file, then detect content type:

| Indicator | Classification |
|-----------|----------------|
| Has `---` YAML frontmatter | Markdown |
| Has `#`, `##`, `###` headings | Markdown |
| Has `**bold**`, `*italic*`, lists, code blocks, blockquotes | Markdown |
| None of above | Plain text |

**If Markdown detected, use `AskUserQuestion` to ask:**

```
Detected existing markdown formatting. What would you like to do?

1. Optimize formatting (Recommended)
   - Analyze content, improve headings, bold, lists for readability
   - Run typography script (spacing, emphasis fixes)
   - Output: {filename}-formatted.md

2. Keep original formatting
   - Preserve existing markdown structure
   - Run typography script only
   - Output: {filename}-formatted.md

3. Typography fixes only
   - Run typography script on original file in-place
   - No copy created, modifies original file directly
```

**Based on user choice:**
- **Optimize**: Continue to Step 2 (full workflow)
- **Keep original**: Skip to Step 5, copy file then run Step 6
- **Typography only**: Skip to Step 6, run on original file directly

### Step 2: Analyze Content (Reader's Perspective)

Read the entire content carefully. Think from a reader's perspective: what would help them quickly understand and remember the key information?

Produce an analysis covering these dimensions:

**2.1 Highlights & Key Insights**
- Core arguments or conclusions the author makes
- Surprising facts, data points, or counterintuitive claims
- Memorable quotes or well-phrased sentences (golden quotes)

**2.2 Structure Assessment**
- Does the content have a clear logical flow? What is it?
- Are there natural section boundaries that lack headings?
- Are there long walls of text that could benefit from visual breaks?

**2.3 Reader-Important Information**
- Actionable advice or takeaways
- Definitions, explanations of key concepts
- Lists or enumerations buried in prose
- Comparisons or contrasts that would be clearer as tables

**2.4 Formatting Issues**
- Missing or inconsistent heading hierarchy
- Paragraphs that mix multiple topics
- Parallel items written as prose instead of lists
- Code, commands, or technical terms not marked as code
- Obvious typos or formatting errors

**Save analysis to file**: `{original-filename}-analysis.md`

The analysis file serves as the blueprint for Step 3. Use this format:

```markdown
# Content Analysis: {filename}

## Highlights & Key Insights
- [list findings]

## Structure Assessment
- Current flow: [describe]
- Suggested sections: [list heading candidates with brief rationale]

## Reader-Important Information
- [list actionable items, key concepts, buried lists, potential tables]

## Formatting Issues
- [list specific issues with location references]

## Typos Found
- [list any obvious typos with corrections, or "None found"]
```

### Step 3: Check/Create Frontmatter, Title & Summary

Check for YAML frontmatter (`---` block). Create if missing.

| Field | Processing |
|-------|------------|
| `title` | See **Title Generation** below |
| `slug` | Infer from file path or generate from title |
| `summary` | One-sentence concise summary (see **Summary Generation** below) |
| `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

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?")
- Most impactful opinion or conclusion
- Reader pain point or curiosity trigger
- Most memorable metaphor or golden quote

**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**

Present via `AskUserQuestion`:

```
Pick a title:

1. [Hook title A] — (recommended) [formula name]
2. [Hook title B] — [formula name]
3. [Hook title C] — [formula name]
4. [Straightforward title D] — straightforward
5. [Straightforward title E] — straightforward

Enter number, or type a custom title:
```

Put the strongest hook first and mark it `(recommended)`. See `references/title-formulas.md` for principles and prohibited patterns.

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.

**Skip behavior**: If `auto_select: true` or `auto_select_title: true`, skip the user prompt and use the top candidate directly.

#### 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**:

- 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 the existing one and only generate the missing field

**Prohibited patterns**:

- "This article introduces...", "This article explores..."
- Pure topic description without value proposition
- Repeating the title in different words

Once the title is in frontmatter, the body should NOT contain an H1 (avoid duplication).

### Step 4: Format Content

Apply formatting guided by the Step 2 analysis. The goal is making the content scannable and the key points impossible to miss.

**Formatting toolkit:**

| Element | When to use | Format |
|---------|-------------|--------|
| Headings | Natural topic boundaries, section breaks | `##`, `###` hierarchy |
| Bold | Key conclusions, important terms, core takeaways | `**bold**` |
| Unordered lists | Parallel items, feature lists, examples | `- item` |
| Ordered lists | Sequential steps, ranked items, procedures | `1. item` |
| Tables | Comparisons, structured data, option matrices | Markdown table |
| Code | Commands, file paths, technical terms, variable names | `` `inline` `` or fenced blocks |
| Blockquotes | Notable quotes, important warnings, cited text | `> quote` |
| Separators | Major topic transitions | `---` |

**Formatting principles — what NOT to do:**
- Do NOT add sentences, explanations, or commentary
- Do NOT delete or shorten any content
- Do NOT rephrase or rewrite the author's words
- Do NOT add headings that editorialize (e.g., "Amazing Discovery" — use neutral descriptive headings)
- Do NOT over-format: not every sentence needs bold, not every paragraph needs a heading

**Formatting principles — what TO do:**
- Preserve the author's voice, tone, and every word
- **Bold key conclusions and core takeaways** — the sentences a reader would highlight
- Extract parallel items from prose into lists only when the structure is clearly there
- Add headings where the topic genuinely shifts — prefer vivid, specific headings over generic ones (e.g., "3 天搞定 vs 传统方案" over "方案对比")
- Use tables for comparisons or structured data buried in prose
- Use blockquotes for golden quotes, memorable statements, or important warnings
- Fix obvious typos (based on Step 2 findings)

### Step 5: Save Formatted File

Save as `{original-filename}-formatted.md`

**Backup existing file:**

```bash
if [ -f "{filename}-formatted.md" ]; then
  mv "{filename}-formatted.md" "{filename}-formatted.backup-$(date +%Y%m%d-%H%M%S).md"
fi
```

### Step 6: Execute Typography Script

Run the formatting script on the output file:

```bash
${BUN_X} {baseDir}/scripts/main.ts {output-file-path} [options]
```

**Script Options:**

| Option | Short | Description | Default |
|--------|-------|-------------|---------|
| `--quotes` | `-q` | Replace ASCII quotes with fullwidth quotes `"..."` | false |
| `--no-quotes` | | Do not replace quotes | |
| `--spacing` | `-s` | Add CJK/English spacing via autocorrect | true |
| `--no-spacing` | | Do not add CJK/English spacing | |
| `--emphasis` | `-e` | Fix CJK emphasis punctuation issues | true |
| `--no-emphasis` | | Do not fix CJK emphasis issues | |

**Examples:**

```bash
# Default: spacing + emphasis enabled, quotes disabled
${BUN_X} {baseDir}/scripts/main.ts article.md

# Enable all features including quote replacement
${BUN_X} {baseDir}/scripts/main.ts article.md --quotes

# Only fix emphasis issues, skip spacing
${BUN_X} {baseDir}/scripts/main.ts article.md --no-spacing
```

**Script performs (based on options):**
1. Fix CJK emphasis/bold punctuation issues (default: enabled)
2. Add CJK/English mixed text spacing via autocorrect (default: enabled)
3. Replace ASCII quotes with fullwidth quotes (default: disabled)
4. Format frontmatter YAML (always enabled)

### Step 7: Completion Report

Display a report summarizing all changes made:

```
**Formatting Complete**

**Files:**
- Analysis: {filename}-analysis.md
- Formatted: {filename}-formatted.md

**Content Analysis Summary:**
- Highlights found: X key insights
- Golden quotes: X memorable sentences
- Formatting issues fixed: X items

**Changes Applied:**
- Frontmatter: [added/updated] (title, slug, summary)
- Headings added: X (##: N, ###: N)
- Bold markers added: X
- Lists created: X (from prose → list conversion)
- Tables created: X
- Code markers added: X
- Blockquotes added: X
- Typos fixed: X [list each: "original" → "corrected"]

**Typography Script:**
- CJK spacing: [applied/skipped]
- Emphasis fixes: [applied/skipped]
- Quote replacement: [applied/skipped]
```

Adjust the report to reflect actual changes — omit categories where no changes were made.

## Notes

- Preserve original writing style and tone
- Specify correct language for code blocks (e.g., `python`, `javascript`)
- Maintain CJK/English spacing standards
- The analysis file is a working document — it helps maintain consistency between what was identified and what was formatted

## Extension Support

Custom configurations via EXTEND.md. See **Preferences** section for paths and supported options.

## Dónde encaja

- Categoría: [Redacción y contenido](https://skillsagentes.com/categorias/redaccion-contenido.md) — Redacción, edición y estructuración de contenido extenso.
- Creador: [JimLiu](https://skillsagentes.com/creators/jimliu.md) — 0 skills en el directorio
- [Todas las skills](https://skillsagentes.com/skills.md)
- [Ranking de instalaciones](https://skillsagentes.com/ranking.md)

## Otras skills del mismo repositorio

- [Baoyu Image Gen](https://skillsagentes.com/skills/jimliu/baoyu-skills/baoyu-image-gen.md): Generación de imágenes con IA usando OpenAI GPT Image 2, Azure OpenAI, Google, OpenRouter, DashScope, Z.AI GLM-Image, MiniMax, Jimeng, Seedream, Replicate y Agnes; soporta texto a imagen, referencias, aspectos y lotes.
- [Baoyu Post To Wechat](https://skillsagentes.com/skills/jimliu/baoyu-skills/baoyu-post-to-wechat.md): Publica contenido en WeChat Official Account (微信公众号) vía API o Chrome CDP, con posts de artículo (文章) o de imagen-texto (贴图/图文).
- [Baoyu Wechat Summary](https://skillsagentes.com/skills/jimliu/baoyu-skills/baoyu-wechat-summary.md): Convierte los chats de un grupo de WeChat en un resumen estructurado usando el binario local wx-cli, con historial, perfiles de usuario y memoria de hechos por grupo entre ejecuciones.
- [Baoyu Post To X](https://skillsagentes.com/skills/jimliu/baoyu-skills/baoyu-post-to-x.md): Publica contenido y artículos en X (Twitter): posts normales con imágenes/vídeos y X Articles en Markdown, vía plugin Chrome de Codex, Computer Use o scripts CDP.
- [Baoyu Cover Image](https://skillsagentes.com/skills/jimliu/baoyu-skills/baoyu-cover-image.md): Genera portadas de artículos con 5 dimensiones (tipo, paleta, renderizado, texto, mood), combinando 11 paletas y 7 estilos de renderizado, en formatos cinematic, widescreen o square.

## Skills relacionadas

- [Baoyu Article Illustrator](https://skillsagentes.com/skills/jimliu/baoyu-skills/baoyu-article-illustrator.md): Analiza la estructura del artículo, identifica dónde faltan apoyos visuales y genera ilustraciones combinando Tipo × Estilo × Paleta. Úsalo para "ilustrar artículo", "añadir imágenes" o "为文章配图".
- [Baoyu Danger Gemini Web](https://skillsagentes.com/skills/jimliu/baoyu-skills/baoyu-danger-gemini-web.md): Genera imágenes y texto mediante la API web de Gemini (ingeniería inversa). Soporta generación de texto e imágenes, imágenes de referencia para visión y conversaciones multi-turno.
- [Baoyu Electron Extract](https://skillsagentes.com/skills/jimliu/baoyu-skills/baoyu-electron-extract.md): Extrae recursos y JavaScript de cualquier app Electron instalada (app.asar), restaurando las fuentes originales desde .js.map o formateando el código minificado con Prettier.
- [Baoyu Post To Weibo](https://skillsagentes.com/skills/jimliu/baoyu-skills/baoyu-post-to-weibo.md): Publica en Weibo texto, imágenes y vídeos, y artículos de cabecera (头条文章) en Markdown, usando Chrome vía CDP para evitar la detección anti-bot.
- [Release Skills](https://skillsagentes.com/skills/jimliu/baoyu-skills/release-skills.md): Flujo de release universal: detecta archivos de versión y changelogs, soporta Node.js, Python, Rust, Claude Plugin, GitHub Releases, tags anotados y backfill histórico.

---

Skills Agentes · [Índice de páginas en markdown](https://skillsagentes.com/sitemap.md) · [Inicio](https://skillsagentes.com/index.md)