Skillを自作する：Options活用編

claude-code 101

Ryo Nakagami

2026年04月29日

Index

regmonkey_index:
  title_fontsize: 1.1em
  bullet_fontsize: 0.85em
  children:
    - title: 1. メタデータの全体像
      description:
        - frontmatter は <strong>6 フィールド</strong>．必須は name と description のみ
        - license・compatibility・allowed-tools・model はオプションの強化要素
      width: [40, 60]
    - title: 2. allowed-tools
      description:
        - 良い description は <strong>「何をする」+「いつ使う」</strong>の二点を含む
        - allowed-tools で <strong>使えるツールを絞り</strong>，読み取り専用 Skill を作れる
      width: [40, 60]
    - title: 3. Progressive Disclosure
      description:
        - SKILL.md は <strong>500 行以内</strong>．scripts・references・assets に分割
        - Scripts は<strong>実行のみ</strong>．本体は context を消費せず出力だけが乗る
        - 既存ツールは <strong>uvx・npx</strong>，独自処理は <strong>PEP 723</strong> で同梱
        - <strong>非対話・--help・構造化出力・冪等性</strong>を満たすよう設計する
      width: [40, 60]
    - title: 4. バリデーションチェック
      description:
        - <strong>シンプルから始め</strong>，必要に応じて高度な field を追加する
        - 500 行を超えたら分割を検討．description は磨き続ける
        - <strong>skills-ref</strong> CLI で公開前に frontmatter と構造をバリデーション
      width: [40, 60]

メタデータの全体像

メタデータの全体像
allowed-tools
Progressive Disclosure
バリデーションチェック

任意フィールドを活用することでSKILL運用力を底上げする

制約や権限を宣言，context windowsの削減したい場面でOptionsを活用する

SKILL.md の frontmatter フィールド一覧表（name・description・license・compatibility・metadata・allowed-tools）

必須フィールド

name：識別子．最大 64 文字．小文字・数字・ハイフンのみ
description：マッチング基準．最大 1024 文字．非空

任意フィールド

license：ライセンス名 or バンドルファイル参照
compatibility：環境要件（最大 500 文字）
metadata：任意の key-value マッピング
allowed-tools：使用可能ツール（実験的）
model：使用するモデルの指定

allowed-tools

メタデータの全体像
allowed-tools
Progressive Disclosure
バリデーションチェック

allowed-tools で読み取り専用 Skill を実現できる

セキュリティ用途や副作用を避けたい workflow で，Claude の権限に明示的なガードレールを敷く

最小例：onboarding Skill

---
name: codebase-onboarding
description: Helps new developers
  understand how the system works.
allowed-tools: Read, Grep, Glob, Bash
model: sonnet
---

When a new developer asks how the
system works:

1. Use Glob to map the directory tree
2. Use Grep to locate entry points
3. Read key modules and explain

allowed-tools の効果

列挙したツールは 確認なしで利用可(= without permission)
列挙外のツール（Edit，Write 等）は 使えない
省略時は通常の権限モデルが適用される

使いどころ

調査・要約など 書き換えを伴わない作業
セキュリティ感度が高い workflow
「うっかり Edit が走る」事故の予防

Progressive Disclosure

メタデータの全体像
allowed-tools
Progressive Disclosure
バリデーションチェック

SKILL.md は 500 行以内．詳細はサブディレクトリに逃がす

全部を SKILL.md に詰めると context を圧迫する．本文は目次に徹し，詳細は別ファイルへ

codebase-onboarding skill のディレクトリツリー（assets/・references/・scripts/・SKILL.md）

3 つのオプションディレクトリ

scripts/：実行可能コード．自己完結 or 依存を明記
references/：追加ドキュメント．REFERENCE.md FORMS.md などを置き，必要なときだけ読ませる
assets/：静的リソース．テンプレ・図・データファイル

なぜ分離するのか

全部を SKILL.md に詰めるとコンテキストを圧迫しメンテも辛い
個別ファイルはロード対象に含めるかを Claude が判断できる
SKILL.md は目次としての役割に徹し，詳細は別ファイルに逃がす

Scripts は実行のみで context を消費しない

本体は読まれず，実行結果（出力）だけが context に乗る．コードで書ける処理は scripts へ

SKILL.md には「スクリプトを実行する」と書く．読ませない
実行結果（出力）だけが context に乗る．本体ファイルの行数は無関係
検証・データ変換・定型処理などコードで書いた方が信頼できる作業に最適

向いている処理

環境バリデーション（依存・バージョンチェック）
一貫性が必要なデータ変換
「コード化した方が安定する」定型操作

Skill 設計の判断軸

自然言語で Claude に毎回考えさせる？ → SKILL.md 本文に書く
決まった処理を毎回流す？ → scripts/ に置いて実行を指示する

既存ツールは uvx・npx で呼び，独自処理は scripts/ に同梱する

依存解決を実行時に任せれば環境構築が要らない．独自ロジックは PEP 723 で依存をインライン宣言

One-off：既存ツールをそのまま呼ぶ

uvx ruff@0.8.0 check .
uvx black@24.10.0 .
npx eslint@9.0.0 src/

バージョンを ピン留めして再現性を確保
前提環境は compatibility フィールドで宣言
フラグが増えて複雑化したらscripts/ へ移行

Bundled：PEP 723 で依存をインライン宣言

# /// script
# dependencies = ["beautifulsoup4>=4.12,<5"]
# ///
from bs4 import BeautifulSoup
...

uv run scripts/extract.py で隔離環境＋自動依存解決
uv lock --script で完全再現用のロックファイル生成
スキルルートからの相対パスで参照

エージェント実行を前提に「非対話・自己説明・構造化」で書く

エージェントは stdout / stderr を読んで次の行動を決める．書き方が成功率を直接左右する

① 対話プロンプトは禁止

非対話シェルでは TTY プロンプトでハングする
入力は CLI フラグ・環境変数・stdin で受ける
必須引数欠落は使い方を出して即終了

② --help で interface を自己文書化

エージェントは --help を読んでスクリプトを学ぶ
説明・フラグ・実行例を簡潔に
context を圧迫しないよう短く保つ

③ 親切なエラーメッセージ

「何がダメ・何を期待・どう直せばよいか」を1メッセージに
例：--format must be one of: json, csv, table. Received: "xml"
曖昧なエラーはエージェントの1ターン分を浪費する

④ 構造化出力を stdout，診断は stderr

JSON・CSV・TSV など 機械可読な形式
データは stdout，進捗・警告は stderr に分離
jq 等とのパイプライン合成が容易に

冪等性・dry-run・終了コードで運用上の安全装置を仕込む

エージェントはリトライする．副作用と出力サイズの暴走を抑える設計が事故を減らす

① 冪等性

エージェントはリトライ前提．何度呼ばれても結果が同じ設計に
「create if not exists」を「create and fail」より優先する

② 入力制約

曖昧な入力を推測で実行しない．推測は誤実行のもと
enum・closed set を使い，曖昧な入力は明確にエラー

③ dry-run

副作用ありの操作は未然に防ぎたい
--dry-run フラグで先にプレビューさせる

④ 意味のある終了コード

失敗の種類を区別できないと，エージェントが対処を選べない
失敗種別ごとに別 code を返し，--help に意味を明記

⑤ 安全なデフォルト

うっかり破壊的操作が走る事故を防ぐ
--confirm・--force などの明示フラグを必須化

⑥ 出力サイズの予測可能性

harness は 10〜30K 字で truncate．重要情報が消えうる
要約をデフォルトに．--offset で追加取得を許可

バリデーションチェック

メタデータの全体像
allowed-tools
Progressive Disclosure
バリデーションチェック

skills-ref CLI で公開前にバリデーションする

frontmatter のスキーマと include 構造を機械チェック．CI に載せれば壊れた Skill をマージ前で止められる

使い方

skills-ref validate ./my-skill

agentskills が提供する リファレンス実装の CLI
ディレクトリを引数に指定して実行するだけ
参考：agentskills/skills-ref