CH 14 · Skill とワークフロー
この章の目標
前までは、Agent に何かさせるたびに毎回きちんと要件を説明する必要がありました。ただ、タスクには工程が決まっているものがあります —— CH 05 で走らせた「リポジトリを要約、ドキュメントとして出力」のような、週報、データ整理、ルーティン作業のような日常タスク。毎回ゼロから工程を話すのはもったいないです。そうしたタスクは「1 枚の指示書」にしておくと価値があります:Agent に「この手のタスクに当たったら、この工程に従え」と伝えるのです。それが Skill です。この章では dsh の Skill とは何か、どこから来るのか、モデルがどう使うかをはっきりさせてから、既製の Skill を 1 つインストールしてそのまま使います —— Agent に一言告げるだけで Skill を自分でインストールさせ、自分の「再利用可能な能力」にします。
重要な事実:Skill もプラグイン
MCP やサブエージェントと同様、dsh の Skill も別エントリではなく、プラグインの組み合わせです。設定ツリーを見ると、Skill 能力ファミリは 4 つのピースから構成されます:
| プラグイン | 機能 | 役割 |
|---|---|---|
dsh-skill | レジストリ:各ソースのスキルディレクトリをマージ、名前で「勝つ」方を解決 | 倉庫管理者 |
dsh-skill-filesystem | プロジェクトとユーザーディレクトリからローカル Skill を発見、ファイル変更を監視 | バイヤー |
dsh-tool-skill | モデルにスキル一覧を見せ、skill ロードツールを提供 | フロント |
dsh-skill-badge | 同梱の公式バッジ Skill、デフォルト無効 | 装飾 |
この 4 つすべてが web 設定でデフォルトで入っています —— つまり今すぐに使えます、何もインストール不要。これも CH 08 の「すべてはプラグイン」で、「再利用可能な能力」自体もプラグインが組み立てているのです。
Skill とは:書かれた「タスクの進め方」
ツールは Agent が「呼べる」アクション(ファイル読み書き、ウェブ検索)で、Skill は Agent のために書かれた「指示書」 —— 「この手のタスクに当たったら、この工程に従え」と伝えるタスク固有の指示セットです。
最大の違いは再利用性:ツールはシステム提供、Skill はあなたの蓄積。タスクに対する有用なやり方を編み出し、Skill として書いておけば、同じ手のタスクに当たってもう一度要件を繰り返す必要がなくなります。Skill はその置き場に従います:プロジェクトの .dsh/skills に置けばプロジェクトレベル、そのプロジェクトでのみ有効;ユーザーディレクトリ ~/.dsh/skills に置けばユーザーレベル、どのプロジェクトでも使えます —— 次節「5 つの棚」で全階層を見せます。
「ワークフロー」は何か:Skill が最も単純なワークフロー
1 行で覚えてください:Skill が最も単純なワークフロー。ワークフローの本質は「人間の経験を工程として凝固させる」ことで、Skill はまさにそれです:入力明確、出力明確、工程固定、個別に再利用可能。1 タスクに圧縮された小さな工程。
違いは粒度。Skill は「単一タスクの進め方」(1 品の料理レシピ)、ワークフローは「複数タスクをどう順に繋ぐか」(食材購入から野菜洗い、配膳までの全体パイプライン、分岐や引き継ぎ、誰が先かも管理)。dsh の Standard プリセットでは「Skills」と「Workflows」は並列する 2 ツールです —— 単一工程の固定ルーティンは Skill で十分、複数工程のチェーンで初めて Workflow が必要。
2 つを並べると違いがよりはっきりします:
| 次元 | Skill | Workflow |
|---|---|---|
| 扱うもの | 単一タスクの進め方 | 複数タスクをどう順に繋ぐか |
| 粒度 | 単一工程の固定ルーティン | 多工程パイプライン |
| 分岐・引き継ぎ | 担当しない | 担当する(条件、引き継ぎ、順序) |
| 再利用 | 個別に再利用可能 | 必要に応じて再编排 |
| 比喩 | 1 品の料理レシピ | 食材購入から配膳までの全体パイプライン |
つまり、ただ 1 つの固定タスクのために Skill を書いたら、実は「最も単純なワークフロー」を作ったことになります。
Skill はどんな形をしているか
Skill は frontmatter 付きの Markdown ファイルで、標準形はディレクトリバンドル:フォルダ名が Skill 名、中に必ず SKILL.md —— 付随リソース(スクリプト、参考資料、資産)を伴う Skill に向きます。
名前は小文字 kebab-case(^[a-z0-9]+(?:-[a-z0-9]+)*$)、例: code-review、weekly-report。
標準的なディレクトリバンドルはこの形:
code-review/
├── SKILL.md # 必須: frontmatter + 指示本体
├── scripts/ # 任意: 付随スクリプト (.py / .sh など)
├── references/ # 任意: 参考資料、レビューチェックリストテンプレート
└── assets/ # 任意: 資産、サンプルファイルSKILL.md が必要な唯一のファイルで、本体はバンドル内のスクリプトや参考資料を相対パスで参照できます。最小構造は次のとおり:
---
name: code-review
description: 統一チェックリストに従ってコードをレビューし、構造化されたレビューコメントを出力する
whenToUse: ユーザーが「コードレビュー」「代码审查」を求めたとき
---
# Code Review
次の順に従う:
1. まず関連 README を読み、このコードが何を解くかを理解する;
2. 公開エクスポートと主要関数を列挙し、それぞれが何をするかをメモ;
3. 明らかなリスク箇所を探す:エラーハンドリング、エッジケース、機微情報;
4. 表形式で出力:ファイル / 問題 / 重大度 / 提案。frontmatter で必須なのは name と description のみ、他のフィールドはすべて任意:
| フィールド | 役割 |
|---|---|
name | Skill の一意な名前(kebab-case、必須) |
description | 1 行説明、モデルが「自分の仕事か」を判定するために使う(必須) |
whenToUse | 追加の使用タイミングヒント(任意) |
disable-model-invocation | true に設定:ユーザーだけが /name で呼び出せ、モデルは自動ロードしない(任意) |
user-invocable | false に設定:モデルだけが呼び出せ、ユーザーの /name は無効(任意) |
2 つのスイッチ:誰が呼べるか
frontmatter の 2 フィールドが「誰が呼べるか」を扱います:
| 組み合わせ | 効果 |
|---|---|
| どちらも未設定 | モデルとユーザー両方が呼べる(デフォルト) |
disable-model-invocation: true | ユーザーだけが /name で呼べる、モデルディレクトリにも skill ツールにも出ない —— 機微または高コストなフローで、モデルがカジュアルに発動するのを防ぐのに適する |
user-invocable: false | モデルだけが呼べる、ユーザーの /name は無効 |
| 両方オフ | 信頼できるコードだけが呼べる、モデルもユーザーも触れない |
Skill はどこから来るか:5 つの「棚」
まず 2 つを区別してください:この節はdsh がどこから Skill を読むか —— つまり Skill が発見されるために置かれるべきローカルディレクトリ。dsh は dsh-skill-filesystem プラグインを使って複数のルートディレクトリを固定順でスキャンし、Skill をレジストリに集めます。「新しい Skill をインストールする」は別の話:コミュニティ Skill マーケット(Tencent の SkillHub など)や dsh のプラグインマーケットへ行き、誰かの既製 SKILL.md をこれらの棚ディレクトリに入れる —— 下の「既製 Skill をインストールする」節がまさに行うことです。
dsh-skill-filesystem は複数のルートディレクトリを固定順でスキャンし、Skill をレジストリに集めます。順位が上ほど優先度が高く、同名 Skill が複数の棚にある場合は前方のものが勝ちます:
| 優先度 | ディレクトリ | 誰がここに置くか |
|---|---|---|
| 1 | <project-root>/.dsh/skills | プロジェクトに従う、リポジトリと一緒に配布 |
| 2 | <project-root>/.agents/skills | 他ツール(例:Claude Code)との共有場所 |
| 3 | 設定 customSkillDirs からのカスタムディレクトリ | 手動で指定する他の場所 |
| 4 | <dshHome>/skills(~/.dsh/skills) | ユーザーレベル、どの作業ディレクトリでも有効 |
| 5 | <agentsHome>/skills(~/.agents/skills) | 他の Agent ツールと共有するユーザーレベルディレクトリ |
モデルはどう Skill を「見る」か
Skill はモデルに見せるために書かれます;モデルはどうやってどれがあるか知るのか?この仕組みは dsh-tool-skill プラグインが提供し、web 設定でデフォルトで入っています(dsh --profile web --dump-config で見える)。3 つの仕組みで動きます:
- セッション見出し:セッション開始前と最初のリクエスト前に、モデルは利用可能 Skill の名前と 1 行説明を列挙した永続メッセージを受け、「行動前に合致する Skill をまずロードせよ、概要から推測するな」と告げられます。
skillツール:モデルが Skill が関連ありと判断したら、skill({ name })を使って完全な指示本体をロードします —— 本体は<skill_content>ブロックとして返り、ツール結果として履歴に残ります。下の画像は実軌跡:モデルがまずskillツールを呼んでaihotの完全指示をロードし、次にpwshを呼んで検証リクエストを実行しています;2 つのツール呼び出しが軌跡で明瞭に見えます。
- ユーザー操作
/name:入力欄に直接/code-reviewと打てば、Skill の指示がユーザーメッセージとしてラウンドに注入され、モデルがそのまま従います。注意:この名前は作業ディレクトリの棚に実在し、ユーザー呼び出しを許可している必要があります —— 存在しない Skill 名を打ってもただのテキスト扱いになり、何も起きません。
一点:ユーザーの /name 注入後は、モデルは同じ Skill を skill ツールでロードし直しません —— 同じ指示が二重に詰め込まれトークンを浪費するのを避けます。
モデルに「今どんな Skill を持っている?」と聞いて答えられないときは、まず web 設定に @deepseek-ai/dsh-tool-skill プラグインがあるか確認してください(dsh --profile web --dump-config で 1 目で分かる)。
実操作:既製 Skill をインストール(そのまま使う)
既製 Skill をインストールする本質は、誰かの既製 SKILL.md を dsh の「棚」ディレクトリ(通常プロジェクトレベルの .dsh/skills)に入れること —— コミュニティにはすでに大量の既製 Skill があり、もらえます。
ここでは aihot を例にします:有名な AI 科技ブロガー「数字生命卡兹克」(デジタルライフ・カジケ)製の検索系 Skill で、毎日の AI ニュースや業界動向の取得が得意です。
ステップ 1:Agent に一言、インストールさせる
自分でファイルを探してディレクトリを作る必要はありません。会話を再開してこう言います:
AIHOT Skill をインストールしてください: https://aihot.virxact.com/aihot-skill/README.md インストール後に新しいセッションを開く必要があるか教えてください。 インストーラーが対応しているなら、追加してください: --actor あなたの-Actor-ID
--actor の後ろの ID は AIHOT プラットフォームで登録後に割り当てられ、インストール後にローカルの .aihot-actor-id に書かれます;Agent はリクエスト時にこれを身元確認として携えます。
Agent は自分でやります:公式サイトへ行き、AIHOT の SKILL.md と付随ファイルをダウンロードし、DSH の標準発見場所(~/.agents/skills/aihot/)に配置し、1 件ずつ SHA-256 整合性チェックを行い、actor 設定を書き、.gitignore を生成し、結果をあなたに報告します。インストール後、新しいセッションを開く必要はありません —— すでに現在のセッションの <available_skills> に入っており、すぐに使えます。
ステップ 2:モデルに新しい Skill を報告させる
会話に戻り、こう聞きます:
今どんな Skill を持っていますか?aihot Skill は何をしますか?
モデルが報告します —— あなたは 1 行もコードを書かず、再利用可能な能力を手に入れました。それはまた、この Skill が具体的に何をするかも教えてくれます(aihot は AIHOT の匿名読み取り専用 API を通じて現在の本物の中国語 AI ニュースを取得するので、訓練記憶からの「捏造」ではない)。
ステップ 3(任意):モデルに使わせる
「aihot を使って今日の AI ニュースを取得して」と一言言えば、モデルはこの Skill をロードして取得します。誰かが練り上げた検索フローが今やあなたの能力に —— これが「そのまま使う」です。
よくある落とし穴
| 落とし穴 | 避け方 |
|---|---|
description を忘れた | 必須フィールド欠落、Skill 全体が警告後に破棄される |
| ディレクトリの置き場が間違っている | <root>/<name>/SKILL.md または <root>/<name>.md のみ認識される、1 階層、それより深くネストしない |
| モデルが能動的に使ってくれない | description に「いつ使うか」を明確に書く(whenToUse も助けになる);本当に心配なら /name で直接注入する |
| 本体を編集したがモデルが反応しない | 本体編集はディレクトリ概要に影響しない;モデルは 1 回「リロード」が必要;description のような概要フィールドの編集のみ即時にディレクトリに反映される |
この章で学んだこと
下の項目を自力で達成できれば合格です:
- [ ] Skill が「Agent のために書かれた再利用可能な指示」であり、ツールとの違いが再利用性であることを言える
- [ ] dsh で Skill もプラグインであることを知っている(Skill レジストリ + ファイルシステム発見 + ツール消費側)
- [ ] Skill の構造を言える(frontmatter に
name/description必須、whenToUse任意) - [ ] 5 つの棚の優先度を知っている(プロジェクト
.dsh/skillsが最高、ユーザーディレクトリが次、プロジェクト跨ぎで使える) - [ ] 「Agent に一言 → Skill をインストール → モデルが報告 → モデルがロードして使う」を走らせた
- [ ] 2 つのスイッチ
disable-model-invocationとuser-invocableを区別できる