skills/xtone__ai_development_tools
1
0
Fork 0
mirror of https://github.com/xtone/ai_development_tools.git synced 2026-09-14 20:07:12 +08:00
Code Issues Packages Projects Releases Wiki Activity
Files
feat/plugins-setup-via-plugin-command
xtone__ai_development_tools/skill_usage_tracker
T
History

README.md

Skill Usage Tracker

Claude Code用のスキル使用状況トラッキングプラグインです。スキルの使用を自動的に記録し、セッション終了時にサマリーを表示します。Notionデータベースへの同期機能も備えています。

機能

1. 自動スキル使用記録（PostToolUse フック）

スキル呼び出し時に以下の情報を自動記録します：

  • スキル名
  • タイムスタンプ
  • ユーザー情報（git config の name, email）
  • コンテキスト情報（プロジェクト名、ブランチ、リモートURL、ホスト名）

保存先: ~/.claude/hooks/logs/skill_usage.jsonl

2. セッション終了時のサマリー表示（Stop フック）

セッション終了時に使用されたスキルの一覧と回数を表示します：

📊 Skill Usage Summary
────────────────────────────────────────
  greeting-skill:greeting: 3
  backend-development:orchestrating-api-implementation: 2
────────────────────────────────────────
  Total: 5 invocations

注意: Stop フックは /exit コマンドで正常終了した場合に動作します。Ctrl+C で強制終了した場合は動作しません。

3. カスタムコマンド

/skill-stats - 統計表示

任意のタイミングでスキル使用状況を確認できます。

/skill-stats reset - データリセット

ローカルに保存されたスキル使用データをクリアします。

/skill-stats setup - Notion同期設定

Notionデータベースへの同期に必要な設定ファイルを作成します。

# 使用方法
skill-stats.js setup <skill_usage_db_id> <slash_command_db_id>

# 例
skill-stats.js setup b787567d-9565-49ac-89d4-fd2569497d15 a24187ec-c81b-4853-a6ae-d8139abffc0b

data_source_id は Notion MCP の mcp__notion__notion-fetch で取得できます。

/skill-stats sync - Notionへの同期

未同期のイベントをNotionデータベースに同期します。事前に setup で設定ファイルを作成してください。

4. Notion データベース同期

チーム全体の使用状況を集計・可視化するために、Notionデータベースへの同期機能を提供します。

セットアップ手順

  1. Notionで2つのデータベースを作成（スキーマは下記参照）
  2. /skill-stats setup でデータベースIDを設定
  3. /skill-stats sync で同期を実行

データベーススキーマ

Skill Usage Events:

プロパティ名 型 説明
Skill title スキル名
Timestamp date 実行日時
User Name rich_text git config user.name
User Email email git config user.email
System User rich_text システムユーザー名
Project rich_text プロジェクト名
Branch rich_text ブランチ名
Remote url リモートリポジトリURL
Hostname rich_text ホスト名

Slash Command Events:

プロパティ名 型 説明
Command title コマンド名
Full Command rich_text フルコマンド文字列
Source select user_prompt / slash_command_tool
Timestamp date 実行日時
User Name rich_text git config user.name
User Email email git config user.email
System User rich_text システムユーザー名
Project rich_text プロジェクト名
Branch rich_text ブランチ名
Remote url リモートリポジトリURL
Hostname rich_text ホスト名

インストール

Claude Code Marketplaceから

# マーケットプレイスにリポジトリを追加
/plugin marketplace add xtone/ai_development_tools

# プラグインをインストール
/plugin install skill-usage-tracker@xtone-ai-development-tools

収集データ

収集される情報

カテゴリ 項目 取得元
スキル スキル名 Skill ツールの入力
タイムスタンプ システム時刻
ユーザー name git config user.name
email git config user.email
system_user 環境変数 USER
コンテキスト project カレントディレクトリ名
branch git branch --show-current
remote git remote get-url origin
hostname os.hostname()
cwd カレントディレクトリのフルパス

データ形式（JSONL）

データは JSONL（JSON Lines）形式で保存されます。1行1イベントで、追記操作が効率的です。

skill_usage.jsonl:

{"skill":"greeting-skill:greeting","timestamp":"2025-12-03T02:38:45.218Z","user":{"name":"Pregum","email":"pregum.y@gmail.com","system_user":"y.hino"},"context":{"project":"ai_development_tools","branch":"feature/xxx","remote":"ssh://git@github.com/xtone/ai_development_tools.git","hostname":"XTONE-0089-YHINO.local"}}

ファイル構成

ファイル 説明
~/.claude/hooks/logs/skill_usage.jsonl スキル使用イベント
~/.claude/hooks/logs/slash_command.jsonl スラッシュコマンド使用イベント
~/.claude/hooks/logs/sync_state.json Notion同期状態
~/.claude/hooks/logs/notion_config.json Notion設定（DB ID）

プライバシーとデータの取り扱い

データの保存場所

収集されたデータは ローカルマシンのみ に保存されます。外部サーバーへの自動送信は行いません。

  • 保存先: ~/.claude/hooks/logs/
  • 送信: なし（ローカル保存のみ、Notion同期は手動実行）

データの使用目的

  • スキル使用状況の可視化・分析
  • 開発ワークフローの改善
  • チーム全体での使用傾向の把握（Notion同期時）

データの削除

# 全データを削除
/skill-stats reset

# 手動で削除
rm ~/.claude/hooks/logs/skill_usage.jsonl
rm ~/.claude/hooks/logs/slash_command.jsonl

プライバシーに関する注意

  • Git設定のユーザー名・メールアドレスが記録されます
  • リモートURLにはリポジトリ情報が含まれます
  • 機密プロジェクトで使用する場合は、データファイルの管理に注意してください
  • notion_config.json にはデータベースIDが含まれるため、.gitignore に追加することを推奨

ディレクトリ構造

skill_usage_tracker/
├── .claude-plugin/
│   ├── plugin.json           # プラグイン設定
│   └── marketplace.json      # マーケットプレイス情報
├── hooks/
│   ├── hooks.json            # フック設定
│   ├── skill_usage_counter.js # PostToolUse: スキル使用記録
│   ├── slash_command_counter.js # PostToolUse: コマンド使用記録
│   ├── user_prompt_command_counter.js # UserPromptSubmit: プロンプト内コマンド検出
│   └── skill_usage_sender.js  # Stop: サマリー表示
├── commands/
│   └── skill-stats.md        # カスタムコマンド
├── bin/
│   ├── skill-stats.js        # 統計/同期スクリプト
│   └── migrate-to-jsonl.js   # JSON→JSONL移行スクリプト
├── CHANGELOG.md
└── README.md

トラブルシューティング

ローカルデータの確認

# 最新10件のスキル使用を表示
tail -10 ~/.claude/hooks/logs/skill_usage.jsonl

# 最新10件のコマンド使用を表示
tail -10 ~/.claude/hooks/logs/slash_command.jsonl

データのリセット

/skill-stats reset

実行権限エラー（permission denied）

フックスクリプトに実行権限がない場合：

chmod +x ~/.claude/plugins/skill_usage_tracker/hooks/*.js
chmod +x ~/.claude/plugins/skill_usage_tracker/bin/*.js

Stop フックが動作しない

  • /exit コマンドで終了してください
  • Ctrl+C での強制終了時は Stop フックは実行されません
  • /skill-stats コマンドで手動確認できます

旧形式（JSON）からの移行

v0.2.0 より前のバージョンからアップグレードする場合：

# ドライラン（確認のみ）
node ~/.claude/plugins/skill-usage-tracker/bin/migrate-to-jsonl.js --dry-run

# 実際の移行
node ~/.claude/plugins/skill-usage-tracker/bin/migrate-to-jsonl.js

必要な環境

  • Claude Code 0.1.0 以上
  • Node.js 18.0.0 以上
  • Git（ユーザー情報取得用）
  • Notion MCP（同期機能を使用する場合）

作成者

HINO, Yasushi

  • Organization: XTONE

ライセンス

MIT License

Reference in New Issue View Git Blame Copy Permalink