Markdown 記法の基本 — Cowork のスキルファイル・指示書を書くための入門

取り組みの背景 — なぜ Markdown を学ぶのか

Cowork を使いこなしていくと、スキルファイル（SKILL.md）やプロジェクト指示書（CLAUDE.md）を自分で書く場面が増えてきます。これらのファイルはすべて Markdown（マークダウン） という記法で書かれています。

Markdown は「プレーンテキストに簡単なルールを加えるだけで、見やすい文書を作れる」軽量マークアップ言語です。HTML のように複雑なタグを覚える必要はなく、数種類の記号を覚えるだけで、見出し・箇条書き・コードブロック・リンクなどを含む構造的な文書を作成できます。

見出し（Headings）

文書に構造を持たせる最も基本的な要素が 見出し です。# の数で見出しのレベルを表します。

# 見出しレベル 1（h1）
## 見出しレベル 2（h2）
### 見出しレベル 3（h3）
#### 見出しレベル 4（h4）

スキルファイルでは、以下のような使い分けが一般的です。

• # — ドキュメント全体のタイトル（1ファイルに1つだけ）
• ## — 大きなセクションの区切り（「Step 1: 準備」「Step 2: 実行」など）
• ### — セクション内のサブ項目（「ファイル配置」「フロントマター形式」など）

実際の SKILL.md では、このように使います。

# コンテンツ自動更新スキル
 
## Step 0: リポジトリの準備
 
### システム要件
- Node.js 18 以上
- npm または yarn
 
### インストール手順
1. リポジトリをクローン
2. 依存パッケージをインストール

段落と改行

Markdown では、テキストをそのまま書けば段落になります。段落と段落の間には 空行を1行 入れます。

これは最初の段落です。
ここは同じ段落の続きとして表示されます。
 
空行を挟むと、ここから新しい段落になります。

改行したいだけの場合（段落を変えずに次の行に移る場合）は、行末に 半角スペースを2つ 入れるか、<br> タグを使います。ただし、スキルファイルでは段落ごとに空行を入れる書き方のほうが読みやすく、推奨されています。

テキストの装飾（強調）

重要な部分を目立たせるための装飾には、以下の記法を使います。

**太字（ボールド）** — 重要なキーワードや注意事項に
*斜体（イタリック）* — 用語の初出や補足説明に
~~取り消し線~~ — 廃止された情報やNG例に
`インラインコード` — コマンド名、ファイル名、変数名に

スキルファイルでは特に **太字** と `インラインコード` をよく使います。たとえば、CLAUDE.md でプロジェクトのルールを書くときは以下のようになります。

**重要**: 記事は必ず日英セットで作成してください。
`npm install` は `--ignore-scripts` オプション付きで実行します。

リスト（箇条書き・番号付き）

箇条書きリスト

行頭に -、*、+ のいずれかを付けると箇条書きリストになります。

- 項目 A
- 項目 B
- 項目 C

インデント（半角スペース2〜4つ）を入れると、入れ子のリストを作れます。

- メイン項目
  - サブ項目 1
  - サブ項目 2
    - さらに深い項目

番号付きリスト

行頭に 1.、2. のように数字とピリオドを付けます。

1. 最初のステップ
2. 次のステップ
3. 最後のステップ

スキルファイルでは、手順を順番に示すときに番号付きリストを使い、選択肢や並列の情報を示すときに箇条書きリストを使うと、読み手にとってわかりやすい文書になります。

コードブロック

技術文書で最も重要な要素のひとつが コードブロック です。バッククォート3つ（```）で囲み、言語名を指定するとシンタックスハイライトが適用されます。

```bash
npm install --prefer-offline
node scripts/generate-content.mjs
```

よく使う言語指定の例をいくつかご紹介します。

スキルファイルでは、ユーザーが実行すべきコマンドを bash ブロックで、設定ファイルの内容を json や yaml ブロックで示すのが一般的です。

# リポジトリをクローンして作業ディレクトリに移動
git clone --depth 1 git@github.com:USERNAME/REPO.git
cd repo
 
# 依存パッケージをインストール
npm install

リンクと画像

リンク

[表示テキスト](URL)

たとえば、関連する他の記事にリンクする場合は以下のようになります。

詳しくはスキル＆プラグイン入門をご覧ください。

画像

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

画像はスキルファイルではあまり使いませんが、README や運用ガイドでスクリーンショットを入れたい場合に便利です。

テーブル（表）

パイプ記号（|）とハイフン（-）で表を作成できます。

| 項目 | 説明 | デフォルト |
|------|------|-----------|
| title | 記事のタイトル | なし（必須） |
| slug | URL用のスラッグ | なし（必須） |
| level | 難易度 | beginner |

テーブルの2行目のハイフンの書き方で、列の揃え方を指定できます。

| 左揃え | 中央揃え | 右揃え |
|:-------|:--------:|-------:|
| テキスト | テキスト | テキスト |

スキルファイルでは、設定項目の一覧やエラー対応表などにテーブルを活用すると、情報が整理されて読みやすくなります。

引用とコールアウト

引用

行頭に > を付けると引用ブロックになります。

> **注意**: このスキルは確認不要で全工程を自律実行します。

スキルファイルでは、重要な注意事項や補足説明を引用ブロックに入れることが多いです。入れ子にすることもできます。

> 外側の引用
> > 内側の引用（補足説明など）

コールアウト（MDX 拡張）

Claude Lab の MDX 記事では、<Callout> コンポーネントで注意書きやヒントを強調できます。

<div class="callout callout-info"><span class="callout-icon">ℹ️</span><div>ここに補足情報を書きます。</div></div>
 
<div class="callout callout-warning"><span class="callout-icon">⚠️</span><div>ここに注意事項を書きます。</div></div>

水平線と区切り

セクション間に区切り線を入れたい場合は、ハイフン3つ以上（---）を空行で囲みます。

## セクション A の内容
 
ここまでがセクション A です。
 
---
 
## セクション B の内容
 
ここからセクション B が始まります。

スキルファイルでは、Step と Step の間に --- を入れると視覚的に区切りが明確になり、長い文書でも読みやすさを保てます。

実践 — SKILL.md のテンプレートを書いてみよう

ここまで学んだ Markdown の記法を使って、実際のスキルファイルのテンプレートを作ってみましょう。

---
name: my-custom-skill
description: "カスタムスキルの説明文をここに書く"
---
 
# マイカスタムスキル
 
このスキルは〇〇を自動化します。
 
> **注意**: 実行前に必ずバックアップを取ってください。
 
## Step 1: 準備
 
### 必要な環境
 
- Node.js 18 以上
- npm または yarn
- Git
 
### セットアップ
 
1. 作業ディレクトリに移動
2. 依存パッケージをインストール
 
```bash
cd /tmp/work
npm install

Step 2: 実行

| コマンド | 説明 | |---------|------| | npm run build | ビルドを実行 | | npm run deploy | デプロイを実行 |

エラー時の対応

| 問題 | 対処 | |------|------| | npm install 失敗 | --legacy-peer-deps を試行 | | ビルドエラー | ログを確認して原因を特定 |

このテンプレートには、見出し・箇条書き・番号付きリスト・コードブロック・テーブル・引用・水平線といった基本的な Markdown 要素がすべて含まれています。

## 便利なエディタ環境

Markdown ファイルの編集は、基本的にはどのテキストエディタでも可能です。ただし、スキルファイルや指示書の作成・管理を効率よく行うには、ファイル操作もあわせて行える環境が便利です。

Cowork 上でファイルの閲覧・編集・整理を行いたい場合は、Google の AI コードエディタ **Antigravity**（旧 Project IDX）も選択肢のひとつです。ブラウザベースの開発環境なので、ローカルに特別なソフトウェアをインストールしなくても、Markdown ファイルのプレビューや Git 操作が行えます。Antigravity の活用法については [Antigravity Lab](https://antigravitylab.net) でも詳しくご紹介しています。

もちろん、VS Code や Cursor といったローカルエディタでも Markdown のプレビュー拡張を入れれば同様の体験が得られます。自分に合った環境を選びましょう。

## まとめ

Markdown はシンプルなルールで構造的な文書を作成できる、とても実用的な記法です。Cowork でスキルファイルや指示書を書く際には、この記事でご紹介した基本的な記法を押さえておけば十分に対応できます。

最初は見出し・リスト・コードブロックの3つだけでも覚えておくと、すぐにスキルファイルを書き始められます。慣れてきたらテーブルやリンクなども取り入れて、より見やすい文書を目指してみてください。

Cowork のスキル機能についてさらに詳しく知りたい方は、Cowork で繰り返しタスクを自動化する実践テクニックや[ファイル管理とデスクトップ操作](/articles/cowork/file-management)もあわせてご覧ください。