modular-skills

使用しない場合

• トークン予算内に収まる単一ファイルのスキル（abstract:skill-authoring を使用）
• 遅延読み込みの契約自体（leyline:progressive-loading を使用）

モジュール式スキルの設計

概要

このフレームワークでは、複雑なスキルを用途に応じたモジュールに分割し、トークン使用量を予測可能にするとともに、単一の巨大なファイルになるのを防ぎます。プログレッシブディスクロージャーを採用しており、最初に必須事項を読み込み、必要な場合にのみ @include または Load: ステートメントで技術的な詳細を追加で読み込みます。この方法により、長時間のタスク中にコンテキスト制限に達するのを防ぎます。

モジュール式の設計により、ファイルサイズを通常150行未満という推奨範囲内に保てます。依存関係を浅くし、境界を明確にすることで、テストやメンテナンスが容易になります。ハブアンドスポークモデルを使えば、主要なスキルファイルを肥大化させずにプロジェクトを拡張でき、用途を絞ったモジュールは個別に検証しやすく、解析も速くなります。

コアコンポーネント

モジュール式スキルの開発を支援するツールは3つあります。

• skill-analyzer：複雑さを確認し、コードを分割する箇所を提案します。
• token-estimator：使用量を予測し、最適化を提案します。
• module_validator：構造がプロジェクトの標準に準拠しているかを検証します。

設計原則

スキルは単一責任と疎結合を基本に設計します。各モジュールは1つのタスクに特化し、依存関係を最小限に抑えることで、まとまりのあるアーキテクチャを維持します。境界を明確にし、インターフェースを適切に定義することで、あるモジュールの変更が他のモジュールの不具合につながるのを防ぎます。これはAnthropicのAgent Skillsに関するベストプラクティスに沿ったもので、まず概要を示し、必要に応じて詳細を提示することで、コンテキストを効率的に保ちます。

モジュールの所有権（重要）

非推奨：skills/shared/modules/ ディレクトリ。このパターンでは、共有モジュールの更新や削除により、参照先が失われる問題が発生していました。

現在のパターン：各スキルが skills/<skill-name>/modules/ にモジュールを所有します。複数のスキルで同じコンテンツが必要な場合は、プライマリ所有者がそのモジュールを保持し、他のスキルは相対パス（例：../skill-authoring/modules/description-writing.md）で参照します。バリデーターは残っている skills/shared/ ディレクトリに警告を出します。

クイックスタート

スキルの分析

scripts/skill_analyzer.py を使用してモジュール性を分析します。分割が必要なファイルを特定するため、行数のしきい値をカスタマイズできます。

python scripts/skill_analyzer.py --file path/to/SKILL.md --threshold 100

Pythonからは、abstract.skill_tools の analyze_skill を使用します。

トークン使用量の計画

トークン消費量を見積もり、スキルが予算内に収まることを確認します。スキルのディレクトリから次を実行します。

python scripts/tokens.py

モジュールの検証

デプロイ前に、構造とパターンへの準拠を確認します。

python scripts/abstract_validator.py --scan

ワークフローとタスク

まず skill_analyzer.py で複雑さを評価します。スキルが150行を超える場合は、modules/implementation-patterns.md のパターンに従って、用途を絞ったモジュールに分割します。token_estimator.py で効率を確認し、abstract_validator.py で最終的な構造を検証します。この反復プロセスにより、モジュールの保守性とトークン効率を維持できます。

品質チェック

行数を確認し、対応が必要なモジュールを特定します。100行を超えるモジュールは、分割を検討してください。目次は追加しないでください。アンカーの一覧はその下の見出しを繰り返すため、読み込むたびにトークンを消費します。また、grepを使えば見出しを直接検索できます。

# Find modules exceeding 100 lines
find modules -name "*.md" -exec wc -l {} + | awk '$1 > 100'

標準への準拠

標準では、具体例と一貫した語調を重視します。クイックスタートのセクションには、抽象的な説明ではなく、実際のコマンドを必ず記載してください。「あなた」や「あなたの」ではなく、「プロジェクト」や「開発者」などの三人称で記述してください。各コード例の後には、検証コマンドを記載してください。見つけやすくするため、説明には具体的なトリガーフレーズを5つ以上含めてください。

リソース

共有モジュール：スキル横断パターン

トリガーの標準パターンと、スキルが適用されるかどうかを判断する方法：

• トリガーパターン：[enforcement-patterns.md](modules/enforcement-patterns.md)を参照してください
• スキルの選択：[skill-selection-judgment.md](../../shared-modules/skill-selection-judgment.md)を参照してください

スキル固有のモジュール

実装と保守に関する詳細なガイド：

• 適用パターン：modules/enforcement-patterns.mdを参照してください
• コアワークフロー：modules/core-workflow.mdを参照してください
• 実装パターン：modules/implementation-patterns.mdを参照してください
• 移行ガイド：modules/antipatterns-and-migration.mdを参照してください
• 設計理念：modules/design-philosophy.mdを参照してください
• トラブルシューティング：modules/troubleshooting.mdを参照してください
• 最適化手法：modules/optimization-techniques.mdを参照してください。外部化、統合、段階的読み込みによって大きなスキルファイルのサイズを削減します

ツール

• ツール：../../scripts/内のskill_analyzer.py、token_estimator.py、abstract_validator.py。

完了条件

• 作成したすべてのモジュールファイルが150行以下であり、SKILL.mdにもモジュールにも目次がないこと。
• skills/shared/modules/ディレクトリが存在せず、すべてのモジュールが skills/<skill-name>/modules/の下にあること。
• python scripts/abstract_validator.py --scanが、対象のスキルディレクトリに対して構造上の警告なしで終了コード0を返すこと。
• python scripts/tokens.pyが、ハブとなるSKILL.mdの宣言済みestimated_tokens予算以内の推定トークン総数を報告すること。