Content & Media Creation · freestylefly/canghe-skills
canghe-format-markdown
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
Clear division of labor: Content analysis and formatting are handled by Claude (LLM) in Steps 1–6, while the script only performs typesetting fixes in the final step (Step 7).
skills/canghe-format-markdown/SKILL.md
Claude performs content analysis and formatting (Steps 1-6), then runs the script for typography fixes (Step 7).
What is happening here: This is a hybrid skill where "LLM handles structure + script handles typesetting"; the script is responsible for deterministic typesetting and does not interpret content.
Detect content type first: If any of frontmatter, headings, bold, lists, code blocks, or blockquotes are matched, it is classified as markdown; it is treated as plain text only when none match.
skills/canghe-format-markdown/SKILL.md
| Has `---` YAML frontmatter | Markdown |
What is happening here: The type determines subsequent branching—plain text proceeds directly to Step 2 formatting, whereas markdown prompts the user first.
When markdown is detected, present the user with three choices: optimize formatting, keep as is, or run typesetting fixes only (the latter directly modifies the original file).
skills/canghe-format-markdown/SKILL.md
1. Optimize formatting (Recommended)
What is happening here: The three paths determine which subsequent steps are skipped; "typesetting fixes only" skips artifact copying and modifies the user's source file in place.
Auto-populate frontmatter: Write metadata fields such as title, slug, summary, and coverImage into YAML, with summary generated by the model as a 100–150 character abstract.
skills/canghe-format-markdown/SKILL.md
| `summary` | Generate engaging summary (100-150 characters) |
What is happening here: slug is inferred from the file path or generated from the title; coverImage uses a relative path only if imgs/cover.png exists in the same directory.
Heading deduplication: If the first line of the body is an H1, it is extracted into the frontmatter title and removed from the body to prevent duplicate H1 headings.
skills/canghe-format-markdown/SKILL.md
2. If first line is H1 → extract to frontmatter `title`, remove H1 from body
What is happening here: Three candidate titles are generated by the model and presented via AskUserQuestion for user selection, falling back to the recommended item on timeout.
The output name is fixed to {original-filename}-formatted.md, and existing artifacts with the same name are backed up with a timestamp before overwriting.
skills/canghe-format-markdown/SKILL.md
mv "{filename}-formatted.md" "{filename}-formatted.backup-$(date +%Y%m%d-%H%M%S).md"
What is happening here: final.md → final-formatted.md; if it already exists, it is backed up as final-formatted.backup-20260128-143052.md before writing.
The typesetting script main.ts reads the file, processes it according to options, and writes it back in place; the processing is a deterministic string/AST transformation.
skills/canghe-format-markdown/scripts/main.ts
writeFileSync(filePath, formattedContent, "utf-8");
What is happening here: main.ts uses readFileSync to read, processes the content, and uses writeFileSync to write back to the same path, meaning "typesetting fixes only" directly modifies the user's source file.
The script provides multiple typesetting toggles: CJK emphasis fixes, CJK/English spacing, ASCII to full-width quotes, and frontmatter YAML formatting.
skills/canghe-format-markdown/SKILL.md
| `scripts/quotes.ts` | Replace ASCII quotes with fullwidth quotes |
What is happening here: --quotes, --spacing, --emphasis, and their corresponding --no-* inverse flags; the script defaults to spacing+emphasis enabled and quotes disabled.
Spacing fixes are not implemented internally, but invoked via execSync calling the external npx autocorrect-node CLI.
skills/canghe-format-markdown/scripts/autocorrect.ts
execSync(`npx autocorrect-node --fix "${filePath}"`, { stdio: "inherit" });
What is happening here: filePath is concatenated into a shell command via string interpolation—this is an injection surface for this skill (see security.injection_surface).
The script depends on the remark ecosystem (remark-cjk-friendly / remark-frontmatter / remark-gfm / unified, etc.) and uses a YAML library to read and write frontmatter.
skills/canghe-format-markdown/scripts/package.json
"remark-cjk-friendly": "^1.1.0",
What is happening here: Dependencies are declared and locked in package.json / package-lock.json / bun.lock, relying on npx -y bun to execute TS directly.
2Core Capabilities
01Plain text / semi-structured text → standardized markdown artifact
02Automatic generation of frontmatter / title / slug / summary / coverImage
03CJK emphasis (bold) punctuation fixes
04CJK / English mixed-text spacing (autocorrect)
05ASCII quotes → full-width quotes replacement
06Automatic timestamped backup prior to overwrite
07Interactive title selection (3 candidates + user confirmation)
08Three-way workflow selection upon markdown detection (optimize / preserve / typesetting only)
3External Dependencies
| Kind | Dependency / Endpoint |
|---|---|
| cli | bun / npx（npx -y bun 运行 main.ts） |
| package | autocorrect-node（npx 第三方 CLI，由 autocorrect.ts 调起） |
| package | remark 生态（remark-cjk-friendly / remark-frontmatter / remark-gfm / unified 等） |
| network | registry.npmjs.org（依赖与 npx 包拉取来源） |
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/: Execute local scripts or commands: scripts/main.ts (run via npx -y bun: read file → typesetting processing → write back in place)
- 网络端点: Declared external network access: registry.npmjs.org (npx fetches autocorrect-node and bun dependencies on first run; npx package version is not locked in this repository)
- 本地工作目录: File I/O and artifact output: {filename}-formatted.md (formal output artifact)
Audit Notes: Target of assessment = this skill directory (SKILL.md + scripts/{main,quotes,autocorrect}.ts + package.json/package-lock.json/bun.lock): Internal behavior = local file read/write (reading user md, writing -formatted.md, in-place modification of original files, creating backups), plus outbound calls to a fixed public endpoint (execSync in autocorrect.ts uses npx to fetch and run a third-party CLI from registry.npmjs.org when default spacing is enabled, without package version locking in this repo). No credential/secret reading, no reverse engineering/impersonation/protection bypass/security degradation, and no user content sent to business backends; hence rated Yellow rather than Orange/Red. Points to note: ① The "typesetting fixes only" path modifies the user's source file in place; ② String interpolation in autocorrect.ts execSync creates a command injection surface (which could be avoided by using an args array); ③ Running unlocked npx packages introduces supply chain unpredictability.
5Second-Pass Verification
- [ok] 无业务网络请求，仅 npx 拉包 — §3 URL 命中集中在 package-lock.json 的 registry/赞助链接；脚本无业务端点调用，唯一外发是 npx 拉 autocorrect-node。
- [ok] 本地读写与原地修改 — main.ts 以 readFileSync/writeFileSync 同路径读写；SKILL.md 的「Typography fixes only」路径直接改原文件，无副本。
- [ok] CJK 排版三能力 — emphasis（remark-cjk-friendly）、spacing（autocorrect-node）、quotes（quotes.ts 全角替换）三项在脚本职责与 SKILL.md 选项中均有对应。
- [ok] execSync 命令注入面 — autocorrect.ts 用模板串把 filePath 插进 shell 命令；同类 baoyu 版用 spawnSync(npxCmd, [...args]) 的数组形式，本版更弱，已记入 injection_surface 与 risks。
- [ok] 无凭证读取 — 目录内无 env/keychain/cookie 读取；仅检查 EXTEND.md 偏好文件是否存在（非凭证）。
- [ok] 与 baoyu 同型实现的差异 — canghe 版无 references/ 与分析底稿，目录更精简（7 文件）；排版脚本形态由 spawnSync 改为 execSync。
- [ok] 依赖可复现性 — remark 生态在 package.json/package-lock.json/bun.lock 有锁定；但 npx autocorrect-node 未锁定具体版本。
6Verdict & Scenarios
Best for: Ideal for Chinese writers looking to format drafts or semi-structured text into standardized markdown (adding frontmatter, headings, lists, Chinese/English spacing, and full-width quotes), or as a standard pre-publishing typesetting step.
Not for: Not suitable for scenarios where source files must strictly remain untouched ("typesetting fixes only" writes in place); not suitable for fully offline environments lacking npx/Node; not suitable for teams with strict policies against unlocked third-party npx package supply chain risks.
Install Agent-Ready
① Verified Mirror 2026-10-10
Option A · Direct DownloadDownload canghe-format-markdown.tar.gz
sha256:
Option B · Copy Guide for Agent535df884a21e0d2e…Agents automatically download and verify mirrors from this JSON guide.
② Upstream GitHub
GitHub Repo ↗
Pinned to commit dd0bf35595.