> ## Documentation Index
> Fetch the complete documentation index at: https://docs.qoder.com/llms.txt
> Use this file to discover all available pages before exploring further.

# スキル

Skill とは、特定の作業を Qoder CLI に教えるための [**SKILL.md**](http://SKILL.md) を含むフォルダです。たとえば、チームの基準に沿った PR レビュー、好みの形式でのコミットメッセージ生成、社内データベースのスキーマ照会などを行えます。Qoder CLI に Skill の目的に合致する依頼をすると、Qoder CLI はその Skill を自動的に適用します。

**主な機能**：

* **インテリジェントな呼び出し**：ユーザーのリクエストと Skill の説明に基づき、モデルが自律的に Skill を使用するタイミングを判断します。
* **モジュール設計**：各 Skill は特定の種類のタスク解決に特化しています。
* **柔軟な拡張**：ユーザーレベルとプロジェクトレベルの両方でカスタム Skill をサポートします。

## クイックスタート

この例では、API ドキュメントを生成するための Skill を作成します。

### 1. Skill ディレクトリの作成

個人の Skills フォルダにディレクトリを作成します。個人の Skill はすべてのプロジェクトに適用されます。また、`.qoder/skills/` にプロジェクトレベルの Skill を作成してチームと共有することもできます。

```bash theme={null}
# ユーザーレベルの Skills ディレクトリを作成
mkdir -p ~/.qoder/skills/api-doc-generator
```

### 2. SKILL.md の作成

すべての Skill には `SKILL.md` ファイルが必要です。このファイルは、`---` マーカーで囲まれた YAML メタデータで始まり、そのメタデータには `name` と `description` を必ず含める必要があります。その後に Markdown 形式で指示を記述します。

`~/.qoder/skills/api-doc-generator/SKILL.md` を作成します：

```markdown theme={null}
---
name: api-doc-generator
description: Generate comprehensive API documentation from code. Use when creating API docs, documenting endpoints, or generating OpenAPI specs.
---

# API Documentation Generator

When generating API documentation:
1. Identify all API endpoints and routes
2. Document request/response formats
3. Include authentication requirements
4. Add example requests and responses
5. Generate OpenAPI/Swagger specification if needed
```

### 3. Skill のロードと検証

新しいセッションでは起動時に Skill がロードされます。Qoder CLI がすでに実行中の場合は、`/skills reload` で検出済み Skill を更新できます。正常にロードされたことを確認します：

```
What Skills are available?
```

または、次の Command を使用します：

```
/skills
```

会話には `api-doc-generator` がその説明とともに表示されるはずです。

### 4. Skill のテスト

プロジェクト内の API ルートファイルを開き、Skill の説明に一致する質問をします：

```
Generate documentation for this API
```

Qoder CLI は `api-doc-generator` Skill を適用し、関連する API ドキュメントを生成します。トリガーされない場合は、説明にあるキーワードを使って表現を変えてみてください。

## Skill の仕組み

Skill は、Command によってロードされるか、モデルによって自動的に呼び出されます。モデルはリクエストの内容に基づいてどの Skill を使用するかを判断するため、明示的な指定は不要です。

1. 起動時、Qoder CLI は各 Skill の名前と説明をロードします。これにより、高速な起動を維持しつつ、モデルが各 Skill の適用可能なシナリオを理解できるようになります。
2. リクエストが Skill の説明と一致すると、モデルはその Skill の使用をリクエストし、完全な `SKILL.md` をロードします。一部の Skill は追加確認なしで実行できますが、追加の権限が必要な Skill は承認を求めることがあります。ユーザーが一般的に使用するキーワードを含む説明を記述してください。
3. モデルは Skill の指示に従い、必要に応じて参照されているファイルをロードしたり、スクリプトを実行したりします。

### Skill の保存場所

保存場所によって Skill の利用可能性が決まります：

| 場所        | パス                                      | スコープ               | ユースケース                         |
| --------- | --------------------------------------- | ------------------ | ------------------------------ |
| ユーザーレベル   | `~/.qoder/skills/{skill-name}/SKILL.md` | 現在のユーザーのすべてのプロジェクト | 個人のワークフロー、実験的な Skill、個人用ツール    |
| プロジェクトレベル | `.qoder/skills/{skill-name}/SKILL.md`   | 現在のプロジェクトのみ        | チームのワークフロー、プロジェクト固有の知識、共有スクリプト |

名前が競合する場合、ユーザーレベルの Skill がプロジェクトレベルの Skill をオーバーライドします。

### Skill と Command の違い

中心的な違いは、**Skill は手動での呼び出しと自動トリガーの両方をサポートする**のに対し、Command は明示的な `/command-name` の入力が必要である点です。

| 機能     | Skill                             | Command              |
| ------ | --------------------------------- | -------------------- |
| トリガー方法 | 自動 (モデルベース) または手動 (`/skill-name`) | 手動 (`/command-name`) |
| 主な用途   | 専門知識、複雑なワークフロー                    | 迅速なプリセットタスク          |
| 保存場所   | `skills/` ディレクトリ                  | `commands/` ディレクトリ   |
| 権限     | Skill の内容によって承認が必要な場合があります        | 不要                   |

> **注：** 内部的に、Skill は特殊な Command タイプに変換され、同じ実行メカニズムを共有します。

## Skill の使用場面

**Skill の使用が適しているケース**：

* **複雑で専門的なタスク**：ドメイン知識を必要とするワークフロー (コードレビュー、PDF 処理、API 設計)
* **標準化されたプロセス**：固定された手順に従うタスク (コミット規約、デプロイフロー)
* **チームの知識共有**：ベストプラクティスをパッケージ化して共有
* **反復的な作業**：専門的なガイダンスを必要とする頻繁に実行されるタスク

**Command の使用が適しているケース**：

* シンプルで迅速な操作
* ユーザーによる明示的なトリガーが必要なタスク
* 複雑なプロンプトガイダンスを必要としないタスク

## Skill の作成

### 保存場所の選択

| タイプ       | パス                                      | スコープ               |
| --------- | --------------------------------------- | ------------------ |
| ユーザーレベル   | `~/.qoder/skills/{skill-name}/SKILL.md` | 現在のユーザーのすべてのプロジェクト |
| プロジェクトレベル | `.qoder/skills/{skill-name}/SKILL.md`   | 現在のプロジェクトのみ        |

> **ヒント：** ユーザーレベルの Skill は、同じ名前のプロジェクトレベルの Skill をオーバーライドします。

**ディレクトリの作成**：

```bash theme={null}
# ユーザーレベル
mkdir -p ~/.qoder/skills/my-skill-name

# プロジェクトレベル
mkdir -p .qoder/skills/my-skill-name
```

### ディレクトリ構造の整理

**ディレクトリ構造の例**：

```
{skill-name}/
├── SKILL.md              # Required: main file
├── REFERENCE.md          # Optional: reference
├── EXAMPLES.md           # Optional: documentation examples
├── scripts/              # Optional: helper scripts
│   └── helper.py  
└── templates/            # Optional: template files
    └── template.txt     
```

`SKILL.md` 内で補助ファイルを参照し、段階的開示を行います：

```markdown theme={null}
For better usage,see [REFERENCE.md]. For examples, see [EXAMPLES.md].

Run the helper script:

python scripts/helper.py input.txt
```

### SKILL.md の作成

YAML フロントマターと Markdown コンテンツを含む `SKILL.md` を作成します：

```markdown theme={null}
---
name: skill-name
description: Brief description of functionality and when to use
---

# Skill Name

## Instructions
Provide clear step-by-step guidance.

## Examples
Show specific usage examples.
```

**フロントマターのフィールド**：

| フィールド         | 必須 | 説明                      | 制約                     |
| ------------- | -- | ----------------------- | ---------------------- |
| `name`        | はい | Skill の一意な識別子           | 小文字、数字、ハイフンのみ。最大 64 文字 |
| `description` | はい | モデルがいつ使用するかを判断するための機能説明 | 最大 1024 文字             |

> **重要：** `description` フィールドは、モデルがいつあなたの Skill を使用すべきかを発見するために不可欠です。Skill が何をするのか、いつ使用するのかを含めてください。詳細は「ベストプラクティス」セクションをご参照ください。

## Skill の使用

### 自動トリガー

ニーズを直接記述すると、モデルが Skill を使用するかどうかを自動的に判断します：

```
Analyze the errors in this log file
```

モデルは `log-analyzer` Skill を認識し、呼び出します。

### 手動トリガー

`/skill-name` を使用して手動でトリガーします：

```
/log-analyzer
```

### 利用可能な Skill の表示

**CLI 内で**：

```
What Skills are available?
```

**ファイルシステム経由で**：

```bash theme={null}
# ユーザーレベルの Skill を一覧表示
ls ~/.qoder/skills/

# プロジェクトレベルの Skill を一覧表示
ls .qoder/skills/

# SKILL.md ファイルを表示
ls ~/.qoder/skills/*/SKILL.md
ls .qoder/skills/*/SKILL.md
```

## 更新と削除

### Skill の更新

`SKILL.md` を直接編集します。新しいセッションでは起動時に更新が読み込まれます。Qoder CLI がすでに実行中の場合は、`/skills reload` で検出済み Skill を更新します。

### Skill の削除

Skill ディレクトリを削除します：

```bash theme={null}
# ユーザーレベル
rm -rf ~/.qoder/skills/my-skill

# プロジェクトレベル
rm -rf .qoder/skills/my-skill
```

> **警告：** Skill ディレクトリを削除すると、すべてのファイルが完全に削除され、復元はできません。

## ベストプラクティス

### Skill の焦点を絞る

各 Skill は、1 つの特定のドメインまたはタスクタイプに焦点を当てるべきです。

**推奨**：

* `log-analyzer` - ログ分析
* `security-auditor` - セキュリティ監査
* `database-migrator` - データベースマイグレーション

**非推奨**：

* `coding-helper` - 広すぎる

### 明確な説明を記述する

`description` には、Skill が何をするか、いつ使用するか、そして主要なトリガーワードを含めるべきです。

**比較**：

```yaml theme={null}
# 非推奨：曖昧
description: Helps with logs

# 推奨：具体的
description: Analyze log files to identify errors, patterns, and performance issues. Use when debugging logs, investigating errors, or monitoring application behavior.
```

### 共有前のテスト

共有する前に、以下を確認してください：

* Skill が期待されるシナリオでトリガーされること
* 指示が明確であること
* 一般的なエッジケースがカバーされていること

### バージョン変更の記録

SKILL.md にバージョン履歴を追加します：

```markdown theme={null}
## Version History

- v2.0.0 (2026-10-01): Breaking API changes
- v1.1.0 (2026-09-15): New features
- v1.0.0 (2026-09-01): Initial release
```

## トラブルシューティング

### Skill がトリガーされない

**ファイルの場所を確認**：

```bash theme={null}
ls ~/.qoder/skills/*/SKILL.md
ls .qoder/skills/*/SKILL.md
```

`SKILL.md` が正しいパスに存在することを確認します。

**YAML フォーマットの確認**：

`SKILL.md` を表示して、フロントマターに構文エラー (インデント、引用符の対応など) がないことを確認します。

**説明の具体性の確認**：

明確で具体的な説明を使用します：

```yaml theme={null}
# 推奨：明確な目的とトリガー条件
description: Analyze log files to identify errors, patterns, and performance issues. Use when debugging logs, investigating errors, or monitoring application behavior.

# 非推奨：曖昧
description: For logs
```

### Skill の実行エラー

**依存関係の可用性の確認**：

CLI は、必要に応じて (または許可を求めて) 必要な依存関係を自動的にインストールします。

**スクリプトの権限を確認**：

```bash theme={null}
chmod +x .qoder/skills/my-skill/scripts/*.py
```

### 複数の Skill の競合

CLI が類似した Skill を混同する場合、説明に異なるトリガー用語を使用して区別します。

## 例

### 例 1：シンプルな Skill

ログファイルを分析し、問題を診断します。

**ディレクトリ構造**：

```
log-analyzer/
└── SKILL.md
```

**SKILL.md**：

```markdown theme={null}
---
name: log-analyzer
description: Analyze log files to identify errors, patterns, and performance issues. Use when debugging logs, investigating errors, or monitoring application behavior.
---

# Log Analyzer

## Instructions

1. Read the log file to understand its format
2. Identify and categorize issues:
   - Error patterns and stack traces
   - Warning messages
   - Performance bottlenecks
   - Unusual patterns or anomalies
3. Provide summary with:
   - Issue severity and frequency
   - Root cause analysis
   - Recommended solutions

## Analysis tips

- Focus on recent critical errors first
- Look for recurring patterns
- Check timestamp correlations across entries
```

### 例 2：複数ファイルの使用

データベースのマイグレーションとバージョン管理ツール。

**ディレクトリ構造**：

```
database-migrator/
├── SKILL.md
├── MIGRATION_GUIDE.md
├── ROLLBACK.md
└── scripts/
    ├── generate_migration.py
    ├── validate_schema.py
    └── backup_db.sh
```

**SKILL.md**：

````markdown theme={null}
---
name: database-migrator
description: Generate and manage database migrations, schema changes, and data transformations. Use when creating migrations, modifying database schema, or managing database versions. Requires sqlalchemy and alembic packages.
---

# Database Migrator

## Quick start

Generate a new migration:

```bash
python scripts/generate_migration.py --name add_user_table
```

For detailed migration patterns, see [MIGRATION_GUIDE.md](MIGRATION_GUIDE.md).
For rollback strategies, see [ROLLBACK.md](ROLLBACK.md).

## Workflow

1. **Analyze changes**: Compare current schema with desired state
2. **Generate migration**: Create migration file with up/down operations
3. **Validate**: Run `python scripts/validate_schema.py` to check syntax
4. **Backup**: Execute `scripts/backup_db.sh` before applying
5. **Apply**: Run migration in staging environment first
6. **Verify**: Check data integrity after migration

## Requirements

Install required packages:
```bash
pip install sqlalchemy alembic psycopg2-binary
```

## Safety checks

- Always backup before migrations
- Test rollback procedures
- Validate data integrity after changes
- Use transactions for atomic operations
````