Skill システム

Skill は、SKILL.md ファイルとして存在する再利用可能な指示セットです。実行中、Agent はツールを通じて skill の内容を読み取り、追加コンテキストとして会話に注入できます。Skill を使うことで、ドメイン知識、ワークフロー、ベストプラクティスを、標準化された再利用可能な単位としてカプセル化できます。

Skill とは

skill は基本的に、YAML frontmatter と Markdown 本文を含むファイルです。

---
name: Code Review Standards
description: Unified code review standards and checklist for the project
---

# Code Review Standards

## Required Checks

1. Does the code follow naming conventions?
2. Are there any unused imports?
3. Does the file exceed the line limit?
4. Are there any leftover `console.log` statements?

## Review Template

**File**: `{filename}`
**Issues found**: {N}
**Severity**: High / Medium / Low

| # | Issue | Location | Suggestion |
|---|-------|----------|------------|
| 1 | ... | L42 | ... |

Agent は list_skills ツールを使って利用可能な skill を確認し、その後 read_skill ツールを使って特定の skill の内容を取得し、タスク実行時に参照します。

Skill の検出場所

Skill は次の順序で検出され、読み込まれます。

Priority	Location	Path	Source Tag	Description
1	Workspace	.claude/skills/<name>/SKILL.md	workspace	現在のプロジェクトのみ
2	Project	<projectRoot>/.claude/skills/<name>/SKILL.md	project	プロジェクトレベルで共有
3	Personal	~/.claude/skills/<name>/SKILL.md	personal	ユーザー全体でグローバルに利用可能
4	Plugin	~/.elftia/plugins/skills/<name>/SKILL.md	plugin	コミュニティからインストールされた skill
5	Built-in	Bundled with the app	builtin	Elftia にプリインストールされた skill

同じ名前の skill が複数ある場合は、優先度が高いものが優先されます。

Skill ツール

Agent は、2 つの組み込みツールを通じて skill システムとやり取りします。

list_skills

利用可能なすべての skill とその説明を一覧表示します。

Parameters: なし

Example output:

Available skills:
- code-standards (workspace): Project coding standards and best practices
- architecture-index (workspace): Project architecture index and file location guide
- build-optimization (personal): Build optimization standards

read_skill

指定した skill の完全な内容を読み取ります。

Parameters:

Parameter	Type	Required	Description
name	string	Yes	Skill 名

Returns: skill ファイルの完全な Markdown 内容。

SkillHub コミュニティマーケットプレイス

SkillHub は skill のコミュニティマーケットプレイスで、他のユーザーが共有した skill を検索してインストールできます。

Skill を検索する

Agent は skillhub_search ツールを使ってコミュニティ skill を検索できます。

Search for skills related to "React best practices"

Skill をインストールする

必要な skill が見つかったら、skillhub_install ツールを使ってローカルにインストールします。

Install the skill "react-best-practices" to the personal directory

インストールされた skill は ~/.elftia/plugins/skills/ に保存され、すべてのプロジェクトで利用できます。

Skill を Agent に関連付ける

Skill を Agent に関連付ける方法は 2 つあります。

方法 1: Agent 設定で宣言する

Agent の frontmatter で skills フィールドを使用します。

---
name: Code Assistant
skills:
  - code-standards
  - architecture-index
---

この設定では、Agent の起動時に、これらの skill の内容が system prompt に自動的に注入されます。

方法 2: 実行時に読み取る

実行中、Agent は list_skills と read_skill を能動的に呼び出して skill の内容を取得できます。

User: Please review this code according to the project standards
Agent: Let me check the available skills first... [calls list_skills]
Agent: Found the code-standards skill, let me read it... [calls read_skill]
Agent: Based on the standards, I found the following issues...

カスタム Skill を作成する

手順

1. skill の保存場所を選びます。

   • プロジェクト固有 → .claude/skills/<name>/SKILL.md
   • グローバルに利用可能 → ~/.claude/skills/<name>/SKILL.md

2. ディレクトリとファイルを作成します。

mkdir -p .claude/skills/my-skill

3. SKILL.md ファイルを記述します。

---
name: My Skill
description: One-sentence description of the skill's purpose
---

# Skill Title

Detailed skill content...

SKILL.md 形式リファレンス

基本形式

---
name: Skill name
description: Brief description of the skill
---

Skill body content (Markdown format)

完全形式（拡張メタデータ付き）

---
name: Skill name
description: Skill description
always: false
allowedTools:
  - Read
  - Grep
  - Glob
metadata:
  always: false
  emoji: "📋"
  os:
    - win32
    - darwin
    - linux
  requires:
    bins:
      - node
      - npm
    env:
      - GITHUB_TOKEN
---

Skill body...

Frontmatter フィールドリファレンス

Field	Type	Description
name	string	Skill の表示名
description	string	簡潔な説明
always	boolean	system prompt に常に注入するかどうか（デフォルト: false）
allowedTools	string[]	この skill を使用する際のツール許可リスト
metadata.always	boolean	always と同じ（ネスト形式）
metadata.emoji	string	表示アイコン
metadata.os	string[]	プラットフォーム制限（空 = すべてのプラットフォーム）
metadata.requires.bins	string[]	必須 CLI ツール
metadata.requires.env	string[]	必須環境変数

常時有効な Skill

always: true が設定された skill は、Agent 設定で宣言しなくても、Agent が起動するたびに system prompt へ自動的に読み込まれます。これはプロジェクトレベルの基本標準に便利です。

ツール許可リスト

allowedTools フィールドでは、その skill を使用する際に Agent が利用できるツールのセットを制限できます。これは、たとえば次のようなセキュリティ上慎重な扱いが必要な場面で便利です。

allowedTools:
  - Read
  - Grep
  - Glob

これにより、Agent が利用できるツールは読み取り専用ツールに制限されます。

Skill 作成のベストプラクティス

明確な構造

---
name: API Design Standards
description: RESTful API design guide and naming conventions
---

# API Design Standards

## Naming Rules
- URLs use kebab-case
- Query parameters use camelCase

## Status Code Usage
- 200: Success
- 201: Created
- 400: Bad request parameters

## Checklist
- [ ] Does the URL conform to RESTful conventions?
- [ ] Is there appropriate error handling?
- [ ] Is pagination supported?

実践的なヒント

1. 単一のトピックに集中する - 1 つの skill で 1 つの問題カテゴリを扱います
2. 具体例を提供する - コードスニペットやテンプレートを含めます
3. チェックリストを使う - Agent が体系的に実行しやすくなります
4. スコープを明示する - skill の前提条件と制限事項を説明します
5. 簡潔に保つ - コンテキストウィンドウを過度に消費する長すぎる skill 内容は避けます

FAQ

Problem	Cause	Solution
Agent が skill を見つけられない	skill ファイルが正しいパスにない、または名前が一致していない	list_skills を使って利用可能な skill 名を確認する
Skill の内容が system prompt に注入されない	Agent 設定で宣言されておらず、always が false になっている	skills フィールドに追加するか、always: true を設定する
skill が必要とするツールを利用できない	Agent のツール許可リストに必要なツールが含まれていない	必要なツールを Agent 設定に追加する
プラットフォーム制限により skill を利用できない	metadata.os が現在のプラットフォームを制限している	os フィールドを変更するか、現在のプラットフォームに必要な依存関係をインストールする
Skill の内容が長すぎてパフォーマンスに影響している	Skill の内容がコンテキストウィンドウを過度に消費している	複数の小さな skill に分割し、必要に応じて読み込む
SkillHub 検索で結果が返らない	検索キーワードが一致していない	別のキーワードを試すか、英語で検索する

関連リンク

• Agent Overview - Agent システムの概要
• Creating Custom Agents - Agent で skill を設定する
• Tool Permissions & Security - ツール許可リストの仕組み