宝玉格式
- 作者仓库星标 0
- 作者更新于 2026年7月4日 01:22
- 作者仓库 baoyu-skills
- 领域
- 文档
- 作者声明的智能体
- 未找到明确声明;不据此推断已兼容或已测试
- 静态检查
- 92 / 100 · 启发式扫描,不代表运行安全
- 运行环境证据
- 未执行;当前没有隔离运行测试证据
- 作者 / 版本 / 许可证
- @JimLiu · v1.57.0 · 未声明许可证
- 上下文用量评级
- 低消耗
- 接入复杂程度
- 需手动接入
- 是否需要外部接口密钥
- 不需要
- 兼容的系统
- macOS · Linux · Windows
- 运行环境要求
- Bun · Python
- 检测到的文件与系统行为
-
- 只读
- 允许写入 / 修改
- 命令执行
- 网络行为
- 仅限本地
- 安装命令数
- 无(仅作为资料)
需要注意: 未声明工具权限范围;实际权限由运行环境决定。
第 1 步:读取并检测内容类型
读取用户指定的文件,然后检测内容类型: 指示符 · 分类有 `---` YAML frontmatter · Markdown 有 `#`、`##`、`###` 标题 · Markdown 有 `bold`、`*italic*`、列表、代码块、块引用 · Markdown
步骤 2:分析内容(读者的角度)
仔细阅读全部内容。站在读者的角度思考:什么可以帮助他们快速理解和记住关键信息?进行涵盖以下维度的分析: 2.1 要点和关键见解 作者提出的核心论点或结论 令人惊讶的事实、数据点或反直觉的主张
第 3 步:检查/创建 Frontmatter、标题和摘要
检查 YAML frontmatter(`---` 块)。如果丢失则创建。字段·处理`title`·参见下面的标题生成`slug`·从文件路径推断或从标题生成`summary`·一句话简明摘要(参见下面的摘要生成)
第四步:格式化内容
应用第 2 步分析指导的格式。目标是使内容易于浏览并且关键点不会被错过。格式化工具包:元素·何时使用·格式标题·自然主题边界、分节符·`##`、`###`层次结构粗体·关键结论、重要术语、核心要点·`bold`
第5步:保存格式化文件
另存为`{original-filename}-formatted.md` 备份现有文件:
第 6 步:执行排版脚本
在输出文件上运行格式化脚本: 脚本选项:选项 · 简短 · 描述 · 默认 `--quotes` · `-q` · 将 ASCII 引号替换为全角引号 `"..."` · false `--no-quotes` · 不替换引号
第7步:完成报告
显示总结所有所做更改的报告:调整报告以反映实际更改 - 忽略未进行更改的类别。
# 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.
章节与文件索引
按说明文件中的顺序排列。
用户输入工具
脚本目录
首选项(EXTEND.md)
用途
第 1 步:读取并检测内容类型
文件/命令 -> AskUserQuestion · request_user_input · clarify · ask_user · scripts/ · {baseDir} · ${BUN_X} · bun
内容校验值 -> db6af7ad63f3
baoyu-format-markdown 不是「跑一遍 Prettier」这么浅——它是把粗稿自动整形成「读者友好」版本的 Markdown:补 frontmatter、统一标题阶梯、识别并加粗关键句、整理列表、规范代码块。
核心约定
作者强调:不改变任何原始内容。它只调结构和呈现,不替你改字。所以可以放心给作者交付的文章用。
工作流
按 Workflow 章节:① 读输入文件,识别它是纯文本还是已带部分 Markdown;② Highlights & Key Insights:找出文章核心句,用粗体或引用标记;③ Structure Assessment:检查标题阶梯是否合理(不要 H1→H3 跳级),列表层级是否正确;④ Reader-Important Information:识别「读者最该看到的信息」并前置;⑤ Formatting Issues:修空行、错位的代码 fence、混乱的列表;⑥ Typos Found:列出疑似错别字(不替你改,列给你看)。
输入输出
输入支持纯 txt / 半结构化 Markdown / 老式 HTML 转 MD 的脏稿。输出始终是干净的 Markdown,顶部带 frontmatter(标题、摘要、tags)。
适合的场景
与
baoyu-markdown-to-html的关系这个负责打磨结构(让 Markdown 自身更好读),
baoyu-markdown-to-html负责输出排版(适配公众号 / 博客的 HTML)。两个技能配合就是「先把内容理顺,再让样式上线」。不适合
风格化散文、小说——它的「加粗关键句」逻辑会让文学味打折;正式法律 / 学术论文——格式应严格按目标期刊模板,让它自动加粗反而麻烦。