writing-skills

スキルの作成

概要

スキルの作成は、プロセスのドキュメント化に適用したテスト駆動開発です。

個人用スキルは、エージェント固有のディレクトリ（$DOTFILE_REPO_ROOT/ai/files/skills）に配置します。

プロジェクト用スキルは、.agents/skills/に配置します。

サブエージェントを使ってテストケース（プレッシャーシナリオ）を作成し、失敗する様子を確認し（ベースラインの動作）、スキル（ドキュメント）を作成し、テストが通る様子を確認し（エージェントが準拠する）、抜け穴を塞ぐためにリファクタリングします。

基本原則： スキルなしでエージェントが失敗する様子を確認していなければ、そのスキルが適切な内容を教えているかどうかはわかりません。

必須の事前知識： このスキルを使う前に、superpowers:test-driven-developmentを必ず理解してください。このスキルでは、基本となるRED-GREEN-REFACTORサイクルを定義しています。このスキルは、TDDをドキュメントに応用したものです。

公式ガイダンス： writing-skillsスキルからanthropic-best-practicesリソースを読み込んでください。このドキュメントでは、このスキルのTDD中心のアプローチを補完する追加のパターンとガイドラインを紹介しています。

スキルとは？

スキルとは、実証済みの手法、パターン、ツールをまとめたリファレンスガイドです。スキルは、将来のClaudeインスタンスが効果的なアプローチを見つけて適用するのに役立ちます。

スキルに含まれるもの： 再利用可能な手法、パターン、ツール、リファレンスガイド

スキルに含まれないもの： 一度問題を解決した方法についての物語

まず、スキルの種類を分類する

セクションを書き始める前に、早い段階で分類してください。

リファレンス

参照用の資料：API、構文、コマンドのオプション、互換性に関する注意事項。

ワークフロー

順を追って実行するプロセス（多くの場合、ゲートやチェックリストを含みます）。

スタイルガイド

命名、書式、語調、構成に関する標準と規約。

ペルソナ

やり取りのスタイル、優先事項、境界を定める行動プロファイル。

テクニック／パターン

繰り返し発生する問題を解決するための手法やメンタルモデル。

複数の種類にまたがるスキルの場合は、次の手順で判断してください。

1. まず意図を尋ねます： 複数の種類を扱うことが意図的なのか、それとも概念を分割して、焦点を絞った別々のスキルにしたいのかをユーザーに尋ねます。
2. 分割しない場合： 1つのスキルとして続けます。主となる種類を選び、概要で明示してから、RED/GREEN/REFACTORテストを続けます。
3. 分割する場合： 概念を分析し、対象者、ライフサイクルの段階、問題の種類、成果物の種類などを基準に、複数の分割案を提案します。
4. 協力して決定します： ユーザーと相談して希望する分割方法を選びます。その後、別々のセッション用に一時的なプロンプトを作成します。新しいスキルごとに1つずつ作成し、それぞれのプロンプトでこのwriting-skillsスキルを使うよう明示します。

スキルのTDD対応付け

詳しいTDD対応付けの表と概念については、writing-skillsスキルからtdd-mappingリソースを読み込んでください。

基本概念： スキル作成の全プロセスは、TDDのサイクルをドキュメントに応用したRED-GREEN-REFACTORに従います。

スキルを作成するタイミング

作成する場合：

• 手法が直感的にはわかりにくかった
• 複数のプロジェクトで再び参照することになる
• パターンが広く適用できる（特定のプロジェクトに限られない）
• 他の人にも役立つ

作成しない場合：

• 一度きりの解決策
• 他の場所で十分に文書化されている標準的な手法
• プロジェクト固有の規約（CLAUDE.mdに記載してください）

ディレクトリ構成

skills/
  skill-name/
    SKILL.md
    references/
      extra-file.md
    scripts/
      codified-helper.sh
      known-steps-cli.js
    assets/
      possibly-a-circle-mask.png
      maybe-a-logo.png

ルール： スキルのディレクトリにはSKILL.mdだけを含めます。

それ以外のものは、種類ごとに分類した兄弟フォルダーに配置します。

1. 詳細なドキュメント、ガイド、表にはreferences/
2. 実行可能なヘルパーやジェネレーターにはscripts/
3. 図、画像、静的ファイルにはassets/

フラットな名前空間 — すべてのスキルを、検索可能な1つの名前空間にまとめます。

可能な限り、以下はSKILL.mdにインラインで記載します：

• 原則と概念
• 短いコードパターン（50行未満）
• 判断基準とアンチパターン

SKILL.md の構成

フロントマター（YAML）：

• サポートされるフィールドは name と description の2つのみです
• 合計1024文字以内です
• name：英字、数字、ハイフンのみを使用します（括弧や特殊文字は使用しません）。フォルダー名と一致させる必要があります。
• description：三人称で、次の形式で記述します：{何をするか}, {いつ使うか}, {結果は何か}
  • 具体的で検索しやすい内容にします（症状、状況、結果）
  • あいまいな表現や誇張は避けます
  • 可能であれば500文字未満にします

---
name: Skill-Name-With-Hyphens
description: [what it does], [when to use it], [what the result is]
---

# Skill Name

## Overview
What is this? Core principle in 1-2 sentences.

## When to Use
[Small inline flowchart IF decision non-obvious]

Bullet list with SYMPTOMS and use cases
When NOT to use

## Core Pattern (for techniques/patterns)
Before/after code comparison

## Quick Reference
Table or bullets for scanning common operations

## Implementation
Inline code for simple patterns
Link to file for heavy reference or reusable tools

## Common Mistakes
What goes wrong + fixes

## Real-World Impact (optional)
Concrete results

Claude 検索最適化（CSO）

説明文のパターン、キーワードの網羅性、命名規則など、包括的なCSOガイダンスについては、writing-skills スキルから cso-guide リソースを読み込みます。

主な原則：

• 説明文の形式： {何をするか}, {いつ使うか}, {結果は何か}
• システムプロンプトへの注入を想定し、三人称で記述します
• 具体的なきっかけ、症状、結果を使用します
• 検索しやすいキーワードを含めます：エラーメッセージ、症状、ツール

フローチャートの使用

フローチャートを使用するのは、次の場合のみです：

• すぐにはわかりにくい判断が必要な場合
• 早く終わらせすぎる可能性があるプロセスのループ
• 「AとBのどちらを使うか」という判断

次の用途にはフローチャートを使用しないでください：

• 参照資料 → 表、リスト
• コード例 → Markdown ブロック
• 直線的な手順 → 番号付きリスト

graphviz のスタイル規則については、writing-skills スキルから graphviz-conventions リソースを読み込みます。

人間のパートナー向けの可視化： scripts/writing-skills/ の render-graphs.js を使ってフローチャートを SVG にレンダリングします：

./scripts/writing-skills/render-graphs.js ./skills/some-skill           # Each diagram separately
./scripts/writing-skills/render-graphs.js ./skills/some-skill --combine # All diagrams in one SVG

コード例

優れた例1つは、平凡な例をいくつも並べるよりも価値があります

最も関連性の高い言語を選びます：

• テスト手法 → TypeScript/JavaScript
• システムのデバッグ → Shell/Python
• データ処理 → Python

良い例：

• 完全で、そのまま実行できる
• WHY（なぜそうするのか）を説明するコメントが付いている
• 実際のシナリオに基づいている
• パターンが明確に示されている
• 汎用的なテンプレートではなく、応用しやすい

避けること：

• 5つ以上の言語で実装する
• 空欄を埋める形式のテンプレートを作成する
• 不自然な例を書く

移植は得意です。優れた例が1つあれば十分です。

ファイル構成

自己完結型スキル

skills/defense-in-depth/
  SKILL.md

使用する場面：すべての内容をインラインに収められる場合。

再利用可能なツールを含むスキル

skills/condition-based-waiting/
  SKILL.md
scripts/condition-based-waiting/
  example.ts

使用する場面：ツールが再利用可能なコードである場合。

大量の参照資料を含むスキル

skills/pptx/
  SKILL.md
  references/
    pptxgenjs.md
    ooxml.md
  scripts/
    render-slides.js
  assets/
    diagrams/

使用する場面：参照資料が大きすぎてインラインのドキュメントに収まらない場合。

鉄則（TDDと同じ）

NO SKILL WITHOUT A FAILING TEST FIRST

これは新しいスキルにも、既存のスキルの編集にも適用されます。

テスト前にスキルを書く？削除して、最初からやり直してください。 テストせずにスキルを編集する？同じ違反です。

例外はありません：

• 「簡単な追加」であっても例外ではありません
• 「セクションを追加するだけ」であっても例外ではありません
• 「ドキュメントの更新」であっても例外ではありません
• テストしていない変更を「参考」として残さないでください
• テスト実行中に「適宜調整」しないでください
• 削除するとは、削除することです

必須の前提知識： superpowers:test-driven-development スキルでは、これが重要な理由を説明しています。同じ原則がドキュメントにも適用されます。

すべての種類のスキルのテスト

スキルの種類ごとの包括的なテスト手法については、writing-skills スキルから testing-methodology リソースを読み込みます。

クイックリファレンス：

• 規律を徹底させるスキル： プレッシャー（時間、埋没コスト、疲労）のある状況でテストします
• 手法スキル： 適用シナリオとエッジケースをテストします
• パターンスキル： パターンの認識と反例をテストします
• 参照スキル： 情報の取得と正しい適用をテストします

重要な原則： デプロイ前にテストします。例外はありません。

合理化に対抗する堅牢なスキルの作成

規律を徹底させるスキルの抜け道を塞ぎ、合理化に対処する詳細な戦略については、writing-skills スキルから rationalization-patterns リソースを読み込みます。

主な原則：

• 具体的な回避策を禁止し、すべての抜け道を明示的に塞ぎます
• 基本原則を示し、「精神か字面か」という議論に対処します
• ベースラインテストから合理化の一覧表を作成します
• 自己点検用の危険信号リストを作成します
• 違反の症状を説明文に追加します

スキルの RED-GREEN-REFACTOR

TDD サイクルに従ってください。

1. RED：失敗するテストを書く（ベースライン） - スキルを使わずにサブエージェントで圧力シナリオを実行します。実際の動作、正当化の内容、違反を引き起こした圧力を正確に記録します。

2. GREEN：最小限のスキルを書く - それらの具体的な正当化に対処するスキルを書きます。同じシナリオをスキルを使って実行します。エージェントは今度は指示に従うはずです。

3. REFACTOR：抜け穴を塞ぐ - エージェントが新しい正当化を見つけましたか？明示的な対策を追加します。万全になるまで再テストします。

圧力の種類やメタテストの手法を含むテスト方法の全容については、writing-skills スキルから testing-methodology リソースを読み込んでください。

アンチパターン

❌ 物語形式の例

「2025-10-03 のセッションで、空の projectDir が原因で……」 よくない理由： 具体的すぎて、再利用できません

❌ 複数言語への分散

example-js.js、example-py.py、example-go.go よくない理由： 品質が中途半端になり、メンテナンスの負担が増えます

❌ フローチャート内のコード

step1 [label="import fs"];
step2 [label="read file"];

よくない理由： コピー＆ペーストできず、読みにくくなります

❌ 一般的すぎるラベル

helper1、helper2、step3、pattern4 よくない理由： ラベルには意味が伝わる名前を付けるべきです

STOP：次のスキルに進む前に

スキルを書いた後は、どのような場合でも必ず作業を止め、デプロイプロセスを完了してください。

次のことはしないでください。

• 各スキルをテストせずに、複数のスキルをまとめて作成する
• 現在のスキルを検証する前に、次のスキルに進む
• 「まとめて作業したほうが効率的」という理由でテストを省略する

テストしていないスキルのデプロイは、テストしていないコードのデプロイと同じです。

スキル作成チェックリスト（TDD 対応版）

RED-GREEN-REFACTOR の全フェーズと品質チェックを含む完全なチェックリストについては、writing-skills スキルから skill-checklist リソースを読み込んでください。

TodoWrite を使って、チェックリストの各項目の ToDo を作成してください。

概要：

• RED フェーズ： 圧力シナリオを作成し、スキルなしでベースラインを実行する
• GREEN フェーズ： 最小限のスキルを書き、スキルを使ってシナリオを実行する
• REFACTOR フェーズ： 抜け穴を塞ぎ、万全になるまで再テストする
• デプロイ： コミットし、広く役立つスキルについては PR を検討する

発見ワークフロー

将来 Claude がスキルを見つける流れ：

1. 問題に遭遇する（「テストが不安定」）
2. SKILL を見つける（説明が一致する）
3. 概要をざっと読む（関連性があるか？）
4. パターンを読む（クイックリファレンステーブル）
5. 例を読み込む（実装するときだけ）

この流れに合わせて最適化してください - 検索されやすい用語を早い段階から何度も使ってください。

要点

スキルを作成することは、プロセス文書に対する TDD です。

同じ鉄則：失敗するテストが先になければ、スキルを作成しない。 同じサイクル：RED（ベースライン）→ GREEN（スキルを書く）→ REFACTOR（抜け穴を塞ぐ）。 同じメリット：品質の向上、予想外の問題の減少、万全な成果。

コードに TDD を適用するなら、スキルにも適用してください。同じ規律を文書に適用するだけです。