1k-new-skill

新しいスキルの作成

新しい Claude Code スキルを作成するときは、このワークフローに従ってください。

0) 最新のベストプラクティスを取得する（必須）

スキルの内容を作成する前に、必ず最新のドキュメントを取得して読みます。

1. スキルの概要: https://code.claude.com/docs/en/skills
2. ベストプラクティス: https://platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices

WebFetch を使ってこれらのページを取得し、先に進む前に重要なガイドラインを抽出してください。

1) スキルを既存のスキルに統合すべきか確認する（必須）

新しいスキルを作成する前に、まず内容が既存のスキルに含まれるか確認してください。

既存のスキルを確認する

ls -la .claude/skills/

統合するかどうかの判断基準

次の場合は、原則として既存のスキルに統合します。

• トピックが既存のスキルの領域と密接に関連している
• 内容が既存のスキルのサブトピックにあたる
• 類似したワークフローやパターンがすでにある
• ルールとして追加することで、関連する知識をまとめておける

次の場合は、新しいスキルを作成します。

• トピックが独立しており、既存のどのカテゴリにも当てはまらない
• 単独のスキルとして作成するだけの十分な内容がある
• トリガーとなるキーワードやユースケースが異なる
• 既存のスキルが大きくなりすぎる、または焦点がぼやける

トークン最適化に関する検討事項

既存のスキルを分割するタイミング：

スキルが大きくなりすぎて、読み込むたびに不要なトークンを消費する場合は、分割してください。以下の基準を使います。

🚨 次のいずれかに当てはまる場合は分割します。

• ファイルサイズ：リファレンスファイルが 10 KB 超、または 1000 行超
• 使用頻度の不一致：トピックが大きく異なるシナリオで使われる
• 独立したワークフロー：トピックに共通するパターンがない
• 固有のトリガーワード：トピックに、ほかのトピックとはほとんど重複しない固有のキーワードがある

✅ 次の場合はまとめておきます。

• 高い相関性：トピックが頻繁に一緒に使われる（重複率が 50% 超）
• 共通概念：共通のパターン、用語、またはワークフローがある
• ファイルサイズが小さい：すべてのリファレンスファイルが 5 KB 未満
• 自然なまとまり：ユーザーが関連するトピックとして捉える

トークン削減の計算式：

Token Savings = (Skill_Size × Probability_Not_Needed) - Split_Overhead

Where:
- Skill_Size: Total tokens in skill (SKILL.md + all references)
- Probability_Not_Needed: % of tasks that don't need this topic
- Split_Overhead: ~500-1000 tokens (new SKILL.md + metadata)

実際のコードベースの例：

元のスキル	サイズ	分割後	トークン削減率
1k-coding-patterns	15 KB（9 ファイル）	6 つの特化型スキル	90% のケースで 47-53%
1k-dev-workflows	43 KB（3 ファイル）	3 つの特化型スキル	Sentry を使わない場合は 80%

分割方法：

1. 保守的な分割（安全で、変更を最小限に抑える）：

   • 最も大きく、独立性の高いファイルだけを分割する
   • 関連するトピックはまとめておく
   • 例：43 KB のワークフローから、34 KB の Sentry 分析を分割する

2. 中程度の分割（バランス重視）：

   • 明確に異なる 3～5 個のトピックを別々のスキルに分割する
   • 中核となるパターンはまとめておく
   • 例：日付、i18n、エラー処理、クロスプラットフォーム、コード品質を分割する

3. 積極的な分割（最適化を最大限に行う）：

   • 主要なトピックごとに独立したスキルにする
   • 本当に切り離せない内容だけをまとめておく
   • 次の場合に使用します：スキルが非常に大きい（50 KB 超）、トピック間の相関性が低い

OneKey の既存スキルカテゴリー

カテゴリー	スキル	統合候補
分析／トラッキング	1k-analytics	イベントトラッキング、Mixpanel、LogToServer、defaultLogger
アーキテクチャ	1k-architecture	プロジェクト構成、インポートルール
コード品質	1k-code-quality	Lint の修正、コミット前タスク、ドキュメント
コードレビュー	1k-code-review-pr	PR レビューチェックリスト
コーディングパターン	1k-coding-patterns	React パターン、TypeScript の規約
PR の作成	1k-create-pr	PR 作成ワークフロー
クロスプラットフォーム	1k-cross-platform	プラットフォーム固有のコード
日付のフォーマット	1k-date-formatting	日時表示、ロケールに応じたフォーマット
DeFi 統合	1k-defi-module-integration	ステーキング、レンディング、Earn、Borrow モジュール
開発コマンド	1k-dev-commands	ビルド、テスト、Lint コマンド
エラー処理	1k-error-handling	Try/Catch、エラーバウンダリー、ユーザー向けエラー
機能開発	1k-feature-guides	新しいチェーン、ソケットイベント、通知、ページ、ルート
Git ワークフロー	1k-git-workflow	ブランチ、コミット、PR
グループシンク	1k-group-think	複数エージェントによる共同分析
i18n	1k-i18n	翻訳、ロケール
PR CI の監視	1k-monitor-pr-ci	CI チェックの監視、PR ステータス
ネイティブモジュールのパッチ	1k-patching-native-modules	iOS／Android のクラッシュ修正、ネイティブコードのパッチ
パッケージのアップグレード	1k-pkg-upgrade-review	依存関係のアップグレードレビュー、互換性
パフォーマンス	1k-performance	最適化、並行リクエスト、メモ化
プラットフォーム要件	1k-platform-requirements	全プラットフォームの最小 SDK／OS バージョン
振り返り	1k-retrospective	バグ修正の分析、チェックリストの更新
Sentry 分析	1k-sentry-analysis	クラッシュレポート、AppHang、ANR の修正
Sentry 設定	1k-sentry	エラーのフィルタリング、クラッシュ設定
状態管理	1k-state-management	Jotai atoms、グローバル状態
バージョンアップテスト	1k-app-upgrade-test	アプリの自動更新テスト、バージョン移行
UI レシピ	1k-ui-recipes	スクロールオフセット、ビューの遷移、キーボード回避

統合ワークフロー

既存のスキルに統合する場合：

1. ルールファイルとして追加します：

   .claude/skills/<existing-skill>/
   ├── SKILL.md                          # Update quick reference
   └── references/rules/
       └── <new-topic>.md                # Add detailed content here
   

2. メインの SKILL.md を更新します：

   • クイックリファレンステーブルに項目を追加します
   • 簡単な概要セクションを追加します
   • 新しいルールファイルへのリンクを追加します

3. 統合の例：

   ## Quick Reference
   
   | Feature | Guide | Key Files |
   |---------|-------|-----------|
   | Existing topic | [existing.md](references/rules/existing.md) | `path/to/files` |
   | **New topic** | [new-topic.md](references/rules/new-topic.md) | `path/to/files` |  
   

分割ワークフロー

既存のスキルを分割する場合：

1. 現在のスキルを分析します：

   # Check file sizes
   ls -lh .claude/skills/<skill-name>/references/rules/
   wc -l .claude/skills/<skill-name>/references/rules/*.md
   

2. 分割候補を特定します：

   • 10 KB 超または 1000 行超のファイル
   • トリガーワードが明確に異なるトピック
   • 個別に使用されるワークフロー

3. 新しいスキルディレクトリを作成します：

   mkdir -p .claude/skills/<new-skill-1>/references/rules
   mkdir -p .claude/skills/<new-skill-2>/references/rules
   

4. ファイルを移動します（git は名前変更として追跡します）：

   mv .claude/skills/<old-skill>/references/rules/<topic>.md \
      .claude/skills/<new-skill>/references/rules/
   

5. 各新しいスキルの SKILL.md を作成します：

   • 固有のトリガーワードを含む、対象を絞った説明を書きます
   • クイックリファレンスセクションを追加します
   • 関連スキルセクションを含めます

6. 元のスキルの SKILL.md を更新します：

   • クイックリファレンスから分割したトピックを削除します
   • 新しいスキルを参照するよう、関連スキルを更新します

7. 相互参照を更新します：

   # Find all skills that reference the old skill
   grep -r "old-skill" .claude/skills/*/SKILL.md
   
   # Update each reference to point to appropriate new skill
   

8. 明確なメッセージを付けてコミットします：

   git add -A .claude/skills/
   git commit -m "refactor: split <old-skill> into focused skills"
   

2）要件を確認する（新しいスキルの場合）

新しいスキルを作成する場合は、ユーザーに次の点を尋ねます：

• このスキルでどのタスクを自動化しますか？
• このスキルを起動するトリガーは何ですか？（キーワード、ファイルの種類、コンテキスト）
• プロジェクトスコープ（.claude/skills/）と個人用（~/.claude/skills/）のどちらにしますか？
• どのツールが必要ですか？（Read、Grep、Glob、Bash、WebFetch、Write など）

3）スキルの構成を作成する

標準構成（OneKey スキルに推奨）

.claude/skills/1k-<skill-name>/
├── SKILL.md                    # Main entry with quick reference (required)
└── references/
    └── rules/
        ├── topic-1.md          # Detailed guide for topic 1
        ├── topic-2.md          # Detailed guide for topic 2
        └── topic-3.md          # Detailed guide for topic 3

シンプルな構成（単一トピックのスキル向け）

.claude/skills/1k-<skill-name>/
└── SKILL.md                    # All content in one file

SKILL.md テンプレート

---
name: 1k-skill-name
description: Brief description of what this Skill does and when to use it. Include specific trigger keywords.
allowed-tools: Read, Grep, Glob  # Optional: restrict tool access
---

# Skill Title

Brief overview.

## Quick Reference

| Topic | Guide | Key Files |
|-------|-------|-----------|
| Topic 1 | [topic-1.md](references/rules/topic-1.md) | `path/to/files` |
| Topic 2 | [topic-2.md](references/rules/topic-2.md) | `path/to/files` |

## Topic 1 Summary

See: [references/rules/topic-1.md](references/rules/topic-1.md)

**Key points:**
- Point 1
- Point 2

## Topic 2 Summary

See: [references/rules/topic-2.md](references/rules/topic-2.md)

**Key points:**
- Point 1
- Point 2

## Related Skills

- `/1k-related-skill-1` - Description
- `/1k-related-skill-2` - Description

4）ベストプラクティスのチェックリストを適用する

命名

• 必須：すべての OneKey プロジェクトスキルに 1k- プレフィックスを使用します
• 内容が分かる名前を使用します：1k-feature-guides、1k-dev-workflows、1k-sentry
• 64 文字以内にし、小文字、数字、ハイフンのみを使用します
• 予約語「anthropic」「claude」は使用しません

説明

• 三人称で記述します（「処理します…」とし、「お手伝いできます…」とはしません）
• 何をするか、いつ使用するかの両方を含めます
• ユーザーが実際に使う具体的なトリガーキーワードを含めます
• 1024 文字以内にします

コンテンツ構成

• メインの SKILL.md に、ルールへのリンクを含むクイックリファレンステーブルを配置します
• 詳細な内容は references/rules/*.md に記載します
• 各ルールファイルは、それだけで内容が理解でき、焦点を絞ったものにします
• SKILL.md の本文は 500 行未満にします
• Unix 形式のパス（スラッシュ）を使用します

構成

• 関連するトピックを、複数のルールを含む 1 つのスキルにまとめます
• すべてのルールで一貫した書式を使用します
• 相互参照のための「関連スキル」セクションを含めます
• 複雑なワークフローにはチェックリストを追加します

5) スキルを出力する

要件を収集し、ベストプラクティスを適用した後：

1. references/rules/ 構成でスキルディレクトリを作成します
2. クイックリファレンステーブルを含む SKILL.md を作成します
3. 各トピックのルールファイルを追加します
4. 作成した内容を要約します
5. 最適化を確認するため、トークン分析を実行します（必須）

トークン分析（セルフチェック）

スキルを作成または変更した後は、必ず実行してください：

# Run token analysis
python3 development/skills-analysis/analyze-skills-tokens.py --sort-by-size

# Check your new skill's token count
python3 development/skills-analysis/analyze-skills-tokens.py --detailed | grep -A 5 "your-skill-name"

確認チェックリスト：

• 新しいスキルが 5,000 トークン未満（理想）
• 5,000 トークンを超える場合：トピック同士の関連性が高い（50% 超のケースで併用される）
• 10,000 トークンを超える場合：すぐに分割する計画を立てる
• SKILL.md にクイックリファレンスがある（ファイル全体の読み込みを強制しない）
• スキル間に重複した内容がない

結果に基づく対応：

トークン数	対応
< 2,000	✅ 優秀 — 続行
2,000 - 5,000	✅ 良好 — 続行し、増加を監視
5,000 - 10,000	⚠️ 確認：トピックを分割できますか？関連性が高ければ、クイックリファレンスを設けて続行
> 10,000	🚨 コミット前に分割

詳しいガイダンスについては、development/skills-analysis/SKILLS-TOKEN-MONITORING.md を参照してください。

例：複数のルールを含むスキル

.claude/skills/1k-feature-guides/
├── SKILL.md
└── references/rules/
    ├── adding-chains.md
    ├── adding-socket-events.md
    ├── notification-system.md
    └── page-and-route.md

SKILL.md の内容：

---
name: 1k-feature-guides
description: Feature development guides for OneKey. Use when adding new chains, socket events, notifications, pages, or routes.
---

# Feature Development Guides

## Quick Reference

| Feature | Guide | Key Files |
|---------|-------|-----------|
| Add blockchain chain | [adding-chains.md](references/rules/adding-chains.md) | `packages/core/src/chains/` |
| Add WebSocket events | [adding-socket-events.md](references/rules/adding-socket-events.md) | `packages/shared/types/socket.ts` |

## Adding New Chains

See: [references/rules/adding-chains.md](references/rules/adding-chains.md)

**Key steps:**
1. Implement chain core logic
2. Add chain configuration
3. Update UI components

避けるべきアンチパターン

構成と整理

• ❌ 内容が既存のカテゴリに適合するのに、新しいスキルを作成する
• ❌ すべての内容を SKILL.md に記載する（詳細には references/rules を使用します）
• ❌ ファイル参照を深くネストする（1 階層にとどめます）
• ❌ OneKey スキルに 1k- プレフィックスを付け忘れる

コンテンツの品質

• ❌ 「ドキュメントを支援します」のような曖昧な説明
• ❌ 明確なデフォルトを示さずに複数のアプローチを挙げる
• ❌ Claude がすでに知っていることを過剰に説明する
• ❌ 説明にトリガーキーワードが含まれていない

トークン最適化に関するアンチパターン

• ❌ 肥大化したスキルを放置する：ファイルが 10 KB を超えても分割しない
• ❌ 過剰に分割する：関連性の高いトピックを別々のスキルにする
• ❌ 使用パターンを無視する：どのトピックが一緒に使われるかを考慮しない
• ❌ 曖昧なトリガー語：不要な読み込みを引き起こす一般的なトリガーを使う
• ❌ クイックリファレンスがない：最初に要約を示さず、ファイル全体の読み込みを強制する
• ❌ 内容を重複させる：相互参照の代わりに、スキル間で内容をコピーする

分割の良い例と悪い例

❌ 悪い例：過剰な分割

1k-date-format-display
1k-date-format-parse
1k-date-format-locale

問題点：常に一緒に使われるため、分割によるオーバーヘッドが節約分を上回ります

✅ 良い例：焦点を絞ったスキル

1k-date-formatting
├── SKILL.md (Quick Reference)
└── references/rules/date-formatting.md

❌ 悪い例：肥大化したままにする

1k-coding-patterns (15 KB, 9 unrelated files)

問題点：1 つのパターンだけが必要な場合でも、すべてのパターンを読み込んでしまいます

✅ 良い例：独立性に基づいて分割する

1k-coding-patterns (core patterns only)
1k-date-formatting (independent utility)
1k-i18n (independent utility)
1k-error-handling (independent patterns)