Docs & Knowledge · JimLiu/baoyu-skills

baoyu-format-markdown

Name: baoyu-format-markdown
Author: JimLiu/baoyu-skills

Formats plain text or markdown files with frontmatter, titles, summaries, headings, bold, lists, and code blocks. Use when user asks to "format markdown", "beautify article", "add formatting", or improve article layout. Outputs to {filename}-formatted.md.

L4 High-Privilege · Graded auth & full auditV1 Commit-PinnedExecute CommandNetwork AccessWrite FileDual-pass Audit

Control levels describe skill capabilities and suggested control measures; they do not represent quality or safety certifications, nor do they dictate usability. Usage decisions rest entirely with users and administrators. Different agent hosts apply varying constraints; do not assume hosts provide automatic protection. Third-party skill copyrights belong to their original authors. Use at your own risk.

1How It Works & Mechanism

Division of responsibilities: Content-level analysis/refactoring is handled by the model following SKILL.md steps (Steps 1-5), while deterministic typesetting fixes are offloaded to built-in scripts (Step 6).

skills/baoyu-format-markdown/SKILL.md

Claude performs content analysis and formatting (Steps 1-5), then runs the script for typography fixes (Step 6).

What is happening here: It separates 'unverifiable editorial judgments' from 'scriptable typesetting fixes'. The script never rewrites content, thereby limiting the model's scope for overreach through step boundaries.

The core discipline is 'format only, do not touch content': no rewriting, no additions or deletions, and no commentary added.

skills/baoyu-format-markdown/SKILL.md

**Core principle**: Only adjust formatting and fix obvious typos. Never add, delete, or rewrite content.

Step 4 expands this into a prohibited list (Do NOT add sentences/explanations, Do NOT rephrase…) and a permitted list (preserve the author's tone, highlight conclusions in bold, distill parallel items into lists/tables).

The core script runs on a unified/remark pipeline: parse → optional CJK-friendly emphasis fix → GFM/frontmatter → stringify, then write back to the file in place.

skills/baoyu-format-markdown/scripts/main.ts

.use(options.emphasis ? remarkCjkFriendly : [])

Frontmatter is reformatted via YAML.parseDocument (`doc.toString({ lineWidth: 0 })`), quotes in text nodes are replaced with full-width quotes if requested, and final output overwrites the file via `writeFileSync(filePath, formattedContent, "utf-8")`.

CJK/English spacing is not implemented internally; instead, it executes `npx autocorrect-node --fix` at runtime to modify the file in place.

skills/baoyu-format-markdown/scripts/autocorrect.ts

const result = spawnSync(npxCmd, ["autocorrect-node", "--fix", filePath], {

spacing is true by default, so the default execution path fetches autocorrect-node from the npm registry; it can be disabled via --no-spacing.

Optional quote normalization: replaces paired ASCII double quotes and 「」 with full-width curved quotes.

skills/baoyu-format-markdown/scripts/quotes.ts

.replace(/"([^"]+)"/g, "\u201c$1\u201d")

Disabled by default (DEFAULT_OPTIONS.quotes=false); it applies to text nodes only when --quotes is passed.

Headline generation relies on a reusable formula library: references/title-formulas.md provides 8 hook formulas plus a straightforward type, outputting 4-5 candidates for the user to choose from.

skills/baoyu-format-markdown/references/title-formulas.md

8 hook formulas + straightforward style for balanced title generation.

SKILL.md requires: first extract core arguments, strongest views, and reader pain points, select 2-3 best-matching formulas to generate hook titles, then add 1-2 straightforward titles (`using formulas from `references/title-formulas.md``), placing the strongest hook first marked with (recommended).

Frontmatter fields follow fixed processing rules: title/slug/summary/description/coverImage, with dual summary/description versions meeting specific length criteria.

skills/baoyu-format-markdown/SKILL.md

| `summary` | 1 sentence, ~50-80 chars | Concise hook — for feeds, social sharing, SEO meta |

Applies a prohibited pattern list (e.g., banning openings like 'This article introduces…'); existing titles still generate new candidates, but existing summary/description values are preserved and only missing fields are filled.

Disk write discipline: outputs {filename}-formatted.md, backing up with a timestamp before overwriting; the analysis document {original-filename}-analysis.md is retained as the editorial basis.

skills/baoyu-format-markdown/SKILL.md

mv "{filename}-formatted.md" "{filename}-formatted.backup-$(date +%Y%m%d-%H%M%S).md"

When markdown formatting is detected, it prompts the user with 3 options (optimize formatting / keep original formatting / typography fixes only). The third option modifies the original file directly in place—the only branch in this skill that directly modifies the user's source file.

2Core Capabilities

01Markdown/plain text classification with three processing paths (optimize / keep original format / typography only)

02Reader-perspective content analysis: four dimensions covering highlights/quotes, structure, actionable takeaways, and typesetting issues, saved to -analysis.md

03Frontmatter generation and standardization (title/slug/summary/description/coverImage)

04Formula-driven multi-candidate headline generation with user selection (bypassable via auto_select)

05Typography repair script: CJK/English spacing (autocorrect), CJK emphasis punctuation, full-width quotes, frontmatter YAML reformatting

06Preference file EXTEND.md (project / XDG / home levels) to control behaviors such as auto_select

3External Dependencies

Kind	Dependency / Endpoint
cli	npx autocorrect-node --fix（CJK/英文间距修复）
package	remark-cjk-friendly
package	remark-parse / remark-stringify / remark-gfm / remark-frontmatter / unified / unist-util-visit / yaml
cli	bun（首选运行时；无 bun 时 npx -y bun）

4Recommended Governance & Evidence

Suggested Controls for Safe Operation

For Agent Runtime

Graded/per-use authorization, sandbox recommended

For Administrators

Approval workflow, rollback support, full audit

Evidence & Triggers (File Paths & Excerpts)

scripts/: Local script or command execution: bun {baseDir}/scripts/main.ts <file.md> [--quotes/--no-spacing/--no-emphasi
网络端点: External network access declaration: registry.npmjs.org: npx fetches autocorrect-node (version unpinned in repository); cached by npm after initial run
本地工作目录: File I/O and artifact output: Writes back in-place to processed .md files (writeFileSync in main.ts during quotes/emphasis phases; the 'typography fixes only' path directly modifies user source files)

Audit Notes: Three-part justification: 1) The audit target is this skill directory (SKILL.md + scripts/{main,quotes,autocorrect}.ts + references/title-formulas.md); 2) Internal behavior is limited to local file I/O (in-place edits of user md files, writing -formatted.md/-analysis.md/backups), plus one fixed public endpoint outbound call: `spawnSync(npxCmd, ["autocorrect-node", "--fix", filePath] …)` in `skills/baoyu-format-markdown/scripts/autocorrect.ts` fetches and runs this third-party CLI from registry.npmjs.org when default spacing is enabled; 3) No credentials/keys are read, no user content leaves the network, and there is no reverse-engineering, spoofing, bypass, or security downgrade, placing it at Yellow rather than Orange or Red. Note: The default path may modify user source files in place (third path) and runs an unpinned npx package, which has been recorded in verdict.risks.

5Second-Pass Verification

[ok] 『模型做内容、脚本做排版』的两段式划分 — SKILL.md Workflow 段逐字：'Claude performs content analysis and formatting (Steps 1-5), then runs the script for typography fixes (Step 6).' 与脚本能力一致（脚本无内容改写逻辑）。
[ok] 脚本的确定性修复项与默认值 — main.ts DEFAULT_OPTIONS={quotes:false, spacing:true, emphasis:true}；--quotes/--no-spacing/--no-emphasis 均有对应分支；与 SKILL.md 选项表一致。
[ok] npx autocorrect-node 为唯一外部命令调用 — 全目录 grep spawn/exec/npx 仅 autocorrect.ts 命中一处；main.ts 只有 readFileSync/writeFileSync。
[ok] 外部依赖清单完整性 — package.json 声明 8 个包（remark 生态 + unified + yaml），另加运行时 npx 的 autocorrect-node；全目录无任何 http 端点/API 调用。
[ok] 无凭证读取 — 目录内 token 扫描 API_KEY/TOKEN/SECRET/.env/keychain 零命中；仅读取 EXTEND.md 偏好（路径在 SKILL.md 明列）。
[ok] 标题公式库内容与『8 个公式』一致 — references/title-formulas.md 首行 '8 hook formulas + straightforward style for balanced title generation.'，表格确为 8 行 hook（Subversive…Empathy）。
[ok] 『仅排版修复』会原地改用户文件 — SKILL.md 第三条路径写明 'Run typography script on original file in-place / No copy created, modifies original file directly'，与 main.ts writeFileSync(filePath…) 行为一致，已列为使用注意。
[ok] 元数据（license/stars/commit） — git HEAD=1567581c26ec29f4216c6e6835415bf30343b0e3；仓库根 LICENSE=MIT（Copyright (c) 2026 Jim Liu）；GitHub API stars=25926、pushed_at=2026-09-10T15:13:43Z。

6Verdict & Scenarios

Clear process tiering where script and model duties do not overlap: scripts only perform verifiable typesetting fixes while editorial judgment is left to the model, reducing the risk of unauthorized rewrites.

Reusable methodology for title and summary generation (8 hook formulas + straightforward type + negative examples) instead of relying on improvised model output.

Deterministic fixes for common CJK style issues (CJK spacing, CJK emphasis punctuation, full-width quotes) without relying on model intuition.

Strict backup discipline for disk writes with fixed output naming, facilitating version comparison and rollback.

Best for: Ideal for scenarios where long-form drafts, interview transcripts, or public blog posts written by users need restructuring by an agent for skimmability and key takeaway extraction, alongside generating frontmatter (title/slug/summary/description). Also suitable as a pre-cleaning pipeline step for downstream skills like markdown-to-html or post-to-wechat (default spacing/emphasis fixes prevent bold markdown parsing failures on platforms like WeChat).

Not for: Not suitable for compliance documents requiring strict layout uniformity (which should use fixed templates/CI validation) or prohibiting any source changes. Not suitable for workflows where the original Markdown is the single source of truth and cannot tolerate in-place modification (the third path overwrites directly). Not suitable for requests expecting the script itself to perform content rewriting or translation—this skill strictly formats without altering content.

Install Agent-Ready

① Verified Mirror 2026-09-15

Option A · Direct DownloadDownload baoyu-format-markdown.tar.gz

sha256: 6367312d8f2334bb…

Option B · Copy Guide for Agent

install.json

Agents automatically download and verify mirrors from this JSON guide.

② Upstream GitHub

GitHub Repo ↗

Pinned to commit 1567581c26.