skanvil は何をしますか？
目的
skanvil CLIを通じてスキルライブラリを変更し、スキルフォルダ、SKILL.mdのフロントマター、READMEインデックス、ライブラリの規約が一貫性を保ち、検証が常にパスする状態にします。
このスキルを有効にするタイミング
- リポジトリに
.skanvilrc.json、SKILL.mdファイルを含むskills/フォルダ、またはpackage.jsonにskanvilが含まれている場合。 - ユーザーがスキルの追加、作成、リネーム、移動、タイトル変更、説明変更、削除、一覧表示、検証、またはインデックス作成を依頼した場合。
skanvil validate、npm test、またはCIがskanvilの診断で失敗した場合。- ユーザーが別のプロジェクトでライブラリのスキルをClaude Code、GitHub Copilot、またはCodexで利用可能にしたい場合。
手順
1. 状況を把握する
.skanvilrc.jsonを読む。これにより、カテゴリ（id、フォルダprefix、READMEのtitle、aliases）、必須セクション、プレースホルダー、ルールの重大度が定義されています。ファイルがない場合は、デフォルトのプリセット（front-、back-、プレフィックスなしのtransversal（デフォルト）、および_internal）が使用されます。npx skanvil list --jsonを実行して、各スキルのカテゴリ、READMEの有無、有効性を確認します。- 変更を加える前に
npx skanvil validate --jsonを実行し、既に存在する問題を把握します。
2. 黄金律
- 手動でスキルフォルダをリネーム、移動、削除したり、手動でREADMEインデックスを編集したりしないでください。
skanvil editを使用してください。これにより、フォルダ、フロントマターのname、# 見出し、READMEエントリが同期され、失敗時にはロールバックされます。 - 手動でスキルフォルダを作成しないでください。
skanvil addを使用してください。これにより、カテゴリプレフィックス、テンプレート、フロントマターメタデータ、READMEエントリが適用されます。 - 非インタラクティブシェルでは、常にすべてのオプションを渡してください。
addには--type、--name、--descriptionが必要です。edit --removeには--yesが必要です。これらがないと、コマンドはプロンプトを表示するか、TTYがない場合は失敗します。 - 引数なしで
skanvilを実行したり、skanvil wizardを実行したりしないでください。 これらは人間向けのインタラクティブメニューを開きます。以下の明示的なコマンドを使用してください。ユーザーがメニューを希望する場合は、自分でnpx skanvilを実行するよう提案してください。 - 出力を解析する必要がある場合は、
--jsonを追加してください。データは標準出力に、警告とエラーは標準エラー出力に出力されます。 - 変更のたびに
npx skanvil validateを実行し、エラーなしで終了してください。終了コード1はエラー、または--strict使用時の警告を意味します。 skanvilがPATHにない限り、すべてのコマンドの先頭にnpxを付けてください。別のフォルダにあるライブラリを対象とする場合は、-C <path>を使用してください。
3. 一般的なタスク
スキルを作成し、その内容を記述する。
npx skanvil add --type <カテゴリ> --name "<短い名前>" \
--description "<何をするか>. <トリガーとなる状況>で使用."
次に、skills/<プレフィックス><名前>/SKILL.mdを編集します:
- 必須セクションすべてに、具体的で実行可能な内容を記入します。
- ジェネリックなテンプレート文をすべて置き換えます。これを行わないと、
validateはtemplate-unchanged警告を報告し、validate --strict（ライブラリのnpm test）は失敗します。 - 長い資料は
references/に移動し、存在するファイルにのみリンクします（broken-references）。
これらのフォルダが空のままになる場合は、--no-scripts、--no-assets、または--no-referencesを使用します。.skanvil/templates/にあるカスタムテンプレートを使用するには、--template <名前>を使用します。
スキルの名前変更または移動。
npx skanvil edit <スキル> --rename <新しい名前> # プレフィックスは自動的に再適用されます
npx skanvil edit <スキル> --type <別のカテゴリ> # 新しいプレフィックス、READMEセクション、メタデータ
npx skanvil edit <スキル> --title "<タイトル>" --description "<テキスト>"
--renameはベース名を取ります: edit front-a --rename b は front-b になります。
スキルを削除する。 最初にユーザーに確認してください。これは永続的です。
npx skanvil edit <スキル> --remove --yes
検証エラーを修正する。
npx skanvil doctor --fixを実行します。これにより、READMEエントリ、nameの不一致、フロントマター内のタブが修正され、toolsがallowed-toolsに変換されます。- 残っている問題は
SKILL.mdを編集して修正します。以下の診断テーブルを参照してください。 - 再度
npx skanvil validateを実行します。
READMEインデックスを再構築する .skanvilrc.jsonでカテゴリタイトルを変更した後:
npx skanvil index # インデックスセクションを書き換えます
npx skanvil index --check # 検証のみ（CI用）
スキルをプロジェクトにインストールする。
npx skanvil sync <プロジェクトディレクトリ> -C <ライブラリディレクトリ> --target claude,copilot --dry-run # プレビュー
npx skanvil sync <プロジェクトディレクトリ> -C <ライブラリディレクトリ> --target claude,copilot
npx skanvil sync --from @scope/package --target agents # インストール済みパッケージ
ターゲット:
claudeは.claude/skillsにインストールします;copilotは.github/skillsにインストールします;agentsとcodexは.agents/skillsにインストールします。- カスタムパスはプロジェクト内のフォルダである必要があります。
--global（プロジェクトディレクトリなし）は、代わりにユーザーの~/.claude/skills、~/.copilot/skills、または~/.agents/skillsにインストールします。ユーザーがすべてのプロジェクトで使用できるスキルを要求した場合にのみ使用します。
syncの動作:
- 自分がインストールしたフォルダを上書きすることはありません。
- ライブラリから削除されたスキルを削除します。
--forceが指定されない限り、検証エラーがあるスキルはスキップします。_internalスキルは公開しません。
カテゴリを追加または変更する。 .skanvilrc.json の categories を編集します:
- ちょうど1つのカテゴリに
"default": trueがあり、プレフィックスがありません; - 他のすべてのカテゴリには、
_または-で終わるケバブケースのプレフィックスがあります; - どのプレフィックスも別のプレフィックスで始まってはいけません。
その後、edit --type で既存のスキルを移動し、skanvil index を実行します。
4. 優れたスキルコンテンツを書く
descriptionは、スキルが 何を 行うか、そして いつ 使用するかを、エージェントが目にするトリガーキーワードとともに記述します。最大1024文字です。nameはフォルダ名と同じです: 小文字、数字、単一のハイフンのみ、最大64文字です。- 本文:
SKILL.mdを500行未満に保ちます。手順は番号付きの検証可能なステップとして書き、例、エッジケース、長いチェックリストはreferences/（1レベル深さ）に配置します。 - プレースホルダー: 仮のテキストは決して残さないでください。
validation.placeholdersのエントリ（ToDoマーカー、ダミーのラテン語テキスト、「未定」メモ）は検証に失敗します。 metadata: 文字列値のみ。数値は引用符で囲みます（例:version: "1.0"）。allowed-tools: スペース区切りの文字列。リストではありません。
5. 診断 → 修正
| ルール | 修正 |
|---|---|
readme-missing、readme-orphan、readme-section | npx skanvil doctor --fix |
name-matches-folder、name-required | doctor --fix、またはフォルダ名が間違っている場合は edit --rename |
frontmatter-tabs、tools-field | doctor --fix |
frontmatter | --- 行間のYAMLを修正する（: または # を含む値は引用符で囲む）。 |
required-sections | validation.requiredSections にリストされている不足している ## セクション を追加する。 |
placeholders | プレースホルダーテキストを実際のコンテンツに置き換える。 |
description-length、max-lines | 短くする。詳細は references/ に移動する。 |
metadata-format | 文字列以外の値を引用符で囲む。 |
duplicate-name | 2つのフォルダが同じ name を共有している: edit --rename で一方をリネームする。 |
broken-references | 参照されているファイルを作成するか、リンクを修正する（パスはスキルからの相対パス）。 |
template-unchanged | 汎用のひな形文をスキル固有の指示に書き換える。 |
すべてのコマンドオプション、設定スキーマ、JSON出力形式については、references/REFERENCE.mdを参照してください。
出力形式
ユーザーに以下の情報を報告します:
- 実行したskanvilコマンド;
- 作成、変更、または削除されたスキルとそのフォルダ名;
- 最終的な
skanvil validateの結果（エラーと警告）、およびユーザーの判断に委ねられた事項。
品質基準
- すべての構造変更は
skanvil addまたはskanvil editを通じて行われました。手動によるフォルダのリネームやREADMEインデックスの編集はありません。 npx skanvil validateでエラーが報告されず、npx skanvil index --checkがパスします。- 新規または編集されたスキルには、トリガーを含む具体的な説明があり、テンプレートの埋め草やプレースホルダーはありません。
- 削除や他のプロジェクトへの同期は、ユーザーに確認済みです。