Windsurfの設定 - Agent Skills

概要

Agent Skillsは、WindsurfのCascadeが複雑な多段階タスクを実行するためのフォルダベースのリソースである。
SKILL.mdファイルと支援ファイル群をバンドルして、デプロイメント、コードレビュー、テスト自動化といったワークフローを標準化する仕組みである。

ルール (Rules) が「コーディング規約やスタイルの制約」を定義するのに対し、スキルは「実行手順を持つ多段階ワークフロー」を定義する。
また、ワークフロー (Workflows) がスラッシュコマンドで呼び出す反復タスクの自動化であるのに対し、スキルはdescriptionベースの自動判断と@メンション呼び出しを持つ点で異なる。

下表に、Agent Skillsの主な特徴を示す。

Agent Skillsの特徴
特徴	説明
段階的読み込み（Progressive Disclosure）	Discovery -> Activation -> Executionの3段階でコンテキストコストを最適化する。
自動呼び出しと手動呼び出しの両対応	descriptionフィールドに基づくCascadeの自動判断に加え、 `@<スキル名>` による明示的な呼び出しが可能である。
支援ファイルの同梱	スクリプト、ドキュメント、設定ファイルをスキルディレクトリに配置でき、 Cascadeがオンデマンドで参照する。
オープンスキル標準への準拠	agentskills.io のSKILL.md仕様に準拠しており、 Claude Code等の他のAIコーディングツールとスキルの構造を共有できる。

Claude Codeも同様にSKILL.mdベースのスキルを採用しているが、
モデル指定 (model)・温度設定 (temperature) が可能な点、スラッシュコマンド (/<スキル名>) で呼び出す点がWindsurfと異なる。

一方、WindsurfのAgent Skillsはdescriptionベースの自動呼び出し機構と段階的読み込みモデルを特徴とする。

Agent Skillsの基本概念

ルール・スキル・ワークフローの比較

Windsurfには、Cascadeの動作をカスタマイズする3つの仕組みが存在する。

ルール・スキル・ワークフローの比較
項目	Rules (ルール)	Skills (スキル)	Workflows (ワークフロー)
用途	コーディング規約、言語選択、スタイルガイドライン	複雑な多段階ワークフロー、テンプレート活用タスク	反復タスクの自動化
形式	単一Markdownファイル	SKILL.md + 支援ファイル群	単一Markdownファイル
配置場所	.windsurf/rules/*.md	.windsurf/skills/<<スキル名>>/	.windsurf/workflows/*.md
呼び出し方法	自動 (発動モード: Manual / Always On / Model Decision / Glob)	自動 (descriptionベース) または手動 (@<スキル名>)	スラッシュコマンド (/workflow-name)
適用タイミング	常時またはパターンマッチ時	タスク実行時のみ	呼び出し時のみ
文字数制限	個別6,000文字、合計12,000文字	SKILL.mdは、500行以下推奨	12,000文字
フロントマター	あり (trigger等)	あり (name, description 必須)	なし

SKILL.mdファイルの構造

SKILL.mdファイルは、YAMLフロントマター + Markdown指示セクションで構成される。
YAMLフロントマターにはスキルのメタデータを記述し、Markdown指示セクションにはスキルの実行手順を記述する。

SKILL.mdの基本構造を以下に示す。

 ---
 name: <スキル名>
 description: スキルの説明 (Cascadeが自動呼び出しの判断に使用)
 license: MIT
 compatibility: Node.js 18+, npm
 metadata:
   author: team-name
   version: "1.0"
 allowed-tools: bash git
 ---
 
 ## Purpose
 このスキルの目的を記述する。
 
 ## Prerequisites
 - 前提条件1
 - 前提条件2
 
 ## Step-by-step Procedure
 1. 手順1
 2. 手順2
 3. 手順3
 
 ## Supporting Resources
 - 参照ファイル1 (scripts/deploy.sh)
 - 参照ファイル2 (references/checklist.md)

YAMLフロントマターの詳細

SKILL.mdのYAMLフロントマターには、スキルのメタデータを定義する。
フロントマターは --- で区切られたブロックとして、ファイルの先頭に配置する必要がある。

YAMLフロントマターフィールド一覧
フィールド	必須/任意	制約	説明
name	必須	1〜64文字、小文字英数字とハイフンのみ先頭・末尾のハイフンおよび連続ハイフンは不可親ディレクトリ名と一致させることを推奨	スキルの一意な識別子 UIに表示され、@メンションでも使用される
description	必須	1〜1024文字	スキルの簡潔な説明 Cascadeが自動呼び出しの判断に使用する最も重要なフィールド
license	任意	ライセンス名またはライセンスファイルへの参照	スキルのライセンス情報
compatibility	任意	最大500文字	実行環境の要件 (例: Node.js 18+, Python 3.10+)
metadata	任意	文字列のキーバリューペア	カスタムプロパティ (author, version等)
allowed-tools	任意 (実験的)	スペース区切りのツールリスト	スキル実行時に事前承認されるツールサポート状況はエージェント実装により異なる。

name フィールドの記述例を以下に示す。

nameフィールドの記述例
有効な例	無効な例
deploy-to-staging	Deploy_To_Staging (大文字・アンダースコア不可)
code-review	-code-review (先頭ハイフン不可)
setup-dev-env	setup--dev--env (連続ハイフン不可)

description フィールドの記述例を以下に示す。

descriptionフィールドの記述例
良い例	悪い例
Guides the deployment process to production with safety checks and monitoring	デプロイを行う
Performs comprehensive code review focusing on security, performance, and best practices	レビュー
Automates test suite execution with coverage reporting and failure analysis	テストする

Markdown指示セクション

YAMLフロントマターに続くMarkdown本文には、スキルの実行手順を記述する。
仕様上、Markdown本文の形式に制限はないが、以下に示す構造が推奨される。

SKILL.mdの主なセクション
セクション	説明
Purpose	スキルの目的と実行内容
Prerequisites	スキル実行前に必要な条件（ツール、設定、ファイル等）
Step-by-step Procedure	具体的な実行手順を番号付きリストで記述
Supporting Resources	スキルディレクトリ内の参照ファイルへのリンク

仕様では、SKILL.mdを500行以下に保つことが推奨されている。
詳細な参照資料は references/ 等のサブディレクトリに移動し、Markdown指示セクションからリンクする。

ディレクトリ構造

スキルは以下のディレクトリ構造で構成される。

.windsurf/skills/<スキル名>/
├── SKILL.md          # コア指示ファイル (必須)
├── scripts/          # 実行可能スクリプト (Python, Bash等)
├── references/       # 参照ドキュメント (Markdown, テキスト等)
└── assets/           # 設定ファイル、テンプレート (YAML, JSON等)

下表に、各ディレクトリの用途を示す。

スキルディレクトリの構成要素
ディレクトリ/ファイル	必須/任意	用途	配置するファイル例
SKILL.md	必須	スキルのメタデータと実行指示	-
scripts/	任意	Cascadeが実行するスクリプト	deploy.sh, validate.py, build.sh
references/	任意	手順書、チェックリスト、ガイドライン	checklist.md, api-reference.md, coding-guide.md
assets/	任意	設定テンプレート、サンプルデータ	config.yaml, template.json, schema.json

ファイル参照のガイドラインを以下に示す。

ファイル参照はスキルルートからの相対パスを使用する。
ディレクトリのネストは1階層のみを推奨する。(コンテキスト管理の最適化のため)
支援ファイルはCascadeによってオンデマンドで読み込まれるため、大量に配置してもDiscoveryフェーズのコストに影響しない。

ワークスペーススキルとグローバルスキル

スキルには、プロジェクト固有のワークスペーススキルと全プロジェクト共通のグローバルスキルの2種類が存在する。

ワークスペーススキルとグローバルスキルの比較
項目	ワークスペーススキル	グローバルスキル
配置場所	.windsurf/skills/<スキル名>/	~/.codeium/windsurf/skills/<スキル名>/
適用範囲	配置されたプロジェクト内のみ	全てのワークスペース
用途	プロジェクト固有のデプロイ手順、レビュー基準、テスト手順	個人の共通ワークフロー、汎用的なユーティリティスキル
バージョン管理	Git管理に含めてチーム共有が可能	ユーザのホームディレクトリに配置 (Git管理外)
優先順位	グローバルスキルよりも優先される	ワークスペーススキルが存在する場合はそちらが優先

使い分けの指針を以下に示す。

スキルの使い分け指針
種別	説明
ワークスペーススキル	プロジェクト固有のデプロイ手順、CI/CDパイプラインの操作、プロジェクト固有のコードレビュー基準等に使用する。 Gitリポジトリに含めることにより、チームメンバー全員で共有できる。
グローバルスキル	個人的に使用するユーティリティスキルに使用する。例: Git操作の自動化、共通テンプレートの生成複数プロジェクトで横断的に使用するスキルに適している。

スキルの作成手順

ステップ 1 : スキルディレクトリの作成

プロジェクトの .windsurf/skills/ ディレクトリにスキル用のディレクトリを作成する。

# ワークスペーススキルの場合 :

mkdir -p .windsurf/skills/my-deploy-skill

# グローバルスキルの場合 :

mkdir -p ~/.codeium/windsurf/skills/my-utility-skill

ディレクトリ名は、SKILL.mdファイルの name フィールドと一致させることを推奨する。

ステップ 2 : SKILL.mdファイルの作成

スキルディレクトリ内に SKILL.md ファイルを作成する。
ファイル名は、必ず SKILL.md (大文字) とする。

touch .windsurf/skills/my-deploy-skill/SKILL.md

ステップ 3 : YAMLフロントマターの記述

SKILL.mdファイルの先頭にYAMLフロントマターを記述する。
必須項目である name と description を必ず記述する。

 ---
 name: my-deploy-skill
 description: Automates deployment to staging environment with pre-flight checks and rollback capability
 ---

ステップ 4 : Markdown指示の記述

YAMLフロントマターの後に、スキルの実行手順をMarkdown形式で記述する。

 ## Purpose
 ステージング環境へのデプロイを自動化する。
 
 ## Prerequisites
 - Docker がインストールされていること
 - .env.staging が正しく設定されていること
 - テストが全てパスしていること
 
 ## Step-by-step Procedure
 1. テスト結果の確認 (`npm test` の実行)
 2. Docker イメージのビルド
 3. ステージング環境へのデプロイ
 4. ヘルスチェックの実行
 5. デプロイログの出力
 
 ## Error Handling
 - テスト失敗時: デプロイを中止し、失敗したテストを報告
 - ビルド失敗時: エラーログを出力し、原因を分析
 - ヘルスチェック失敗時: ロールバック手順 (references/rollback.md) を実行

ステップ 5 : 支援ファイルの配置

必要に応じて、scripts/、references/、assets/ ディレクトリに支援ファイルを配置する。

.windsurf/skills/my-deploy-skill/
├── SKILL.md
├── scripts/
│   └── deploy.sh
├── references/
│   ├── rollback.md
│   └── health-check.md
└── assets/
    └── docker-compose.staging.yaml

ステップ 6 : テストと動作確認

作成したスキルの動作を確認する。

Cascadeの入力ボックスに @my-deploy-skill と入力して手動呼び出しをテストする。
スキルが正しく認識されているか確認する。
指示通りに各ステップが実行されるか確認する。
支援ファイルが正しく参照されるか確認する。

スキルの呼び出し方法

自動呼び出し

Cascadeは、ユーザのリクエスト内容とスキルの description フィールドを照合し、関連性の高いスキルを自動的に呼び出す。

下表に、自動呼び出しの動作例を示す。

自動呼び出しの動作例
ユーザ入力	動作
"ステージング環境にデプロイしたい"	descriptionに "deployment" や "staging" を含むスキルが自動的に検出・実行される。
"このプルリクエストのコードレビューをお願い"	descriptionに "code review" を含むスキルが自動的に検出・実行される。

自動呼び出しを効果的にするポイントを以下に示す。

descriptionに具体的なキーワードを含める。
例: "deployment"、"code review"、"test automation"
descriptionはスキルの用途を正確に反映させる。
曖昧な説明は避け、「何を」「いつ」行うスキルかを明示する。

手動呼び出し (@<スキル名>)

Cascadeの入力ボックスで @<スキル名> と入力することにより、スキルを明示的に呼び出すことができる。

下表に、手動呼び出しの例を示す。

手動呼び出しの例
入力	説明
@deploy-production	本番デプロイスキルを呼び出す。
@code-reviewer このファイルをレビューして	コードレビュースキルを引数付きで呼び出す。
@test-automation src/utils/	テスト自動化スキルを特定のディレクトリに対して実行する。

手動呼び出しが有効な場面を以下に示す。

自動呼び出しでは意図したスキルが選択されない場合
特定のスキルを確実に使用したい場合
descriptionの一致度が低い汎用的なリクエストの場合

段階的読み込みモデル

Agent Skillsは、段階的読み込み (Progressive Disclosure) モデルを採用しており、3つのフェーズでコンテキストコストを最適化する。

段階的読み込みの3フェーズ
フェーズ	名称	読み込み対象	コンテキストコスト	タイミング
Phase 1	Discovery (検出)	YAMLフロントマターの name と description のみ	約100トークン/スキル	セッション開始時
Phase 2	Activation (有効化)	SKILL.mdのMarkdown本文全体	推奨5000トークン以下	スキルが呼び出された時
Phase 3	Execution (実行)	scripts/、references/、assets/ 内の支援ファイル	オンデマンド	スキル実行中に必要になった時

下表に、各フェーズの詳細を示す。

段階的読み込みの各フェーズ
フェーズ	説明
Phase 1 : Discovery（検出）	セッション開始時に、Cascadeは全てのスキルのフロントマター (nameとdescription) のみを読み込む。
	50個のスキルをインストールしていても、Discoveryフェーズのコストは約5000トークンに抑えられる。
	ユーザのリクエストとdescriptionの類似度を評価して、関連性の高いスキルを特定する。
Phase 2 : Activation（有効化）	自動呼び出しまたは手動呼び出しにより、選択されたスキルのSKILL.md全体が読み込まれる。
	SKILL.md本文は50行以下 (ソフトリミット) が推奨され、最大150行 (ハードリミット) とされる。
	Purpose、Prerequisites、手順、コード例が含まれ、即座に実行指示が得られる。
Phase 3 : Execution（実行）	SKILL.md内で参照されている支援ファイル (scripts/、references/、assets/) がオンデマンドで読み込まれる。
	支援ファイルは、スキルの実行中にCascadeが必要と判断した時点でのみ読み込まれる。
	これにより、大量の支援ファイルを配置しても、不要なファイルがコンテキストを圧迫することがない。

サンプル

デプロイ自動化スキル

本番環境へのデプロイを安全に実行するスキルの設定例を以下に示す。

SKILL.md

 ---
 name: deploy-production
 description: Guides production deployment with pre-flight checks, safety validations, monitoring, and rollback capability
 license: MIT
 compatibility: Docker 24+, Node.js 18+, kubectl
 metadata:
   author: devops-team
   version: "2.0"
 ---
 
 ## Purpose
 本番環境へのデプロイメントを安全かつ確実に実行する。
 事前チェック、デプロイ、監視、ロールバックの全プロセスを管理する。
 
 ## Prerequisites
 - 全てのテスト (ユニットテスト、統合テスト) がパスしていること
 - コードレビューが完了し、マージ済みであること
 - Docker と kubectl が設定されていること
 - 環境変数ファイル (.env.production) が正しく設定されていること
 
 ## Step-by-step Procedure
 1. デプロイ準備チェック
    - `npm test` で全テストがパスすることを確認
    - `npm run lint` でリントエラーがないことを確認
    - references/deployment-checklist.md のチェック項目を確認
 
 2. Docker イメージのビルドとプッシュ
    - `scripts/build.sh` を実行
    - イメージタグにGitコミットハッシュを使用
 
 3. ステージング環境での検証
    - ステージングにデプロイして動作確認
    - ヘルスチェックエンドポイントの応答を確認
 
 4. 本番環境へのデプロイ
    - `scripts/deploy.sh production` を実行
    - ローリングアップデートで順次反映
 
 5. デプロイ後の監視
    - ヘルスチェックの確認 (5分間)
    - エラーレートの監視
    - 異常検出時は references/rollback-procedure.md に従いロールバック
 
 ## Error Handling
 - ビルド失敗: エラーログを出力し、デプロイを中止
 - ヘルスチェック失敗: 自動ロールバックを実行
 - ロールバック失敗: 手動介入を要求し、運用チームに通知

references/deployment-checklist.md

 # デプロイメントチェックリスト
 
 ## 事前確認
 - [ ] 全テストがパス
 - [ ] コードレビュー完了
 - [ ] 変更ログの更新
 - [ ] データベースマイグレーションの確認
 - [ ] 環境変数の確認
 
 ## デプロイ中
 - [ ] ロールアウト状況の監視
 - [ ] ヘルスチェックの確認
 - [ ] ログにエラーがないことの確認
 
 ## デプロイ後
 - [ ] 主要機能の動作確認
 - [ ] パフォーマンスメトリクスの確認
 - [ ] Slackへのデプロイ完了通知

scripts/deploy.sh

 #!/usr/bin/env sh
 
 set -euo pipefail
 
 ENVIRONMENT=${1:-staging}
 IMAGE_TAG=$(git rev-parse --short HEAD)
 
 echo "Deploying to ${ENVIRONMENT} with tag ${IMAGE_TAG}..."
 
 # Dockerイメージのビルド
 docker build -t myapp:${IMAGE_TAG} .
 
 # Kubernetesへのデプロイ
 kubectl set image deployment/myapp \
   myapp=myapp:${IMAGE_TAG} \
   --namespace=${ENVIRONMENT}
 
 # ロールアウト完了を待機
 kubectl rollout status deployment/myapp \
   --namespace=${ENVIRONMENT} \
   --timeout=300s
 
 echo "Deployment to ${ENVIRONMENT} completed successfully."

コードレビュースキル

セキュリティ・パフォーマンス・品質において、コードレビューを実行するスキルの設定例を以下に示す。

SKILL.md

 ---
 name: code-reviewer
 description: Performs comprehensive code review with security vulnerability analysis, performance optimization suggestions, and coding standards compliance checks
 metadata:
   author: quality-team
   version: "1.5"
 ---
 
 ## Purpose
 指定されたファイルまたはディレクトリに対して包括的なコードレビューを実行する。
 セキュリティ、パフォーマンス、保守性の3つの観点から分析する。
 
 ## Prerequisites
 - レビュー対象のファイルまたはディレクトリが指定されていること
 
 ## Step-by-step Procedure
 1. レビュー対象の特定
    - 引数で指定されたファイル/ディレクトリを確認
    - 変更されたファイルのみをレビュー対象とする
 
 2. セキュリティ分析
    - SQLインジェクション、XSS等の脆弱性チェック
    - 機密情報 (APIキー、パスワード) のハードコーディングチェック
    - 入力バリデーションの確認
    - references/security-checklist.md を参照
 
 3. パフォーマンス分析
    - N+1クエリ、不要なループの検出
    - メモリリーク、リソースリークの検出
    - アルゴリズム効率の評価
 
 4. コーディング規約チェック
    - 命名規則の準拠確認
    - コード構造の一貫性
    - コメントとドキュメントの充実度
 
 5. レビュー結果の出力
    - references/review-template.md のテンプレートに従い出力
 
 ## Output Format
 レビュー結果は以下の形式で出力する:
 1. 🔴 重大な問題 (修正必須)
 2. 🟡 中程度の問題 (修正推奨)
 3. 🟢 軽微な問題 (改善提案)
 4. ✅ 良い点 (コメント)

references/security-checklist.md

 # セキュリティチェックリスト
 
 ## 入力処理
 - [ ] ユーザ入力のサニタイズ
 - [ ] SQLクエリのパラメータ化
 - [ ] HTMLエスケープ処理
 
 ## 認証・認可
 - [ ] 認証トークンの適切な管理
 - [ ] 権限チェックの実装
 - [ ] セッション管理の安全性
 
 ## データ保護
 - [ ] 機密情報のハードコーディング禁止
 - [ ] HTTPSの使用
 - [ ] ログへの機密情報出力禁止

テスト自動化スキル

テストスイートの実行とカバレッジレポート生成を自動化するスキルの設定例を以下に示す。

SKILL.md

 ---
 name: test-automation
 description: Executes test suite with coverage analysis, generates failure reports, and suggests fixes for failing tests
 compatibility: Node.js 18+, Jest or Vitest
 metadata:
   author: qa-team
   version: "1.0"
 ---
 
 ## Purpose
 プロジェクトのテストスイートを実行し、カバレッジ分析とレポート生成を行う。
 テスト失敗時は原因分析と修正提案を行う。
 
 ## Prerequisites
 - テストフレームワーク (Jest または Vitest) がインストールされていること
 - テスト設定ファイルが存在すること
 
 ## Step-by-step Procedure
 1. テスト環境の確認
    - package.json からテストフレームワークを特定
    - テスト設定ファイル (jest.config.js / vitest.config.ts) を確認
 
 2. テストの実行
    - `npm test -- --coverage` を実行
    - テスト結果と カバレッジレポートを取得
 
 3. 結果の分析
    - 失敗したテストの原因を分析
    - カバレッジが低い箇所を特定
    - references/coverage-thresholds.md のしきい値と比較
 
 4. レポートの生成
    - テスト結果のサマリを出力
    - 失敗テストの修正提案を生成
    - カバレッジ改善のための提案を出力
 
 5. 修正提案 (テスト失敗時)
    - 失敗原因に基づいた具体的な修正コードを提案
    - 不足しているテストケースの追加を提案
 
 ## Error Handling
 - テストフレームワークが見つからない場合: セットアップ手順を提案
 - タイムアウト: タイムアウト設定の調整を提案

references/coverage-thresholds.md

 # カバレッジしきい値
 
 | メトリクス | 最低基準 | 推奨基準 |
 |------------|----------|----------|
 | Statements | 70% | 85% |
 | Branches   | 65% | 80% |
 | Functions  | 70% | 85% |
 | Lines      | 70% | 85% |

ドキュメント生成スキル

ソースコードからAPIドキュメントを自動生成するスキルの設定例を以下に示す。

SKILL.md

 ---
 name: doc-generator
 description: Generates comprehensive API documentation and usage guides from source code analysis with JSDoc/TSDoc parsing
 metadata:
   author: docs-team
   version: "1.2"
 ---
 
 ## Purpose
 ソースコードを解析し、APIドキュメントと使用ガイドを自動生成する。
 既存のJSDoc/TSDocコメントを活用しつつ、不足している箇所も補完する。
 
 ## Prerequisites
 - TypeScript または JavaScript のプロジェクトであること
 - docs/ ディレクトリが存在すること (なければ作成)
 
 ## Step-by-step Procedure
 1. ソースコードの解析
    - src/ ディレクトリ内の全ファイルをスキャン
    - エクスポートされた関数、クラス、型を抽出
    - 既存のJSDoc/TSDocコメントを解析
 
 2. ドキュメント構造の決定
    - assets/doc-template.md のテンプレートに従う
    - モジュールごとにセクションを分割
 
 3. API リファレンスの生成
    - 各関数のパラメータ、戻り値、使用例を記述
    - 型情報を含めた詳細な説明を生成
 
 4. 使用ガイドの生成
    - 主要な機能の使い方を記述
    - コード例を含める
 
 5. ドキュメントの出力
    - docs/API.md にAPIリファレンスを出力
    - docs/GUIDE.md に使用ガイドを出力
 
 ## Output Format
 Markdown形式で出力する。
 見出しレベル2 (##) で各モジュール、見出しレベル3 (###) で各関数/クラスを記述。

assets/doc-template.md

 # API Reference
 
 ## Overview
 [プロジェクト概要]
 
 ## Installation
 ```bash
 npm install <package-name>
 ```
 
 ## Modules
 
 ### [Module Name]
 
 #### `functionName(param1: Type, param2: Type): ReturnType`
 [説明]
 
 **Parameters:**
 | Name | Type | Description |
 |------|------|-------------|
 | param1 | Type | 説明 |
 
 **Returns:** ReturnType - 説明
 
 **Example:**
 ```typescript
 const result = functionName('value1', 'value2');
 ```

Claude CodeのSKILLとの比較

WindsurfのAgent SkillsとClaude CodeのSKILLは、共にSKILL.mdファイルを使用するが、細部の仕様が異なる。

WindsurfとClaude CodeのSKILL比較
項目	Claude Code SKILL	Windsurf Agent Skills
ファイル名	SKILL.md	SKILL.md
配置場所 (ワークスペース)	.claude/skills/<スキル名>/	.windsurf/skills/<スキル名>/
配置場所 (グローバル)	~/.claude/skills/<スキル名>/	~/.codeium/windsurf/skills/<スキル名>/
必須フロントマター	name, description	name, description
任意フロントマター	model, temperature, allowedTools, disallowedTools	license, compatibility, metadata, allowed-tools
モデル指定	可能 (model フィールド)	不可
温度設定	可能 (temperature フィールド)	不可
ツール制限	allowedTools / disallowedTools (リスト形式)	allowed-tools (スペース区切り、実験的)
呼び出し方法	/スキル名 (スラッシュコマンド)	@スキル名 (メンション) または自動呼び出し
自動呼び出し	descriptionベースの自動判断	descriptionベースの自動判断
引数の渡し方	/<スキル名> arg1 arg2	@<スキル名> リクエスト内容
段階的読み込み	あり (Discovery -> Activation -> Execution)	あり (Discovery → Activation → Execution)
支援ファイル	同梱可能	scripts/ references/ assets/ に分類

下表に、両者の主な相違点を示す。

Claude Code と Windsurf の相違点
項目	Claude Code	Windsurf
モデル制御	スキルごとにモデルと温度を指定できるため、タスクの性質に応じた精密な制御が可能例: レビューは低温度、創作は高温度	—
メタデータ	-	license、compatibility、metadataフィールドを持ち、スキルの共有と配布に適した構造になっている。
呼び出し方法	スラッシュコマンド (`/<スキル名>`)	Atメンション (`@<スキル名>`)

推奨される事柄

Agent Skillsを効果的に活用するための推奨される事柄を以下に示す。

明確なdescription

description フィールドは、Cascadeがスキルの自動呼び出しを判断する時の最も重要な要素である。

スキルが「何を」「いつ」行うかを具体的に記述する。
ユーザが使用するであろうキーワードを含める。
曖昧な表現は避け、具体的な動作を記述する。

descriptionの記述例
悪い例	良い例
Deploy code	Guides production deployment with safety checks, rollback capability, and post-deploy monitoring
Run tests	Executes full test suite with coverage analysis and generates failure reports with fix suggestions
Review code	Performs security-focused code review checking for SQL injection, XSS, and credential exposure

段階的な手順

Markdown指示セクションでは、実行手順を番号付きリストで明確に記述する。

各手順は1つのアクションに対応させる。
条件分岐がある場合は明示的に記述する。
前提条件と終了条件を明記する。

支援ファイルの活用

SKILL.mdを簡潔に保ち、詳細な情報は支援ファイルに分離する。

scripts/
実行可能なシェルスクリプトやPythonスクリプトを配置する。
references/
チェックリスト、手順書、ガイドラインを配置する。
assets/
設定テンプレート、JSONスキーマ、サンプルデータを配置する。

エラーハンドリング

スキルには、エラー時の対処手順を必ず含める。

想定されるエラーパターンをリストアップする。
各エラーに対する対処手順を明記する。
ロールバック手順がある場合は支援ファイルとして同梱する。

トラブルシューティング

スキルが認識されない

スキルがCascadeに認識されない場合、以下の点を確認する。

ディレクトリ構造の確認
.windsurf/skills/<スキル名>/SKILL.md の構造になっているか確認する。

ファイル名が SKILL.md (大文字) であることを確認する。
YAMLフロントマターの構文確認
--- で囲まれたYAMLブロックがファイル先頭にあるか確認する。

name と description が正しく記述されているか確認する。

YAMLの構文エラー (インデント不正等) がないか確認する。
name フィールドの確認
小文字英数字とハイフンのみで構成されているか確認する。

先頭・末尾にハイフンがないか確認する。
Windsurf Editorの再起動
スキルを追加・変更した後、Windsurf Editorを再起動する。

自動呼び出しが動作しない

Cascadeがスキルを自動的に呼び出さない場合、以下に示す事柄を確認する。

descriptionフィールドの見直し
リクエストとdescriptionのキーワードが一致しているか確認する。

descriptionをより具体的に記述する。
手動呼び出しでのテスト
@スキル名 で手動呼び出しが動作するか確認する。

手動呼び出しが動作する場合、descriptionの改善により自動呼び出しが改善される可能性がある。
類似スキルの競合
類似するdescriptionを持つ複数のスキルが存在しないか確認する。

競合する場合、descriptionをより特化した内容に変更する。

支援ファイルが読み込まれない

scripts/、references/、assets/ 内のファイルが参照されない場合、以下に示す事柄を確認する。

SKILL.md内での参照
Markdown指示セクション内で支援ファイルへの参照が記述されているか確認する。

相対パス (例: references/checklist.md) が正しいか確認する。
ファイルパスの確認
ファイル名にスペースや特殊文字が含まれていないか確認する。

ディレクトリ構造が1階層のネストに収まっているか確認する。
ファイルの内容
支援ファイルが空でないか確認する。

ファイルのエンコーディングがUTF-8であるか確認する。

参考リンク

Windsurfの設定 - Agent Skills

概要

Agent Skillsの基本概念

ルール・スキル・ワークフローの比較

SKILL.mdファイルの構造

YAMLフロントマターの詳細

Markdown指示セクション

ディレクトリ構造

ワークスペーススキル と グローバルスキル

スキルの作成手順

ステップ 1 : スキルディレクトリの作成

ステップ 2 : SKILL.mdファイルの作成

ステップ 3 : YAMLフロントマターの記述

ステップ 4 : Markdown指示の記述

ステップ 5 : 支援ファイルの配置

ステップ 6 : テストと動作確認

スキルの呼び出し方法

自動呼び出し

手動呼び出し (@<スキル名>)

段階的読み込みモデル

サンプル

デプロイ自動化スキル

コードレビュースキル

テスト自動化スキル

ドキュメント生成スキル

Claude CodeのSKILLとの比較

推奨される事柄

明確なdescription

段階的な手順

支援ファイルの活用

エラーハンドリング

トラブルシューティング

スキルが認識されない

自動呼び出しが動作しない

支援ファイルが読み込まれない

参考リンク

ワークスペーススキルとグローバルスキル