Claude CodeとCoworkで要件定義書をSkill化する手順

Claude CodeのSkillsで要件定義書を作る仕組み

Claude CodeのSkillsは、SKILL.mdという1つのMarkdownファイルに手順を書いておくと、Claudeがそれをツールキットとして読み込む仕組みです。/skill-nameで自分から呼び出すことも、会話の内容に合わせてClaudeが自動で選ぶこともできます。

要件定義書はこの仕組みと相性が良い作業です。背景整理・スコープ確定・機能要件の洗い出し・受け入れ基準の作成という決まった手順を、毎回チャットに書き直すのではなくSKILL.mdに1回だけ固定できます。手順が長くても、Skillの本文は呼び出されたときだけ読み込まれるため、無関係な作業のセッションでコストを払うことはありません。

Skillsと同じ拡張の枠には、サブエージェントやHooks、MCPもあります。4つの機構の役割の違いはClaude Code SkillsとMCPの違いで扱っていますが、要件定義のような「手順を再利用したい」ケースの第一候補はSkillsです。

要件定義書Skillを作る前提条件

保存場所によって、Skillが使える範囲が変わります。個人用の~/.claude/skills/に置けば自分の全プロジェクトで使え、プロジェクトの.claude/skills/にコミットすればチーム全員が同じSkillを使えます。要件定義書のように組織のフォーマットを揃えたい成果物は、プロジェクト側への配置が向いています。

Skillsそのものに専用料金はありません。課金が発生するとすれば実行環境側のプラン料金で、Claude.ai・Claude Code・APIで構造が異なります。詳しい条件はClaude Skills料金にまとめています。

CoworkでSkillsを使う場合は前提が1つ増えます。Coworkが読み込むSkillの範囲はClaude CodeのCLIとは別物で、詳しい条件は手順4で扱います。

要件定義書の作成自体は、ファイルを読んだり書いたりするツールが無くても成立します。既存の資料を見ずに会話の内容だけから作るなら、フロントマターにallowed-toolsを書かない最小構成でも動きます。ファイル保存まで任せる場合のツール権限は、保存の節で扱います。

手順1: SKILL.mdの雛形を作成する

まず、プロジェクトの.claude/skills/配下にディレクトリを作ります。

mkdir -p .claude/skills/requirements-doc

次にSKILL.md本体を作ります。フロントマターのdescriptionには、実際にユーザーが使いそうな言い回しを含めておくと、Claudeが自動で選びやすくなります。

---
name: requirements-doc
description: 要件定義書を作成する手順。新機能や新規プロジェクトの要件定義書を書きたいとき、仕様を整理したいときに使う。
argument-hint: [機能名またはプロジェクト名]
---
 
## 要件定義の手順
 
（ここに手順本文を書く。手順2で詳しく作る）

argument-hintは必須ではありませんが、/requirements-doc ログイン機能のように呼び出すときの補完ヒントとして表示されます。

手順2: 要件定義の手順を本文に落とし込む

SKILL.mdの本体には、要件定義書を書くときに毎回たどる順番をそのまま書きます。以下は最小構成の例です。

## 要件定義の手順
 
対象: $ARGUMENTS
 
1. **背景と目的**を1〜2段落で書く。なぜこの機能・プロジェクトが必要かを明記する
2. **スコープ**をDoing(やること)とNot Doing(やらないこと)に分けて箇条書きにする
3. **ステークホルダー**を一覧化し、それぞれの関心事を1行で添える
4. **機能要件**をユーザーストーリー形式(「〜として、〜したい。なぜなら〜」)で列挙する
5. **非機能要件**(性能・セキュリティ・可用性など)を該当する項目だけ書く。該当なしなら「対象外」と明記する
6. **受け入れ基準**を、各機能要件に対応する形でチェックリスト化する
7. **用語集**に、ドメイン固有の語だけを補足する
 
出力はMarkdown形式で、上記の見出し構成をそのまま使う。

$ARGUMENTSは、/requirements-doc ログイン機能のように渡した引数に置き換わるプレースホルダーです。呼び出しのたびに対象が本文へ差し込まれるので、同じSkillを機能ごとに使い回せます。

各ステップに評価語や結論を付けず、「何を書くか」だけを指示するのがポイントです。Skillの本文は一度読み込まれると会話に残り続けるため、冗長な説明を書くほど以後のターンのcontextを圧迫します。

長い会話では自動圧縮(auto-compaction)が走り、呼び出し済みのSkillは各Skillの先頭5,000トークンまでが残ります。再添付されるSkill全体の予算は25,000トークンで、新しく呼び出したものから埋まります。要件定義書Skillを序盤に使い、その後に別のSkillを何本も呼ぶと、古いほうが圧縮後に落ちることがあります。必須の項目は、先頭の5,000トークンに収めておくと安全です。

プロジェクトごとに項目を増減したいときは、このリストに書き足せば次回の呼び出しから反映されます。

呼び出し方法を選ぶ — 自動か手動か

デフォルトでは、/requirements-docと自分で入力することも、会話の流れからClaudeが自動で選ぶこともできます。要件定義書の作成は「思い立ったときに指示したい」作業になりやすいので、自動起動を避けたいならフロントマターにdisable-model-invocation: trueを追加します。こうするとClaudeは自動では呼び出さず、明示的に/requirements-docと打ったときだけ動きます。

逆に、issueや会話の内容から要件定義書を書いてほしい場面が多いプロジェクトでは、デフォルトのままdescriptionを具体的にしておくほうが手間は減ります。どちらを選ぶかは、Skillの呼び出しに副作用があるかどうかで判断するのが目安です。次の手順のようにファイルへの保存まで自動で行わせるなら、手動起動に寄せたほうが安全です。

生成した要件定義書をファイルに保存する

手順2の本文だけでは、要件定義書はチャットの返答として表示されるだけです。docs/requirements/のようなディレクトリにファイルとして残したい場合は、SKILL.mdの指示に保存先を明記し、allowed-toolsで書き込みを許可します。

---
name: requirements-doc
description: 要件定義書を作成する手順。新機能や新規プロジェクトの要件定義書を書きたいとき、仕様を整理したいときに使う。
argument-hint: [機能名またはプロジェクト名]
allowed-tools: Bash(git log *) Edit(docs/requirements/**)
---
 
（手順2の本文に続けて）
 
最後に、生成した内容を docs/requirements/$ARGUMENTS.md として保存する。

allowed-toolsが許可するのは、Skillを呼び出したそのターンだけです。次のメッセージを送ると許可は消えます。また、リストにないツールが使えなくなるわけではなく、通常の権限設定は引き続き効きます。

ここでWrite(docs/requirements/**)と書きたくなりますが、Claude Codeはファイルパスの照合をEditとReadのルールでしか行いません。Writeにパス付きルールを書いても起動時に警告が出るだけで、実際の許可判定には使われないため、ファイル書き込みを許可したいときはEdit(path)の形で書きます。

手順3: プロジェクト情報を動的に注入する

!`command`という書き方を使うと、Skillが呼び出された瞬間にシェルコマンドを実行し、その出力を本文へ差し込めます。既存のREADMEや直近のコミット履歴を要件定義の材料として自動で読み込ませる用途に使えます。

---
name: requirements-doc
description: 要件定義書を作成する手順。新機能や新規プロジェクトの要件定義書を書きたいとき、仕様を整理したいときに使う。
argument-hint: [機能名またはプロジェクト名]
allowed-tools: Bash(git log *)
---
 
## プロジェクトの直近の変更
!`git log --oneline -10`
 
## 既存のREADME概要
!`head -n 30 README.md`
 
## 要件定義の手順
 
対象: $ARGUMENTS
 
（手順2の本文をここに続ける）

このコマンドは、手元の~/.claude/skills/やプロジェクトの.claude/skills/から呼び出したときに実行されます。routineなどのクラウドセッションでも実行されます。実行されないのは、Coworkと、claude.aiから同期したSkillを手元のセッションで呼び出した場合です。コマンドが失敗すると、そのSkill呼び出し全体が中断され、Claudeには本文が渡りません。エラーには[stderr]の出力が含まれ、Shell command failed for pattern "..."と表示されます。

注入コマンドのstderrは標準出力に混ざって本文に入ります。READMEが無いリポジトリでhead -n 30 README.mdを使うと呼び出し全体が止まるので、既存ファイルが前提のコマンドは避けるか、失敗しない形にします。

手順4: チーム・Coworkへ共有範囲を広げる

置き場所によって、Skillが届く先と使える機能が変わります。

Coworkへ載せる手順は次のとおりです。

なお、プロジェクトの.claude/skills/を追加で読み込むのは、routineなどのクラウドセッションです。リポジトリにコミットしたSkillがそのまま使われます。

手順1の雛形に入れたargument-hintは、Claude Codeでは補完ヒントとして働きます。ただしアップロード時には、次のエラーになると公式ドキュメントに載っています。

Unexpected key(s) in SKILL.md frontmatter: argument-hint. Allowed properties are: allowed-tools, compatibility, description, license, metadata, name

CLI側のチェックでは気づけません。v2.1.287で、argument-hintを入れたSkillと外したSkillをそれぞれ別のディレクトリに置き、claude plugin validateにかけると、どちらも同じ結果でした。

claude plugin validate ./with-hint
claude plugin validate --strict ./with-hint

✔ Validation passed

--strictを付けても結果は変わりませんでした。アップロード前の点検には、このコマンドを当てにせず目視で確認します。CLIとCoworkの両方で使うSkillなら、argument-hintを省いて、引数の渡し方を本文の冒頭に書いておく構成が無難です。

有効化後も、!コマンドを書いた行は実行されず、公式がdisableSkillShellExecutionのプレースホルダーと呼ぶ固定文言に置き換わります。手順3で作ったコマンド注入つきのSkillをCoworkで使っても、git logやREADMEの中身は本文に入りません。Coworkでは、前提情報を対象の指定や会話の中で直接与えます。

CLAUDE.md・手動プロンプトとの使い分け早見表

要件定義書の作成を毎回どう指示するか、3つの方法で比較します。

CLAUDE.mdとSkillsのコスト構造の違いはCLAUDE.mdをSkillsに移行してコストを削減する方法で詳しく扱っています。要件定義のように「特定のタスクでだけ使う長い手順」は、CLAUDE.mdよりSkillへ寄せるのが基本です。

よくあるつまずきと対処

descriptionが曖昧でSkillが自動で呼ばれない。「要件定義」「仕様整理」のように、ユーザーが実際に使いそうな言葉をdescriptionに含めます。読み込まれているかは/skillsの一覧で確認できます。使い方はClaude Code /skillsコマンドの使い方にまとめています。

フロントマターのYAMLが壊れている。パースに失敗するとdescriptionが空になり、/requirements-doc自体は動いてもClaudeの自動判定からは外れます。--debug起動でパースエラーを確認できます。

編集がそのセッションに反映される条件。~/.claude/skills/・プロジェクトの.claude/skills/・--add-dirで追加したディレクトリ配下のSKILL.mdを編集・追加・削除すると、bare modeを除き再起動なしで現在のセッションに反映されます。例外は、セッション開始時に存在しなかったトップレベルのskillsディレクトリを新規に作った場合だけです。このときは監視対象に入らないため、/reload-skillsを実行します。そのディレクトリ内の以後の変更も、再起動するまでは都度/reload-skillsが必要です。反映されるのはSKILL.md本文のみで、同じフォルダがplugin構成を兼ねる場合のhooks/や.mcp.jsonの変更には/reload-pluginsが別途必要です。すでに会話に読み込まれた本文そのものは、その場では書き換わらず次回の呼び出しから新しい内容になります。

手順が長くなりすぎる。SKILL.mdは500行未満を目安にします。用語集やサンプル文例のような詳細はreference.mdのような別ファイルに切り出し、SKILL.mdからは参照だけを書きます。

Skillの数が増えると自動判定が緩む。手持ちのSkillが多いプロジェクトでは、一覧の文字数予算を超えた分からdescriptionが省略され、呼び出し頻度の低いSkillほど自動判定に使われにくくなります。要件定義書Skillをよく使うなら、優先度が下がらないよう定期的に呼び出しておくか、/doctorで一覧のコスト見積もりを確認します。

まとめ

CLIだけで使うならプロジェクトの.claude/skills/にコミットすれば足ります。Coworkでも使うなら、アップロードで弾かれるargument-hintを外し、!コマンドに頼らない本文にしておく必要があります。