メインコンテンツへスキップ
見出し画像

【30分で構築】Claude Code Skills で社内ドキュメント自動生成する全手順

    社内ドキュメントのテンプレ埋めに毎週3時間取られていた(議事録週2本+週次レポート1本の準備時間)。Claude Code Skills を30分で1つ作ったら、その作業が引数1行で済むようになった。

    この記事でわかること: Claude Code の Skills 機能で、議事録・週次レポート・要件定義書のような「毎回同じ準備をしている文書」をスラッシュコマンド化する全手順。30分で1つ目のSkillが動きます。

    非エンジニアでAIツールを業務に活かしたい方向けです。プログラミング経験は不要ですが、Claude Code をインストールしてターミナルで何度か触ったことがある状態を想定しています。

    このnoteでは、非エンジニアでも再現できるAI活用法を実測データつきで解説しています。

    Claude Code Skills でできるようになること

    Skills は Claude Code 専用のカスタム命令セットです。`.claude/skills/{名前}/SKILL.md` というファイルを置くだけで、`/{名前}` というスラッシュコマンドが Claude Code 内で使えるようになります。

    例えば私が今動かしている note 記事制作プロジェクトでは、4つのSkillを運用しています。それぞれの規模感も書いておきます。

    • `/draft` — 記事の下書き生成(テンプレ読み込み→本文生成→保存まで自動)。SKILL.md 104行+テンプレ6種類(howto/practice/trend/tips/paid-recipe/x_post)

    • `/polish` — 公開前の校正・SEO最適化・E-E-A-T評価。SKILL.md 83行

    • `/tweet` — X告知ツイートの生成と投稿。SKILL.md 49行

    • `/thumbnail` — サムネイル画像の自動生成。SKILL.md 85行

    合計 321 行+テンプレ6種。3ヶ月運用で計15回ほど SKILL.md を書き直しました。

    以前は「テンプレートを開く→記事タイプに応じてフォーマット調整→AIに指示を貼り付ける→保存」という流れを毎回手作業でやっていました。1記事あたり準備だけで30分以上かかっていた工程が、いまは `/draft howto 「テーマ」 「キーポイント」` の1行(実行から下書き完成まで約2分)で動き出します。

    社内ドキュメントなら、議事録テンプレ、週次レポート、要件定義書、顧客提案書のたたき台、面談記録あたりが向きます。要するに「書く前に毎回同じ準備をしている文書」全部が対象です。

    Claude Code Skills の前提条件

    • Claude Code(CLI版)がローカルにインストール済み

    • ターミナルで `claude` コマンドが動く

    • git をインストールしている(チーム配布する場合)

    • ドキュメントテンプレートが手元にある(Markdown 推奨)

    Claude Code Pro/Max プラン、もしくは Claude API キー経由のいずれかの契約が必要です。私は月$20の Pro プランで運用しています。

    Skills 構築時の実行環境

    • OS: macOS Sequoia 15.x

    • Claude Code: 2.x 系

    • エディタ: VS Code(ファイル編集用)

    • 運用状況: 4つの Skill を git 管理、運用開始 2026年3月(約3ヶ月運用中)

    Claude Code Skills の構築 5ステップ

    Step 1: .claude/skills/ ディレクトリを作成する

    プロジェクトのルート(チームで共有したいリポジトリのトップ)で、以下のディレクトリを作ります。

    mkdir -p .claude/skills/weekly-report

    `weekly-report` の部分が、そのままスラッシュコマンド名 `/weekly-report` になります。命名は英小文字+ハイフン推奨です。日本語名は Claude Code 側の認識が不安定になるので避けてください。

    Step 2: SKILL.md を書く

    作成したディレクトリの中に `SKILL.md` を置きます。これがSkillの本体です。

    ---
    name: weekly-report
    description: 週次レポートを定型フォーマットで生成する
    argument-hint: <週番号> <主要トピック>
    allowed-tools: Read, Write, Glob, Bash
    ---
    
    # 週次レポート生成
    
    `reports/` ディレクトリに、指定された週番号の週次レポートを生成する。
    
    ## 手順
    
    1. Bash で `date +%Y-%m-%d` を実行し、今日の日付を取得する
    2. `templates/weekly-report.md` を Read で読み込む
    3. テンプレートに従い、第$1週・主要トピック「$2」のレポートを生成する
    4. 以下の frontmatter を付与する: title, week, date, status
    5. `reports/{TODAY}-week{$1}.md` に Write で保存する
    
    ## 品質基準
    - 数値は出典を明記する
    - 「課題」セクションは必ず1つ以上含める
    - 抽象的な感想ではなく、来週のアクションを3つ書く

    frontmatter(先頭の `---` で囲まれた部分)の各項目には明確な役割があります。

    • name: スラッシュコマンド名。ディレクトリ名と一致させる

    • description: スキル一覧に表示される説明。Claude Code が「どのスキルを呼ぶか」を判断する材料にもなる

    • argument-hint: 引数のヒント。`<>` で括った文字列がそのままユーザーに表示される

    • allowed-tools: このスキルが使えるツール。最小権限の原則(必要最低限のツールしか許可しない)で、Read/Write/Bash など必要なものだけを列挙する

    Step 3: テンプレートと参照ファイルを用意する

    SKILL.md の中で「`templates/weekly-report.md` を読み込む」と書いた場合、そのファイルを実際に作ります。

    mkdir -p templates reports
    touch templates/weekly-report.md

    テンプレートには、社内の標準フォーマットをそのまま貼り付けます。見出し構造、必須セクション、文体ルールなど、いつもAIに口頭で指示している内容を全部ファイルに書き出す感覚です。

    ここが Skills の肝です。「いつも口頭で指示している前提」をファイルに固定することで、毎回同じ品質で出力されるようになります。私は最初、ここを軽視して SKILL.md だけで動かそうとして失敗しました。テンプレートを別ファイルに切り出した瞬間に、出力の安定度が一段上がります。

    Step 4: Claude Code で動作確認する

    プロジェクトのルートで Claude Code を起動し、新しいSkillが認識されているか確認します。

    claude
    > /

    `/` を入力すると、利用可能なスキル一覧が表示されます。`weekly-report` がリストに出ていればOK。

    次に実際に呼びます。

    > /weekly-report 24 「Q2レビュー準備、新人オンボーディング」

    引数は `argument-hint` の通りに渡します。Claude Code が SKILL.md を読み、テンプレートを参照しながらレポートを生成します。

    私は初回の動作確認で必ず「テンプレ通りの構造で出力されたか」と「frontmatter の日付が `date +%Y-%m-%d` の値と一致しているか」の2点をチェックしています。ここがズレると、後段の校正処理や別Skillへの引き渡しが全部壊れます。

    Step 5: git でチーム共有する

    ここまで作ったファイルを git にコミットしてプッシュすれば、チームメンバーが `git pull` するだけで全員の Claude Code に同じスキルが入ります。

    git add .claude/skills/ templates/
    git commit -m "feat: add weekly-report skill"
    git push

    `.claude/skills/` 配下は git 管理が前提です。Notion でテンプレ集を共有していた時代は「テンプレ更新したから見て」というSlack通知と「最新版どこですか」という質問が常時発生していました。Skills に移行してからこの2つがゼロになりました。

    Claude Code Skills の動作トラブルと対処法

    スキル一覧に表示されない

    • 原因: SKILL.md の frontmatter(`---` で囲まれた部分)が正しくない

    • 対処法: `name`、`description`、`allowed-tools` の3つが入っているか確認。インデントは半角スペース2つ、`:` の後は半角スペース必須。YAML 仕様上タブ文字は禁止されているため、エディタの「タブをスペースに変換」設定をオンにしておくのが安全です

    `allowed-tools` で許可していないツールが必要になる

    • 原因: 手順の中で WebFetch や AskUserQuestion などの追加ツールを使おうとした

    • 対処法: SKILL.md の `allowed-tools` に追記する。一部のツール(WebFetch、AskUserQuestion、TaskCreate など)はセッション開始時にロードされていないため、SKILL.md の手順内に「ToolSearch で○○をロードする」と明記しておくと安定します。私は WebFetch を使う Skill を最初に作った時、ToolSearch の記述を入れ忘れて「URLが取得できません」というエラーで30分詰まりました

    引数を渡しても無視される

    • 原因: argument-hint はあくまでヒントで、引数を強制しない

    • 対処法: SKILL.md の手順内で `$1`、`$2` を必ず参照すること。引数が空の場合の挙動(「未指定なら選択肢を提示する」など)も明記しておくと、モデルが勝手に進めるのを防げます

    注意点・Claude Code Skills でハマりやすいポイント

    運用初期に私が実際にハマったポイントです。

    1. スキルの粒度を間違えると、結局AIに口頭で指示することになる

    最初に作った `/article-write` という巨大スキルは「記事タイプ判断→テンプレ選択→生成→保存→投稿」を全部やろうとして失敗しました。当時の SKILL.md は約 400 行、条件分岐が 5 箇所。途中で挙動が分岐するたびにモデルが迷い、毎回違う出力になりました。1スキル1責務に分け、`/draft`(生成)と `/polish`(校正)と `/tweet`(投稿)を別々にして、各 SKILL.md を 50〜100 行に収めたら安定しました。

    2. テンプレートを最新化しないと Skill の価値が下がる

    社内ドキュメントのフォーマットが変わったとき、テンプレートファイルを更新しないと古い形式で出力されます。私は git 管理しているので、フォーマット変更時は templates/ 配下も同じPRで更新するルールにしました。

    3. モデルの揺らぎは完全には消せない

    SKILL.md に「冒頭3行で数字を提示せよ」と書いても、出力されない時があります。100%の制御は無理だと割り切り、私は校正用の別Skill側で「数字が冒頭にあるか」をチェックするようにして、二段構えにしています。

    Claude Code Skills の制約 5つ

    売り手の都合のいい話だけ書いても信頼されないので、実際に運用してわかった制約を正直に並べます。仕様の詳細は Anthropic 公式ドキュメント も参照してください。

    1. Claude Code 環境必須

    ChatGPT や Cursor、Windsurf などでは動きません。チーム全員が Claude Code を使っている前提が必要です。Cursor 主体のチームなら Cursor Rules を選ぶべきです。

    2. プロジェクト単位の管理が原則

    `.claude/skills/` はプロジェクト(リポジトリ)単位なので、複数プロジェクトで同じスキルを使うには、グローバルの `~/.claude/skills/` に置くか、各リポジトリにコピーする必要があります。私は「全プロジェクト共通のもの(git操作系、レビュー系)はグローバル、ドメイン固有のものはプロジェクト」で使い分けています。

    3. deferred tools の扱いが直感的でない

    AskUserQuestion や WebFetch などの一部ツールは、SKILL.md の allowed-tools に書いても自動ロードされないことがあります。手順内で ToolSearch を呼ぶ記述が必要になるケースがあり、最初はここで詰まりました。

    4. 非エンジニアへの配布ハードルが残る

    git pull が習慣化していないメンバーにはやや厳しい。私のチームでは、エンジニアがPRをマージしたあとSlackで「pull してください」と通知する運用にしています。完全自動配布の仕組みはまだありません。

    5. ライセンスとセキュリティの管理は別途必要

    SKILL.md に機密プロンプトや社外秘情報を書いてリポジトリにプッシュすると漏れます。`.claude/skills/` を git 管理する場合は、リポジトリ可視性(private/public)と内容の精査をワンセットで運用してください。公開リポジトリで Skills を共有する際は、社内固有名詞を一切含めないルールにしています。

    Claude Code Skills と他ツールの比較(Custom GPT / MCP / Notion / Cursor Rules)

    似た目的のツールが他にもあるので、私が選定時に検討した4つを公平に並べます。

    Custom GPT / GPT Actions(OpenAI)

    ブラウザだけで使える手軽さが最大の強み。ただし「ローカルファイルを読んで書き戻す」用途は、GPT単体では難しい。ChatGPT Business 以上の契約とAPI連携の知識が必要になります。Web完結のFAQボットや問い合わせフォームのような用途なら Custom GPT、ローカルファイル操作を伴うドキュメント生成なら Skills、と棲み分けるのが現実的です。

    MCP(Model Context Protocol)サーバー

    Claude Code から外部ツール・データベースに接続する仕組み。Skills が「定型タスクの自動化」だとすると、MCP は「外部システム連携」が本領です。今回のような社内ドキュメント生成だと Skills だけで足りるケースが多く、MCP まで構築する必要はないことが多いです。

    プロンプトテンプレート集(Notion/Obsidian保管)

    最も低コストの選択肢。ただし「テンプレ集を毎回コピペする手間」「テンプレが古くなっても気づかない」という運用課題が残ります。私はテンプレ集→Skills へ移行して、コピペ作業がゼロになりました。

    Cursor Rules / Windsurf Cascade Rules

    他のAIエディタにも類似機能はあります。チームが Cursor 主体ならそちらを選ぶべきです。Skills の独自価値は「Claude Code のスラッシュコマンドとして呼べる」一点に集約されます。

    次にやるべきこと

    今日からできる具体的なアクションを3つに絞ります。

    1. 手元のドキュメントテンプレート1つを `.claude/skills/{名前}/templates/` に置く — まずはこの一歩。30分は確保してください

    2. SKILL.md の雛形を、本記事 Step 2 のコードからコピーして書き換える — 完璧を目指さず、まず動くものを作る

    3. 3日以内に同僚1人に共有して、フィードバックをもらう — Skill は一人で作っても、運用は複数人。早めに見せる

    私自身、最初に作った Skill は粒度を間違えて作り直しました。完璧な設計より、まず動かしてから直す方が早いです。

    次回のAIツール検証も見逃さないように、フォローで応援お願いします。 Claude Code を含む実務AI活用ノートを毎週更新しています。

    この記事が参考になったら、スキとフォローで応援お願いします。

    関連記事

     
     
    「AI、実際どこまで仕事で使えるの?」を非エンジニア目線で検証しています。ChatGPT・Claude・Geminiを実務で試して、使えた/ダメだったを実測と失敗談つきで正直に書きます。

    あなたへのおすすめ