system-spec-harness

skills

skills は、Claude Code を強化する plugin 群 (機能拡張パッケージ) です。Claude Code に「スキルを作る」「品質を検査する」「非エンジニアからヒアリングする」といった能力を後から追加できます。

plugin (プラグイン): Claude Code 本体を書き換えずに、後から機能を足すための小さな部品。スマートフォンアプリのようなものと考えてください。

---

このドキュメントの読み方

• インストールしたい方 → Part 1: インストール手順 を順番に実行
• API キーを設定したい方 → Part 2: API キーの安全な保存 (Keychain)
• どの plugin を入れるか迷う方 → Part 3: plugin 一覧と役割
• plugin の中身を理解したい方 → Part 4: plugin の仕組み

---

Part 1: インストール手順

このリポジトリは GitHub の marketplace から直接インストールします。リポジトリを手元に clone する必要はありません。

marketplace (マーケットプレイス): plugin が並んでいるお店のような場所。skills 自体が 1 つのお店で、その中に複数の plugin が並んでいます。

Step 0: 前提を確認する

Claude Code CLI が動く環境が必要です。

claude --version
# → claude code x.y.z が表示されれば OK

❌ 入っていなければ公式ガイド https://docs.claude.com/claude-code/setup を参照してください。

Step 1: marketplace を追加する

Claude Code セッションを起動し、以下を打ちます。

/plugin marketplace add manju/skills

これで「skills というお店」が Claude Code に登録されます。

✅ 確認:

/plugin marketplace list

skills が表示されれば成功。

Step 2: plugin をインストールする

用途に合わせて選んでください。まずは最小構成から始めることをおすすめします。

2a. 最小構成 (Skill を作りたいだけ)

/plugin install skill-creator@skills
/plugin install prompt-creator@skills

2b. 標準構成 (品質検査も使う)

最小構成 + governance (運用検査) を追加:

/plugin install skill-governance-config@skills
/plugin install skill-governance-lint@skills
/plugin install skill-governance-hooks@skills

2c. フル構成 (全部入り)

すべての plugin をまとめて入れる場合は bundle (束) を使います。

/plugin install skills-full@skills

bundle (バンドル): 複数の plugin を 1 行でまとめて入れるためのセット。skills-minimal / skills-intake などもあります。

✅ 確認:

/plugin list

入れた plugin が installed と表示されれば成功。

Step 3: 動作確認

Claude Code セッション内で以下を打ち、補完候補に出ることを確認します。

/skill-creator:run-skill-create

実行が始まれば成功。一旦キャンセル (Ctrl-C または「やめる」と返答) して構いません。

Step 4: アップデート / アンインストール

# アップデート
/plugin marketplace update skills
/plugin update skill-creator@skills

# アンインストール
/plugin uninstall skill-creator@skills
/plugin marketplace remove skills

トラブルシュート

症状	対処
/plugin コマンドが効かない	Claude Code のバージョンが古い可能性。claude --version を確認し最新化
marketplace add で not found	リポジトリ名のスペルを確認。manju/skills が正しい
install で authentication failed	private リポジトリの可能性。gh auth login でログイン
Skill が補完に出ない	/plugin list で installed か確認、無ければ再 install

---

Part 2: API キーの安全な保存 (Keychain)

skill-intake plugin など、外部サービス (Notion 等) を呼ぶ plugin は API キー (秘密の合言葉) が必要です。

skills では API キーを コード・ファイル・環境変数に書かず、Mac の Keychain (キーチェーン) に保存する方針を取っています。

Keychain (キーチェーン): Mac に標準で入っている、パスワードや秘密情報を安全に保管してくれる金庫のような仕組み。Safari のパスワード保存にも使われています。

なぜ Keychain を使うのか?

• .env ファイルや環境変数に書くと 間違って git に commit してしまう事故が起きやすい
• Keychain は OS レベルで暗号化されており、他人が覗けない
• Mac ログイン中だけ取り出せるので、自動で守られる

Step 1: Keychain に API キーを登録する

例として Notion の API キー (Internal Integration Token) を登録します。Mac のターミナルで実行:

security add-generic-password \
  -s "notion-api-key.skills" \
  -a "skills" \
  -w "ntn_xxxxxxxxxxxxxxxxxxx" \
  -U

• -s … サービス名 (=Keychain 内の項目名。plugin が読みに行く名前)
• -a … アカウント名 (=どの用途で使うかの区別)
• -w … 実際の API キー (この値だけは秘密に)
• -U … 既にあれば更新

💡 上のコマンドは履歴に API キーが残ります。-w を省略するとターミナルが対話的にキーを聞いてくれるので、その方が安全です。

Step 2: 登録できたか確認

security find-generic-password -s "notion-api-key.skills" -a "skills" >/dev/null

終了コードが 0 なら登録成功。API キー本体は表示しません。

Step 3: plugin が読みに行くサービス名

各 plugin が期待する Keychain のサービス名は以下です。この名前で登録してください。

plugin	サービス名 (-s)	アカウント名 (-a)	用途
skill-intake	notion-api-key.skills	skills	Notion ページ作成

このリポジトリでは .notion-config.json の keychain_service / keychain_account が正本です。

環境変数で上書きしたい場合

CI など Keychain が使えない環境では、以下の環境変数で上書きできます。

export NOTION_CONFIG_PATH="/path/to/.notion-config.json"

通常の利用では上書き不要です。

---

Part 3: plugin 一覧と役割

skills には複数の plugin が入っており、それぞれ役割が分かれています。「料理に例えると」のイメージで読んでください。

中核 plugin (まず入れる)

plugin	役割	料理例
skill-creator	Skill (作業手順書) を作る・更新する・評価する司令塔	レシピを設計するシェフ
prompt-creator	Skill の中で使う「AI への指示文」を 7 層構造で作る	調味料の配合表を作る人
skill-intake	非エンジニアからヒアリングして Skill 要件を引き出す	お客様の好みを聞き取る接客係

運用検査 plugin (品質を保つ)

skill-governance-* という名前の plugin は、Skill の 品質を機械的に検査する仕組み を提供します。手作りの料理が衛生基準を満たしているか確認する保健所のような役割です。