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.
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.
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):
Prefer built-in user-input tools exposed by the current agent runtime — e.g., AskUserQuestion, request_user_input, clarify, ask_user, or any equivalent.
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.
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:
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:
# 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:
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)
Generate 1-2 straightforward titles (descriptive or declarative, no formula — clear and accurate)
If the user specifies a direction (e.g., "make it suspenseful"), prioritize that direction
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
