skills-creator

Skills Creator

agentskills.io 仕様に準拠した Agent Skills の作成、検証、管理を行うための包括的なスキルです。

このスキルを使用する場面

次の場合にこのスキルを使用してください。

• ユーザーが新しいエージェントスキルの作成を依頼したとき
• ユーザーが既存のスキルの変更や改善を希望しているとき
• ユーザーがスキルの構造や frontmatter の検証を必要としているとき
• ユーザーが「skill」、「agent skill」、または agentskills.io に言及したとき
• ユーザーが Agent Skills の形式について知りたいとき

Agent Skills とは

Agent Skills は、専門知識やワークフローを通じて AI エージェントの能力を拡張する、軽量なオープン形式です。基本的に、スキルはメタデータと指示を含む SKILL.md ファイルを格納したフォルダーです。

段階的な開示の原則

スキルは、コンテキストを効率的に管理するために段階的な開示を使用します。

1. 検出：エージェントは起動時に名前と説明のみを読み込みます
2. 有効化：関連性がある場合、エージェントは SKILL.md の指示全体を読み込みます
3. 実行：必要に応じて、エージェントは参照ファイルを読み込むか、コードを実行します

これにより、エージェントは高速なまま、必要に応じて追加のコンテキストにアクセスできます。

ディレクトリー構造

skill-name/
├── SKILL.md          # Required: instructions + metadata
├── scripts/          # Optional: executable code
├── references/       # Optional: documentation
└── assets/           # Optional: templates, resources

SKILL.md の形式

すべてのスキルは、YAML frontmatter の後に Markdown の指示を記述して構成します。

必須の frontmatter

---
name: skill-name
description: A description of what this skill does and when to use it.
---

任意の frontmatter フィールド

---
name: skill-name
description: What this skill does and when to use it.
license: MIT
compatibility: Requires git, docker, jq, and internet access
metadata:
  author: example-org
  version: "1.0"
allowed-tools: Bash(git:*) Bash(jq:*) Read
---

フィールドの仕様

name フィールド

• 必須：はい
• 制約：1～64 文字。小文字、数字、ハイフンのみ使用できます
• ハイフンで始めたり、終えたりしてはいけません
• 連続するハイフン（--）を含めてはいけません
• 親ディレクトリー名と一致させる必要があります

有効な例：

• pdf-processing
• data-analysis
• code-review

無効な例：

• PDF-Processing（大文字）
• -pdf（ハイフンで始まる）
• pdf--processing（ハイフンが連続している）

description フィールド

• 必須：はい
• 制約：1～1024 文字。空欄不可
• スキルの機能と使用する場面の両方を説明してください
• エージェントが関連するタスクを特定するための具体的なキーワードを含めてください

良い例：

description: Extracts text and tables from PDF files, fills PDF forms, and merges multiple PDFs. Use when working with PDF documents or when the user mentions PDFs, forms, or document extraction.

良くない例：

description: Helps with PDFs.

license フィールド

• 必須：いいえ
• 短く記述してください（ライセンス名、または同梱ファイルへの参照）

例：

license: Apache-2.0

compatibility フィールド

• 必須：いいえ
• 制約：指定する場合は1～500文字
• スキルに特定の環境要件がある場合にのみ含めてください
• 対象製品、必須パッケージ、ネットワークアクセスなどを指定できます

例：

compatibility: Designed for Claude Code (or similar products)

compatibility: Requires git, docker, jq, and access to the internet

metadata フィールド

• 必須：いいえ
• 文字列キーから文字列値へのマップです
• 仕様で定義されていない追加のプロパティに使用します
• 競合を避けるため、キー名はできるだけ固有のものにしてください

例：

metadata:
  author: example-org
  version: "1.0"
  category: development

allowed-tools フィールド

• 必須：いいえ
• 事前承認済みツールをスペース区切りで列挙します
• 実験的な機能のため、サポート状況は異なります

例：

allowed-tools: Bash(git:*) Bash(jq:*) Read

本文の内容に関するガイドライン

frontmatter の後に続く Markdown 本文には、スキルの指示を記述します。形式上の制限はありませんが、次のベストプラクティスに従ってください。

推奨セクション

1. このスキルを使用する場面 - エージェントがこのスキルを有効にする条件を明確に示します
2. このスキルでできること - 機能の概要を簡潔に説明します
3. 手順 - 詳細な手順を記述します
4. 例 - 入力例と期待される出力を示します
5. 一般的なパターン - 再利用可能な方法を示します
6. ベストプラクティス - ヒントや推奨事項を示します
7. エッジケース - 特殊な状況への対処方法を示します

コンテンツ作成のベストプラクティス

• メインの SKILL.md は500行未満にしてください（5000トークン未満を推奨）
• 詳細な参考資料は references/ 内の別ファイルに移してください
• 明確で実行可能な表現を使用してください
• 役立つ場合はコード例を含めてください
• 「何を」だけでなく、「なぜ」「どのように」に重点を置いてください
• 指示を書く際は、エージェントの視点を考慮してください

任意のディレクトリー

scripts/

エージェントが実行できる実行可能コードを格納します。

ベストプラクティス：

• スクリプトを自己完結型にするか、依存関係を明確に記載します
• 役立つエラーメッセージを含めます
• エッジケースを適切に処理します
• 一般的な言語（Python、Bash、JavaScript）を使用します

構成例：

scripts/
├── validate.py
├── generate.sh
└── utils/
    └── helpers.py

references/

必要に応じて読み込む追加ドキュメントを格納します。

ベストプラクティス：

• ファイルごとに1つのトピックに絞ります
• 内容がわかるファイル名を使用します
• 推奨ファイル：
  • REFERENCE.md - 詳細な技術リファレンス
  • FORMS.md - フォームのテンプレートまたは構造化データ形式
  • ドメイン固有のファイル（finance.md、legal.md など）

構成例：

references/
├── REFERENCE.md
├── API.md
└── TROUBLESHOOTING.md

assets/

テンプレート、画像、データファイルなどの静的リソースを格納します。

構成例：

assets/
├── templates/
│   └── config.yaml
├── diagrams/
│   └── workflow.png
└── data/
    └── schema.json

ファイル参照

スキル内のほかのファイルを参照する場合は、スキルのルートからの相対パスを使用します。

See [the reference guide](references/REFERENCE.md) for details.

Run the extraction script:
```bash
scripts/extract.py

Keep file references one level deep from SKILL.md. Avoid deeply nested reference chains.

## Creating a new skill step-by-step

When a user asks you to create a skill, follow these steps:

### 1. Gather requirements
Ask the user:
- What should the skill do?
- When should it be activated?
- What tools or resources are needed?
- Are there specific examples or use cases?

### 2. Choose a name
- Use lowercase with hyphens
- Keep it short and descriptive
- Ensure it matches the directory name

### 3. Write a clear description
- Include what the skill does
- Include when to use it
- Add keywords for agent matching

### 4. Create directory structure
```bash
mkdir -p skill-name/scripts
mkdir -p skill-name/references
mkdir -p skill-name/assets

5. SKILL.md を作成する

最初にフロントマターを記述し、その後に以下を含む本文を追加します：

• 使用するタイミングのセクション
• できること
• 手順
• 例
• ベストプラクティス

6. 補助ファイルを追加する（必要な場合）

• scripts/ 内のスクリプト
• references/ 内のリファレンスドキュメント
• assets/ 内のテンプレート／アセット

7. 検証する

以下を確認します：

• 名前が制約に従っている（小文字、連続するハイフンがないなど）
• 説明が明確で、関連キーワードが豊富である（1～1024 文字）
• フロントマターが有効な YAML である
• ディレクトリ名がスキル名と一致している
• 手順が明確で、実行可能である

一般的なパターン

基本的なスキル（手順のみ）

basic-skill/
└── SKILL.md

スクリプトを含むスキル

automation-skill/
├── SKILL.md
└── scripts/
    └── automate.py

リファレンスを含む複雑なスキル

complex-skill/
├── SKILL.md
├── scripts/
│   └── process.py
├── references/
│   ├── REFERENCE.md
│   └── API.md
└── assets/
    └── templates/
        └── config.yaml

検証チェックリスト

スキルを完成させる前に、以下を確認します：

• ディレクトリ名がフロントマターの name と一致している
• name が1～64文字で、小文字の英数字とハイフンのみを使用している
• name がハイフンで始まったり終わったりせず、連続するハイフンも含まない
• description が1～1024文字で、使用するタイミングを含んでいる
• YAML フロントマターが有効である
• メインの SKILL.md が500行未満である
• ファイル参照に相対パスを使用している
• スクリプトに明確なエラー処理がある（存在する場合）
• 深くネストしたリファレンスの連鎖がない

スキルテンプレートの例

最小限のスキル

---
name: example-skill
description: Brief description of what this does and when to use it.
---

## When to use this skill
Use when...

## Instructions
1. Step one
2. Step two
3. Step three

高機能なスキル

---
name: advanced-skill
description: Comprehensive description with keywords for activation.
license: MIT
compatibility: Requires specific tools or environment
metadata:
  author: your-name
  version: "1.0"
---

## When to use this skill
Use when...

## What this skill does
Overview...

## Instructions
Detailed steps...

## Examples
Sample code and outputs...

## Best practices
Tips and recommendations...

## Common patterns
Reusable approaches...

## Troubleshooting
See [troubleshooting guide](references/TROUBLESHOOTING.md)

統合に関する注意事項

スキルは、ファイルシステムベースのエージェント（推奨）またはツールベースのエージェントで動作するように設計されています：

ファイルシステムベースのエージェント

• cat /path/to/skill/SKILL.md のようなシェルコマンドでスキルを有効化します
• バンドルされたリソースにはシェルコマンドでアクセスします

ツールベースのエージェント

• スキルの起動やアセットへのアクセス用のツールを実装します
• ツールの実装方法は開発者に委ねられます

リソース

詳細については、以下を参照してください：

• agentskills.io の仕様
• 統合ガイド
• GitHub のスキル例
• 作成のベストプラクティス
• リファレンスライブラリ（skills-ref）

検証コマンド

ユーザーが skills-ref ライブラリをインストールしている場合：

# Validate a skill directory
skills-ref validate ./skill-name

# Generate XML for agent prompts
skills-ref to-prompt ./skill-name

スキル作成のベストプラクティス

1. 焦点を絞る：1つのスキルで1つのことをうまく行います
2. 説明を具体的にする：有効化に使うキーワードを含めます
3. 段階的に情報を開示する：SKILL.md を簡潔に保ち、詳細はリファレンスに移します
4. 例を示す：説明するだけでなく、例を示します
5. エラーを適切に処理する：エッジケースを想定します
6. 十分にテストする：手順が明確で完全であることを確認します
7. スキルをバージョン管理する：メタデータを使用して変更を追跡します
8. 依存関係を文書化する：必要に応じて互換性フィールドを使用します
9. 移植性を確保する：可能な限り、スキルがさまざまな環境で動作するようにします
10. エージェントの視点で考える：エージェントの視点から手順を記述します

セキュリティに関する考慮事項

スクリプトを含むスキルを作成する際は、次の点に注意してください。

• 危険を伴う可能性のある操作について警告します
• 外部依存関係をすべて記載します
• サンドボックス化の要件を検討します
• 信頼できるスクリプトには許可リストを使用します
• 監査のためにスクリプトの実行を記録します
• 認証情報やシークレットをハードコードしないようにします