baoyu-format-markdown

Files (8)

• SKILL.md
• title-formulas.md · references/
• autocorrect.ts · scripts/
• bun.lock · scripts/
• main.ts · scripts/
• package-lock.json · scripts/
• package.json · scripts/
• quotes.ts · scripts/

SKILL.md (first lines)

# Markdown Formatter

Make plain text or markdown scannable so readers grasp key points and structure fast.

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

`{baseDir}` = this SKILL.md's directory. `${BUN_X}` = `bun` if installed; else `npx -y bun` if `npx` available; 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)

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 |

None found → use defaults (no first-time setup for this skill).

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

## Workflow

The agent analyzes and formats (Steps 1-5), then runs the typography script (Step 6).

### Step 1: Read & Detect Content Type

Read the file. It is **Markdown** if it has `---` YAML frontmatter, `#`/`##`/`###` headings, or `**bold**`/`*italic*`/lists/code blocks/blockquotes; otherwise **plain text**.

If Markdown, 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
```

- **Optimize** → Step 2 (full workflow)
- **Keep original** → skip to Step 5 (copy file), then Step 6
- **Typography only** → skip to Step 6 on the original file

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

Read the whole text and ask what would help a reader quickly understand and remember it. Save `{original-filename}-analysis.md` — the blueprint for Step 4:

```markdown
# Content Analysis: {filename}

## Highlights & Key Insights
- [core arguments/conclusions, surprising facts or data, counterintuitive claims, golden quotes]

## Structure Assessment
- Current flow: [describe]
- Suggested sections: [heading candidates with brief rationale; unheaded section boundaries; walls of text needing breaks]

## Reader-Important Information
- [actionable takeaways, key definitions, lists buried in prose, comparisons that should be tables]

## Formatting Issues
- [specific issues with location: heading hierarchy, mixed-topic paragraphs, parallel items as prose, unmarked code/commands/terms]

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

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

Create a YAML frontmatter block if missing.

| Field | Processing |
|-------|------------|
| `title` | See **Title Generation** |
| `slug` | Infer from file path or generate from title |
| `summary` | One-sentence summary (see **Summary Generation**) |
| `description` | Longer descriptive summary (see **Summary Generation**) |
| `coverImage` | If `imgs/cover.png` exists in the same directory, use its relative path |

#### Title Generation

Run this flow even if a title exists, unless `auto_select_title` is set.

1. Extract: core argument (one sentence), most impactful opinion/conclusion, reader pain point or curiosity trigger, most memorable metaphor or golden quote
2. Using [references/title-formulas.md](references/title-formulas.md): pick the **2-3 best-matching hook formulas** ("When to pick each formula"), plus **1-2 straightforward titles** (descriptive or declarative, no formula). If the user gave a direction (e.g., "make it suspenseful"), prioritize it. Total **4-5 candidates**, obeying the reference's principles and prohibited patterns

From guanyang/open-agent-hub, MIT.

More from guanyang/open-agent-hub