スキルの作成方法と使用方法: SKILL.md の仕様と実践原理

Sat, 28 Mar 2026 16:30:00 +0800

この記事では、次の 2 つの問題に焦点を当てます。

SKILL.mdの書き方と構造の設計方法。
高品質で保守可能、再利用可能なスキルを作成する方法。

1. SKILL.md仕様の詳細説明

SKILL.md は、スキルのコア記述ファイルです。通常、次の 2 つの部分で構成されます。

YAML Frontmatter: スキルのメタ情報を定義します。
マークダウンテキスト: 実行命令と実践的なメソッドを定義します。

1.1 前付の例

---
# === 必需字段 ===
name: skill-name
# 技能的唯一标识符，建议使用 kebab-case 命名

description: >
  简洁但精确地说明：
  1) 这个技能做什么
  2) 什么时候应该使用它
  3) 核心价值是什么
# 注意：description 通常是智能体选择技能的关键依据，必须写清楚

# === 可选字段 ===
version: 1.0.0
allowed_tools: [tool1, tool2]
required_context: [context_item1]
license: MIT
author: Your Name <email@example.com>
tags: [database, analysis, sql]
---

1.2 推奨されるテキストの構成

# 技能标题

## 概述
（技能介绍、适用场景、技术背景）

## 前置条件
（运行环境、依赖项、权限要求）

## 工作流程
（分步骤说明：输入、处理、输出）

## 最佳实践
（经验总结、注意事项、常见陷阱）

## 示例
（典型任务示例，便于快速上手）

## 故障排查
（常见问题与解决方案）

2. 高品質のスキルを書くための原則

公式文書とコミュニティの実践を組み合わせて、次の 4 つの原則に従うことが推奨されます。

2.1 説明は正確でなければなりません

description は、スキルマッチングへの重要な入り口です。次のことを行うことをお勧めします。

適用範囲を明確にし、「データの処理を支援する」などの一般的な説明は避けてください。
ユーザーの意図の一致を容易にするトリガーキーワードが含まれています。
独自の価値を説明し、他のスキルとの境界線を形成します。

悪い例:

`1`	`description: 处理数据库查询`

推奨される例:

description: >
  将中文业务问题转换为 SQL 查询，并分析 MySQL employees 示例数据库。
  适用于员工信息查询、薪资统计、部门分析、职位变动历史等场景。
  当用户询问员工、薪资、部门相关数据时使用此技能。

2.2 モジュール性と単一責任

スキルは明確なタスク領域に焦点を当てる必要があります。スキルがあまりにも多くの機能をカバーしようとすると、通常は次のような結果になります。

記述範囲が広くなり、マッチング精度が低下します。
命令が長くなり、コンテキストの負荷が増加します。
メンテナンスと反復コストが増加します。

「一般的なスキル」を次のような複数の特殊なスキルに分割することをお勧めします。

mysql-employees-analysis
sales-data-analysis
user-behavior-analysis

2.3 確実性を優先する

複雑で正確なタスクの場合は、LLM テキスト生成のみに依存せず、「スクリプトの実行」を優先してください。

たとえば、データエクスポートのシナリオでは、LLM に Excel バイナリコンテンツを直接生成させるのではなく、専用のスクリプトを使用して処理する方が良いでしょう。 SKILL.md はトリガー条件と呼び出し方法を記述するだけです。

2.4 段階的な開示

非効率なコンテキストを避けるために、重要性と頻度によって情報を階層化します。

SKILL.md 本体: コアワークフローとコモンモード
追加ドキュメント (advanced.md など): 高度な使用法とエッジシナリオ
データファイル: 大規模な参照データ、スクリプト経由でオンデマンドで読み取る

要約する

高品質のスキルの目標は、「より多く書く」ことではなく、「明確な境界、正確なトリガー、安定した実行、持続可能なメンテナンス」を持つことです。

標準化された SKILL.md から始めて、単一の責任と段階的な開示を組み合わせることで、より効率的なスキルセットを構築できます。

SKILL.md on KnightLiブログ