markdownlintでSKILL.mdが自動フォーマットされない問題の対処法

はじめに

VSCodeでMarkdownを編集するにあたり、markdownlintという便利な拡張機能があります。

Markdownファイルの記法をチェックし、保存時の自動フォーマットもしてくれるツールで、ドキュメントの品質を保つために私も普段使いしています。

先日、普通のMarkdownファイルに対してはmarkdownlintが正常に動作するのに、AIエージェントに読ませるSKILL.mdのみフォーマットがされないことに気が付いたので、その原因と対処法を記しておきます。

確認環境

2026/8/17時点の以下の環境で確認しています。

VSCode 1.133
DavidAnson.vscode-markdownlint 0.62.1

事象

以下の状態を前提とします。

VSCodeにmarkdownlint拡張機能をインストールしている
settings.jsonにて、ファイル保存時の自動フォーマットを有効にし、Markdownのフォーマッタにmarkdownlintを指定している
```
{
  "editor.formatOnSave": true,
  "[markdown]": {
    "editor.defaultFormatter": "DavidAnson.vscode-markdownlint"
  }
}
```

この状態で一般的なMarkdownファイルを保存すると、markdownlintのルールに沿って自動でフォーマットが実行されます。

しかし、SKILL.mdだけは保存してもフォーマットが実行されませんでした。

試しにSKILL.mdをtest.mdのような別の名前に変えてみると問題なくフォーマットされたので、どうやらファイル名に原因があるようです。

ファイル名によって言語モードが変わる

VSCodeのステータスバー（ウィンドウ下部）の右側に、現在開いているファイルの言語モードが表示されています。

VSCodeではこの言語モードをもとに、それぞれのファイルに応じた便利な機能などを提供しているのですが、ここの値が、一般的なMarkdownファイルとSKILL.mdでは異なっています。

一般的なMarkdownファイル：「Markdown」
SKILL.md：「Skill」

VSCodeはファイルの言語モードを判定する際、拡張子だけでなくファイル名全体を見て判定をしています。

SKILL.mdというファイル名には「Skill」という言語モードが割り当てられており、一般的なMarkdownファイルとは別の言語モードのファイルとして扱われます。

参考：Visual Studio Code - Language Identifiers

markdownlint拡張機能は言語モード「Markdown」しか対象にしない

markdownlint拡張機能は、言語モードが「Markdown」のファイルだけを対象に動作します。

vscode-markdownlintのREADMEより：

By default, all files that VS Code identifies as being Markdown are scanned when they’re open in the editor.

つまり、言語モードが「Skill」であるSKILL.mdは、markdownlintの動作対象外ということになります。

なお、以下のように「Skill」の既定フォーマッタとしてmarkdownlintを指定してみましたが、解決しませんでした。

{
  "[skill]": {
    "editor.defaultFormatter": "DavidAnson.vscode-markdownlint"
  }
}

SkillなどMarkdown以外の言語モードでもmarkdownlintを適用したい、という議論はmarkdownlintのIssueにもあるようですが、現時点ではまだ対応していないようです。

解決策

SKILL.mdの言語モードを「Markdown」に変更するのが手軽な解決策になります。

VSCode左下の歯車アイコンをクリックし、「設定」をクリック
「設定」ウィンドウが開いたら、そのままの状態（「ユーザー」タブが選択された状態）で、右上の「設定（JSON）を開く」をクリック

jsonファイルが開いたら、以下を追記

{
  "files.associations": {
    "SKILL.md": "markdown"
  }
}

これで、SKILL.mdの言語モードを変更できました。一般的なMarkdownファイルと同じように扱われ、保存時に自動でフォーマットが実行されるようになります。

注意点1

上記の"files.associations"の設定は、プロジェクトリポジトリ内の.vscode/settings.jsonなどに記載することもできますが、
この設定は、このワークスペースでは適用できません。これは、含んでいるワークスペースフォルダーを直接開いたときに適用されます。
という警告が出て正常に動作しないことがあります。

上記で解説している通りユーザーの設定として追記しておけば、この警告が出ることは無いはずです。

注意点2

SKILL.mdの言語モードを「Markdown」に上書きすることによる副作用があります。

「Skill」言語モード向けに用意されたVSCodeの機能が受けられなくなります
- スキルファイルを格納しているディレクトリの名前と、スキルファイル内のフロントマターのnameが一致していない場合のエラー表示など
markdownlintは不要な空行を自動で削除してくれますが、フロントマターと最初の見出しの間の空行は削除されないようです
- 最初の見出し以降の空行は削除されます

補足

今回の方法以外では、markdownlint-cli2パッケージを利用してSKILL.mdをフォーマットすることもできます。

こちらはVSCodeの言語モードを見ておらず、指定したディレクトリにあるMarkdownファイルを名前に関係なく対象とするため、files.associationsの設定をせずともSKILL.mdをフォーマットしてくれます。

ただし、パッケージを利用するよりも、拡張機能を利用したほうが、ファイルを保存してからフォーマットが反映されるまでの時間が圧倒的に短かったです。そのため、今回は拡張機能を利用する方法を紹介しました。

以上