What is markdown-formatter?

The Markdown Formatter skill is a specialized tool designed to automate the cleaning, structuring, and standardization of Markdown files. It ensures professional-grade documentation by fixing heading hierarchies, beautifying tables, and applying consistent styling to lists and code blocks. By enforcing best practices such as adding language tags to code and alt text to images, it significantly improves document readability, maintainability, and SEO performance.

When should I use markdown-formatter?

markdown-formatter is useful in the following scenarios: • Project Documentation Standardization: Automatically unify the formatting of README.md, CONTRIBUTING.md, and API documentation across a repository to ensure a consistent professional look. • Technical Blog Post Optimization: Clean up drafts by correcting nested heading levels, aligning complex data tables, and ensuring all code snippets have proper syntax highlighting tags. • Legacy Content Migration: Refurbish old or poorly formatted Markdown files by validating links, removing trailing whitespaces, and standardizing list indentations for better clarity. • Knowledge Base Maintenance: Ensure all technical wiki entries follow a strict style guide, making them easier to navigate and search for team members and external users.

name	markdown-formatter
description	Markdownファイルのフォーマットと整形を実行します。見出し構造の修正、コードブロックの整形、リンク検証、表の整列、一貫性のあるスタイル適用を行います。Markdown整形、フォーマット、スタイル統一について言及する場合に使用します。
allowed-tools	Read, Edit, Write

Markdown Formatter

このSkillは、Markdownファイルを美しく、読みやすく、一貫性のある形式に整形します。

Instructions

ステップ1: ファイル読み込みと分析

Readツールでファイルを読み込む
現在の構造を分析：
- 見出しレベルの一貫性
- コードブロックの言語指定
- リストのインデント
- 表の整列
- リンクの形式

ステップ2: 見出し構造の最適化

修正前:

# タイトル
### サブセクション（H3が直接H1の下にある）
## メインセクション
#### さらにサブ（階層が飛んでいる）

修正後:

# タイトル
## メインセクション
### サブセクション
#### さらにサブ

ルール:

H1は1つだけ（ドキュメントタイトル）
見出しレベルを飛ばさない（H2 → H4はNG）
見出しの前後に1行の空行を入れる

ステップ3: コードブロックの整形

修正前:

function hello() { console.log("Hello"); }

修正後:

```javascript
function hello() {
  console.log("Hello");
}
```

ルール:

コードブロックに言語指定を追加
インデントを統一（2スペースまたは4スペース）
コードブロックの前後に1行の空行

対応言語:

javascript, typescript, python, java, go, rust
html, css, scss, json, yaml, markdown
bash, sh, zsh, powershell

ステップ4: リストの整形

修正前:

* アイテム1
  - サブアイテム（インデントが不統一）
* アイテム2
    * サブアイテム（インデントが深すぎる）

修正後:

* アイテム1
  * サブアイテム（2スペース統一）
* アイテム2
  * サブアイテム

ルール:

順序なしリストは * または - で統一
順序ありリストは 1. 2. 3. 形式
サブリストは2スペースインデント
リストの前後に1行の空行

ステップ5: 表の整列

修正前:

| Name | Age | City |
|---|---|---|
| Alice | 30 | Tokyo |
| Bob | 25 | Osaka |

修正後:

| Name  | Age | City  |
|-------|-----|-------|
| Alice | 30  | Tokyo |
| Bob   | 25  | Osaka |

ルール:

列を視覚的に整列
ヘッダー区切り線を統一（3つ以上のハイフン）
セル内の余分なスペースを削除

ステップ6: リンクの整形

インラインリンク:

[リンクテキスト](https://example.com)

参照リンク（長いURLの場合）:

詳細は[公式ドキュメント][1]を参照してください。

[1]: https://very-long-url-that-would-break-readability.com/path/to/resource

ルール:

リンクテキストは明確に
URLが長い場合は参照リンクを使用
相対パスと絶対パスを統一

ステップ7: 画像の整形

基本形式:

![代替テキスト](画像パス)

キャプション付き:

![AIエージェントアーキテクチャ図](./images/architecture.png)
*図1: マルチエージェントシステムの構成*

ルール:

alt属性（代替テキスト）を必ず記載
画像の前後に1行の空行
キャプションはイタリック体

ステップ8: 引用ブロックの整形

修正前:

>引用テキスト
>複数行

修正後:

> 引用テキスト
> 複数行

ルール:

> の後にスペースを1つ
引用ブロックの前後に1行の空行

ステップ9: 水平線の統一

以下のいずれかに統一：

---

または

***

ルール:

プロジェクト全体で統一
水平線の前後に1行の空行

ステップ10: 最終チェック

行末の余分なスペースを削除
連続する空行を1行にまとめる
ファイル末尾に改行を1つ追加
全角・半角の統一確認

Formatting Rules Summary

# ✅ 正しいフォーマット

# H1タイトル

## H2メインセクション

ここに本文。段落の前後には空行を入れる。

### H3サブセクション

* リスト項目1
  * サブ項目（2スペースインデント）
* リスト項目2

```javascript
const code = "言語指定あり";

列1	列2
A	B

引用テキスト

次のセクション...


## Best Practices

### スタイルガイドの一貫性

プロジェクト全体で以下を統一：

1. **見出しスタイル**: ATXスタイル（`# 見出し`）を推奨
2. **リストマーカー**: `*` または `-` のどちらかに統一
3. **コードブロック**: 必ず言語指定
4. **インデント**: 2スペースまたは4スペースに統一
5. **改行**: UNIX形式（LF）を推奨

### 日本語と英語の混在ルール

```markdown
【推奨】
日本語と English の間にはスペースを入れる。
数字の 100 個も同様。

【非推奨】
日本語とEnglishの間にスペースなし。

リンクの管理

<!-- 記事内リンク -->
[セクション1へ](#section-1)

<!-- 外部リンク -->
[公式サイト](https://example.com)

<!-- 参照リンク（長いURLの場合） -->
詳細は[こちら][ref1]を参照。

[ref1]: https://very-long-url.com/...

Examples

使用例1: ブログ記事の整形

User: "このMarkdownファイルを整形してください"

Skill実行:
1. ファイル読み込み（Read）
2. 見出し構造分析
3. コードブロックに言語指定追加
4. リストのインデント統一
5. 表の整列
6. 整形済みファイルを保存（Edit）

使用例2: README.mdの一括整形

User: "プロジェクト内の全てのMarkdownファイルを統一フォーマットにしてください"

Skill実行:
1. Markdownファイルを検索（*.md）
2. 各ファイルを順次整形
3. スタイルガイドに従って統一
4. 整形レポート作成

Linter Integration

markdownlintなどのツールと連携可能：

# markdownlintのインストール
npm install -g markdownlint-cli

# 整形前の検証
markdownlint *.md

# 自動修正
markdownlint --fix *.md

Configuration Example

.markdownlint.json の推奨設定：

{
  "default": true,
  "MD013": false,
  "MD033": {
    "allowed_elements": ["img", "details", "summary"]
  },
  "MD041": false
}

Formatting Checklist

整形完了前に確認：

H1が1つだけ
見出しレベルが階層的
コードブロックに言語指定
リストのインデント統一（2スペース）
表が整列
画像にalt属性
リンクが有効
行末の余分なスペース削除
ファイル末尾に改行

Version History

v1.0.0 (2025-01-26): 初期リリース

markdown-formatter

When & Why to Use This Skill

Use Cases

Markdown Formatter

Instructions

ステップ1: ファイル読み込みと分析

ステップ2: 見出し構造の最適化

ステップ3: コードブロックの整形

ステップ4: リストの整形

ステップ5: 表の整列

ステップ6: リンクの整形

ステップ7: 画像の整形

ステップ8: 引用ブロックの整形

ステップ9: 水平線の統一

ステップ10: 最終チェック

Formatting Rules Summary

リンクの管理

Examples

使用例1: ブログ記事の整形

使用例2: README.mdの一括整形

Linter Integration

Configuration Example

Formatting Checklist

Version History