mcpField
W
write-a-skill

write-a-skill

github.com/alirezarezvaniエージェントワークフロー29.0k393 回インストール今日更新
リポジトリ

write-a-skill について

write-a-skillは、エージェントやスキル作成者向けのスキル執筆ガイドです。要件収集、草案作成、レビューを整理し、チェックリストツールやスクリプト・ファイル分割の指針も示します。

主な機能

  1. 013段階のスキル作成プロセス
  2. 02SKILL.mdの構成とテンプレート
  3. 03説明と起動条件の指針
  4. 04スクリプトとファイル分割の基準
  5. 05自動レビュー用チェックリスト

活用シーン

  1. 01要件に基づくスキルの草案作成
  2. 02スキルにスクリプトが必要か判断
  3. 03利用前のスキル内容の確認

インストール

コマンドをコピーしてターミナルで実行します。

$npx skills add https://github.com/alirezarezvani/claude-skills --skill write-a-skill

インストール後、Claude Code で/write-a-skillを入力して読み込まれたか確認します。

同梱ファイル

SKILL.md と一緒にインストールされる参考資料やスクリプト。

references/
companion_tooling.md
description_design_patterns.md
progressive_disclosure_principles.md
quality_gates_for_skills.md
scripts/
_skill_frontmatter.py
skill_description_validator.py
skill_review_checklist_runner.py
skill_structure_validator.py

詳細

スキルの作成

Matt Pocock の write-a-skill（MIT）をベースにしています。Matt の語り口と3フェーズのワークフローはそのまま維持しています。追加内容：検証ツール + リファレンス + cs-* ラッパー（下記の ツールと付属機能 を参照）。

プロセス

  1. 要件を収集する - ユーザーに次のことを尋ねます：

    • スキルで扱うタスク／分野は何ですか？
    • 対応すべき具体的なユースケースは何ですか？
    • 実行可能なスクリプトが必要ですか、それとも手順だけでよいですか？
    • 含める参考資料はありますか？

  2. スキルの草案を作成する - 次を作成します：

    • 簡潔な手順を記載した SKILL.md
    • 内容が500行を超える場合は、追加のリファレンスファイル
    • 決定論的な処理が必要な場合は、ユーティリティスクリプト

  3. ユーザーとレビューする - 草案を提示して、次のことを尋ねます：

    • ユースケースを網羅していますか？
    • 不足している点や不明瞭な点はありますか？
    • 詳細を増やす、または減らすべきセクションはありますか？

スキルの構成

skill-name/
├── SKILL.md           # Main instructions (required)
├── REFERENCE.md       # Detailed docs (if needed)
├── EXAMPLES.md        # Usage examples (if needed)
└── scripts/           # Utility scripts (if needed)
    └── helper.js

SKILL.md のテンプレート

---
name: skill-name
description: Brief description of capability. Use when [specific triggers].
---

# Skill Name

## Quick start

[Minimal working example]

## Workflows

[Step-by-step processes with checklists for complex tasks]

## Advanced features

[Link to separate files: See [REFERENCE.md](REFERENCE.md)]

説明の要件

説明は、どのスキルを読み込むかを判断するときにエージェントが目にする唯一の情報です。インストール済みのほかのすべてのスキルとともにシステムプロンプトに表示されます。エージェントはこれらの説明を読み、ユーザーのリクエストに基づいて関連するスキルを選びます。

目標：エージェントが次のことを把握できるだけの情報を記載します：

  1. このスキルが提供する機能
  2. どのような場合に、またなぜ起動するのか（具体的なキーワード、コンテキスト、ファイル形式）

形式：

  • 最大1024文字
  • 三人称で記述する
  • 最初の文：このスキルが行うこと
  • 2番目の文：「次の場合に使用する：[具体的な起動条件]」

良い例：

Extract text and tables from PDF files, fill forms, merge documents. Use when working with PDF files or when user mentions PDFs, forms, or document extraction.

悪い例：

Helps with documents.

悪い例では、ほかのドキュメント作成スキルと区別する方法をエージェントに示せません。

スクリプトを追加するタイミング

次の場合にユーティリティスクリプトを追加します：

  • 処理が決定論的である（検証、フォーマットなど）
  • 同じコードを繰り返し生成する
  • エラーを明示的に処理する必要がある

スクリプトを使うとトークンを節約でき、コードを生成する場合と比べて信頼性も向上します。

ファイルを分割するタイミング

次の場合はファイルを分割します：

  • SKILL.md が100行を超える
  • 内容が異なる分野（金融と営業のスキーマなど）に分かれている
  • 高度な機能がまれにしか必要ない

レビューチェックリスト

草案の作成後、次の点を確認します：

  • 説明に起動条件（「次の場合に使用する：...」）が含まれている
  • SKILL.md が100行未満である
  • 時間の経過で古くなる情報がない
  • 用語が統一されている
  • 具体例が含まれている
  • リファレンスの階層が1段である

ツールと付属機能

検証ツールと cs-* ラッパーは、このスキルと併用します。6項目すべてのレビューチェックをプログラムで実行します：

python scripts/skill_review_checklist_runner.py path/to/skill-folder

ツールカタログ、cs-skill-author ペルソナエージェント、/cs-write-a-skill スラッシュコマンドについては、references/companion_tooling.md を参照してください。

知識が自分の頭ではなく文書にある場合

このスキルは、すでに持っている専門知識をもとに作成します。元資料が書籍、ドキュメントフォルダー、標準規格、または大量の仕様書の場合は、代わりに engineering/book-to-skill を使用してください。文書をナレッジベーススキル（中核となるフレームワーク + 必要に応じて参照する章 + 用語集 + パターン + チートシート）にまとめ、成果物をプラグインとしてパッケージ化することもできます。

/cs-book-to-skill <path|folder|glob> [skill-name]     # compile the source
/cs-book-to-plugin <compiled-skill-dir>               # wrap it as a plugin

経験則：まず作成し、次にまとめる。 手書きのスキルはエージェントに何をさせたいかを示し、書籍からまとめたスキルは作業中に参照する資料です。両方がある場合、それらは1つではなく2つのスキルです。

バージョン： 1.0.0 ベース： Matt Pocock（MIT）+ このリポジトリのラッパー

コメント

Markdown 対応