mcpField
W
write-a-skill

write-a-skill

github.com/akillnessエージェントワークフロー5363 回インストール1 日前に更新
リポジトリ

write-a-skill について

write-a-skillは、文書化された再利用可能なエージェントスキルを作成するためのガイドです。要件整理から構造化されたSKILL.mdの作成、起動条件や適用範囲、補助ファイルのレビューまでを扱います。

主な機能

  1. 01要件の整理
  2. 02構造化されたSKILL.mdの作成
  3. 03補助ファイルの計画
  4. 04起動条件と適用範囲のレビュー
  5. 05スキル品質チェックリスト

活用シーン

  1. 01ワークフローを再利用可能なスキルにする
  2. 02新しいエージェント機能を作る
  3. 03スキルを発見しやすくするためパターンを文書化

インストール

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

$npx skills add https://github.com/akillness/jeo-skills --skill write-a-skill

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

詳細

スキルの作成

適切なドキュメントを備えた、構造化されたエージェントスキルを作成します。

上流の状況

上流では writing-for-agents に置き換えられています。find-skills、upskill、solo-skills、openocta からここに誘導されるため、残されています。

このスキルを使用する場面

  • ワークフローを再利用・共有可能なスキルとして形式化するとき
  • エージェントの新しい機能を一から構築するとき
  • 既存のパターンをドキュメント化し、エージェントが見つけて使用できるようにするとき

重要な設計原則

エージェントがスキルを読み込むかどうかを判断する際に見るのは、description フィールドだけです。

次の点を満たす説明を記述します。

  • スキルの機能を明確に述べている
  • 「Use when [context]」のような具体的なトリガーを含んでいる
  • 1024 文字以内である
  • エージェントが有効化するかどうか判断できるだけの精度がある

プロセス

フェーズ 1 — 要件の収集

次の点を把握します。

  • このスキルで形式化するタスクまたはワークフローは何ですか？
  • トリガー条件（エージェントはどのようなときにこれを有効化すべきですか？）は何ですか？
  • 境界（このスキルが行わないこと）は何ですか？
  • どのプラットフォームで動作させる必要がありますか？
  • 既存のスキルと重複しますか？
フェーズ 2 — スキルの草案作成

中核となるファイルとして SKILL.md を作成します。100 行未満にします。

次の場合は、追加ファイルに分割します。

  • SKILL.md が約 100 行を超える
  • 常に必要とされるわけではない、個別の領域を扱う
  • 例が中核となる指示を煩雑にする

サポート用ファイルとして、次の形式に対応しています。

  • REFERENCE.md — 詳細なリファレンス情報
  • EXAMPLES.md — 具体例
  • scripts/ — 決定論的なユーティリティスクリプト
フェーズ 3 — ユーザーとのレビュー

草案を提示します。次の点を検証します。

  • 説明は適切なリクエストを正しくトリガーしますか？
  • 指示は明確で、十分に網羅されていますか？
  • 境界によって誤用を防げますか？
  • サポート用ファイルが必要ですか、それとも SKILL.md だけで十分ですか？

SKILL.md テンプレート（jeo-skills 形式）

---
name: skill-name
description: >
  One-paragraph description of what this skill does and when to use it.
  Include trigger conditions: "Use when [specific context]."
allowed-tools: Read Grep Glob Bash Write Edit
compatibility: >
  Platform and context compatibility notes. What it pairs with.
metadata:
  tags: tag1, tag2, tag3, tag4
  platforms: Claude, ChatGPT, Gemini, Codex
  version: "1.0"
  source: your-github/repo
---

# Skill Name

Brief intro paragraph.

## When to use this skill

- Condition 1
- Condition 2

## When not to use this skill

- Route-out 1 → use `other-skill`
- Route-out 2 → use `other-skill`

## Instructions

[Core instructions here]

品質チェックリスト

  • 説明が 1024 文字未満である
  • 説明に「Use when [context]」というトリガー表現が含まれている
  • SKILL.md が 100 行未満である（または分割に正当な理由がある）
  • 使用すべきでない場合に、具体的なスキルへ誘導している
  • metadata.tags に見つけやすいキーワードが含まれている
  • 説明に実装の詳細が含まれていない（それは本文に記載する）

例

  • 例：まずこのスキルを小さな範囲に適用し、検証に合格してから全範囲に拡大します。

ベストプラクティス

  • 出力は決定論的で、監査可能なものにします。
  • 広範でリスクのある編集よりも、小規模で元に戻せる変更を優先します。
  • 前提条件を明示的に記録します。

参考資料

  • プロジェクト標準：.agent-skills/skill-standardization/SKILL.md
  • バリデータースクリプト：.agent-skills/skill-standardization/scripts/validate_skill.sh

コメント

Markdown 対応