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

# Skill Format

> エージェントが確実に従うSKILL.mdファイルの書き方 — ファイル構造、フロントマターフィールド、指示パターン

スキルは単一の `SKILL.md` ファイルです: メタデータ用のYAMLフロントマターと、エージェントが従う指示を含むMarkdown本文で構成されます。このページはそのフォーマットのリファレンスです — 構造、フロントマターフィールド、そしてエージェントが最も確実に適用する指示パターンを説明します。

## ファイル構造

すべてのスキルは同じ形式に従います — フロントマターが最初で、次にMarkdown見出しとして指示セクションが続きます:

```markdown theme={null}
---
name: security-review-checklist          # スラグ形式: 小文字、ハイフン
description: Enforce OWASP checks in code review   # スキルカードに表示
---

## SQL injection                         # ルールグループごとに1つのH2

- Flag raw string concatenation in SQL queries
- Require parameterized queries or ORM methods

## Secrets handling

- Flag hardcoded credentials, tokens, and API keys
- Require secrets to come from a secrets manager or environment variables
```

| パーツ         | 必須 | 目的                                              |
| ----------- | -- | ----------------------------------------------- |
| フロントマターブロック | はい | スキルを識別する。UIは `name` と `description` をここから読み取る   |
| 指示本文        | はい | スキルが実行されるときエージェントがそのまま読み込むMarkdown              |
| H2ルールグループ   | 推奨 | ドメインごとに1つの見出しを置くと、あなたとエージェントの両方にとってルールが把握しやすくなる |
| インライン例      | 推奨 | 各ルールを根拠づける具体的な良い例・悪い例                           |

## フロントマターフィールド

| フィールド         | 必須 | 説明                                                          |
| ------------- | -- | ----------------------------------------------------------- |
| `name`        | はい | スラグ形式の一意識別子（小文字、ハイフン、スペースなし）。例: `security-review-checklist` |
| `description` | はい | スキルの機能の短い概要。UIのスキルカードに表示される。                                |

## 効果的な指示の書き方

### トークンを無駄にしない

エージェントはスキルの指示を、自身のシステムプロンプトとタスクコンテキストと並行して処理します。指示は簡潔に書いてください — エージェントがすでに知っていないことだけを書きます。

```markdown theme={null}
<!-- 冗長すぎる例 -->
When reviewing code, you should always check for SQL injection
vulnerabilities. SQL injection is a type of security vulnerability
where an attacker can execute arbitrary SQL commands through
user input that is not properly sanitized...

<!-- 効果的な例 -->
## SQL Injection
- Flag raw string concatenation in SQL queries
- Require parameterized queries or ORM methods
- Check for `execute()` calls with f-strings or `.format()`
```

### 自由度のレベル

エージェントに持たせたい柔軟性に合わせて指示スタイルを選択します:

| 自由度   | スタイル          | ユースケース                             |
| ----- | ------------- | ---------------------------------- |
| **高** | ガイドラインと原則     | クリエイティブなタスク、アーキテクチャのアドバイス、探索的なレビュー |
| **中** | 例付きチェックリスト    | 標準的なコードレビュー、セキュリティ監査、コンプライアンスチェック  |
| **低** | 厳密なテンプレートとルール | 法規制コンプライアンス、フォーマット標準、必須フィールド       |

### 説明より例

エージェントは抽象的なルールより具体的な例をより確実に따います。可能な場合は、説明するのではなく期待される動作を示してください。

```markdown theme={null}
## Naming conventions

Use descriptive variable names that reveal intent.

### Good
- `remaining_retries` not `r`
- `is_authenticated` not `auth`
- `max_connection_pool_size` not `pool`

### Bad
- Single-letter variables outside loop iterators
- Abbreviations that aren't universally understood
- Boolean variables without `is_`, `has_`, or `should_` prefix
```

## 完全な例

PRレビュー標準を適用するための実際的なスキル:

````markdown theme={null}
---
name: pr-review-standards
description: Enforce team PR review standards including size limits, test coverage, and documentation requirements
---

## PR Size

- Flag PRs with more than 500 lines changed as "needs splitting"
- Warn on PRs with more than 10 files changed
- Suggest logical split points when flagging oversized PRs
- Auto-generated files (migrations, lockfiles) do not count toward limits

## Test Coverage

- Require test files for any new public function or method
- Flag removed tests without corresponding feature removal
- Check that edge cases are covered, not just happy paths

## Documentation

- Require JSDoc/docstring for exported functions with more than 3 parameters
- Flag breaking API changes without migration guide updates
- Check that README is updated when adding new environment variables

## Review Comment Format

Use this structure for review comments:

```
**[severity]** Brief title

Description of the issue.

**Suggestion:** How to fix it.
```

Severity levels: `critical`, `warning`, `suggestion`, `nitpick`
````

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

<AccordionGroup>
  <Accordion title="スキル名が拒否される">
    `name` フィールドはスラグ形式である必要があります: 小文字、数字、ハイフンのみ。スペース、アンダースコア、特殊文字は使用できません。

    * `security-checklist` — 有効
    * `Security Checklist` — 無効
    * `security_checklist` — 無効
  </Accordion>

  <Accordion title="エージェントがスキルの指示を無視する">
    * スキルが **有効化** されているか確認する（トグルがオン）
    * スキルが正しい機能に **割り当て** られているか確認する
    * 指示が具体的で実行可能か確認する — 曖昧なガイダンスは優先度が下がりやすい
    * 長く広範なスキルより短く焦点を絞ったスキルの方が確実に適用される
  </Accordion>

  <Accordion title="指示が長すぎる">
    スキルが数百行を超える場合は、複数の焦点を絞ったスキルに分割することを検討してください。エージェントは一つの巨大なスキルより複数の短いスキルをより適切に処理します。

    ドメインで分割してください: セキュリティルール、パフォーマンスガイドライン、スタイル規約を個別のスキルに分けます。
  </Accordion>
</AccordionGroup>

## 関連

<CardGroup cols={2}>
  <Card title="Custom Skills" icon="wand-magic-sparkles" href="/ja/guide/skills/custom-skills">
    ワークスペースでスキルを作成・アップロード・有効化・割り当てる。
  </Card>

  <Card title="Skills Overview" icon="sparkles" href="/ja/guide/skills/overview">
    CloudThinkerプラットフォームとエージェントワークフローにおけるSkillsの位置付けを理解する。
  </Card>
</CardGroup>