%%{ init: {
'theme': 'default',
'themeVariables': {
'fontFamily': 'Meiryo'
},
'sequence': {
'noteMargin': 8,
'messageMargin': 30
}
} }%%
sequenceDiagram
participant U as Client (CLI)
participant T as Transport
participant R as Registry
participant S as Storage
U->>U: ① manifest解析 + zip作成
U->>T: ② POST /api/publish (Bearer token)
T->>R: ③ HTTP or SSH で転送
R->>R: ④ 認証 → メタデータ抽出 → 重複チェック
R->>S: ⑤ zip + yaml + publish.log 書き込み
R-->>T: 200 OK
T-->>U: ✓ published my-skill 0.1.0
はじめてのskilltool
skilltool 101
Ryo Nakagami
2026年04月16日
SKILLTOOLユーザーマニュアル
SKILLTOOLユーザーマニュアル
SKILL + スラッシュコマンドの活用方法
なぜskilltoolが必要か？
Skillの散在 → 属人化 → 再発明のループを断ち切る
- Claude Agent Skillは個人のローカル環境に閉じがちで，チーム内の再利用が進まない
- skilltoolはSkillパッケージの publish / install / search を提供するCLI＋レジストリで，この問題を解決する
- PyPI/npmと同じ感覚でskillを扱える — 作る → 公開する → 使うのサイクルをチーム標準化する
skilltoolなしの世界 = Skillの散在 → 属人化 → 再発明
- Skillファイルが各個人の
.claude/に散在 - 「あのskill誰が持ってたっけ？」 → Slackで聞く
- 同じような機能を複数人が再発明
- バージョン管理なし，どれが最新か不明
- チームのナレッジが蓄積されず，個人の退職・異動で失われる
skilltoolありの世界 = 共有・発見・再利用のサイクル確立
検索と導入
skilltool search "docx"で即座に発見skilltool install docxでワンコマンド導入
管理と追跡
- SemVerでバージョン管理，publishログで変更追跡
- 作る人と使う人の役割分離が可能に
skilltoolの全体像
skill.mdをパッケージとして管理し，pip-likeに活用する
Skillパッケージ
skill.toml+SKILL.md- メタデータと指示書
CLI
- publish / install
- search / show / list
Transport
- HTTP (default)
- SSH (代替)
Registry
- FastAPI (認証・保存)
- Tailscale内部公開
Storage
.zip+.yaml- 監査ログ(append-only)
| skilltoolの概念 | 対応するツール | 具体的な役割 |
|---|---|---|
| Skill | 関数 / npm パッケージ | SKILL.md(指示本体) + skill.toml(メタデータ)で構成される再利用単位 |
| Registry | PyPI / npm registry | Skillの保存・検索・バージョン管理．Tailscale経由でチーム内に公開 |
| CLI | pip / npm コマンド |
skilltool install, publish, search レジストリへのインターフェース |
Skillパッケージの構造
skill.toml（何をパッケージするか） + SKILL.md（何を実行させるか）
skill.toml — パッケージマニフェスト
| フィールド | 必須 | 説明 | デフォルト |
|---|---|---|---|
name |
Yes | ^[a-z0-9][a-z0-9._-]*$ |
— |
version |
Yes | SemVer (MAJOR.MINOR.PATCH) |
— |
description |
Yes | 1行の概要（検索対象） | — |
author |
No | チーム名推奨 (e.g. team-doc) |
— |
entry |
No | Agentが読む起点ファイル | SKILL.md |
include |
No | zip同梱対象のglobパターン | [entry] |
tags |
No | 検索用ラベル | — |
SKILL.md — Claude向け指示書
# create-skill-package
新しい skilltool skill package をインタラクティブに scaffold する skill
## When to use
ユーザーが以下のような依頼をしたとき，この skill を使う:
- 「新しい skill を作りたい」
- 「skill package を作って」
## Instructions
### Step 1: ヒアリング
ユーザーに以下を確認する（既知の項目はスキップ）:
| 項目 | 必須 | 説明 |
| skill名 | Yes | ^[a-z0-9][a-z0-9._-]*$ に合致 |
| 説明 | Yes | 1行程度の短い概要 |
| author | No | チーム名を推奨 |
### Step 2: ディレクトリ作成
skill.toml と SKILL.md を生成する
### Step 3: 確認とガイド
publish 手順を案内する
## Rules
- skill.toml 形式で生成すること
- SKILL.md は大文字．entry と完全一致させる- SKILL.mdは人間向けドキュメントではなくClaudeが実行する指示書
- 曖昧さを排除し，手順・制約・エッジケースを明記する
Quick Start: インストールから動作確認まで
3ステップで完了: install → config → verify
skilltool Quick Start ワークフロー
Step 1: CLIインストール
uv tool install でGitHubリポジトリから直接インストール
Step 2: 接続設定
環境変数またはconfig.tomlでレジストリURLとトークンを設定
Step 3: 動作確認
skilltool config で設定の解決結果を確認し，skilltool search で接続テスト
Quick Start Tips
① インストール
② 接続設定（環境変数 or config.toml）
③ 設定の優先順位
- 環境変数 > config.toml > localhost自動検出 > デフォルト値
- トークンは管理者が
add-user.shで発行
CLIコマンド一覧
6コマンドでSkillパッケージのライフサイクルをカバー
検索・取得系
skilltool search "<regex>" — 正規表現でskillを検索
skilltool show <name> — メタデータ・全バージョン・publish履歴
公開・管理系
skilltool publish <dir> — skillをレジストリに公開
skilltool list — ローカルにinstall済みのskillを一覧
publishの内部フロー
CLIからStorageまで — 1コマンドの裏側で何が起きるか
skilltool publish ./dir/を実行すると，CLIがmanifest解析 → zip作成 → Transport経由でRegistryに送信- HTTPとSSHの2つのTransportが選択可能だが，内部では同じ
publish_logic()を呼ぶ
実践: skillの作成からClaudeでの利用まで
create → publish → search → install → use の一気通貫デモ
Step 1: パッケージを作成する
skill.toml（メタデータ）とSKILL.md（Claude向け指示書）を含むディレクトリを作成- 例:
my-first-skill/{skill.toml, SKILL.md}
Step 2: Registryにpublish
skilltool publish ./my-first-skill/
Step 3: チームメンバーがsearch → install
skilltool install my-first-skillでローカルにダウンロード- バージョン指定:
skilltool install my-first-skill --version 0.1.0
Step 4: Claude Codeで利用する
cp -r ./my-first-skill .claude/commands/でプロジェクトに配置/my-first-skillでスラッシュコマンドとして利用可能
ブラウザUIによるRegistry操作
CLIだけでなく，ブラウザからもパッケージの検索・詳細確認・publish が可能
- Registryサーバー（FastAPI）はHTMLページも提供しており，
http://100.x.x.x:8765/にブラウザでアクセスするだけで利用可能 - CLIと同じデータを参照するため，ブラウザで検索→ CLIで
installといった流れも可能
ブラウザUI 3つの機能
パッケージ検索 (/)
- トップページで Name / Tag / Description の正規表現フィルタが利用可能
- 一覧表から各パッケージの詳細ページへリンク
パッケージ詳細・ダウンロード (/packages/{name})
- メタデータ（Author，Tags，Published by）を確認
- 全バージョン一覧から任意のバージョンのzipを直接ダウンロード
skilltool installコマンド例も表示
ブラウザpublish (/publish)
- トークンとzipファイルを指定してブラウザからpublish可能
- CLIが使えない環境でもブラウザ経由でパッケージを公開できる
ブラウザUIスクリーンショット
SKILL + スラッシュコマンドの活用方法
SKILLTOOLユーザーマニュアル
SKILL + スラッシュコマンドの活用方法
Claude Codeスラッシュコマンドの2形式
SKILLパッケージは.claude/skills/ または .claude/commands/ に配置する
- Claude CodeのスラッシュコマンドはSkill形式（推奨）とcommands形式（レガシー）の2種類
- 自動起動・補助ファイル同梱が必要ならSkill形式を選ぶ（skilltoolで配布されるskillもこの形式）
- 配置先を
.claude/直下にしないよう注意． 必ずskills/またはcommands/サブディレクトリが必要
2形式の比較
| 項目 | Skill形式 (推奨) | commands形式 |
|---|---|---|
| 配置場所 | .claude/skills/<name>/SKILL.md |
.claude/commands/<name>.md |
| ファイル名 | SKILL.md (大文字必須) |
任意 (<name>.md) |
手動起動 /name |
✅ | ✅ |
| 自動起動 | ✅ description連動 | ❌ |
| 補助ファイル | ✅ 複数ファイルOK | ❌ 単一ファイル |
| 用途 | 複雑な指示書・Skill | 簡単なプロンプト |
FAQ: よくあるハマりどころ
skilltool × Claude Code 編
Q1: skill.toml と SKILL.md の関係は？
skill.tomlはskilltool独自のマニフェストで，パッケージ化・配布のために使う- Claude Code標準では
skill.tomlは読まれない — すべての設定はSKILL.mdのfrontmatterに書く
Q2: skill.md (小文字) で認識されない
Q3: Skillと同名のcommandsがある
優先順位は下記のとおり:
- 形式: Skill > commands
- スコープ:
enterprise > ~/.claude/ > .claude/
配置・設定 編
Q4: コマンドが認識されない
.claude/直下ではなくskills/またはcommands/サブディレクトリに配置しているか- セッション中に新規作成した場合は Claude Code を再起動
Q5: @file 指定のパス基準は？
Regmonkey Presentation. ©Ryo Nakagami. All rights reserved.