writing-skills

スキルの作成

概要

スキルの作成は、プロセス文書に適用するテスト駆動開発です。

個人用スキルは、エージェント固有のディレクトリに保存されます（Claude Code の場合は ~/.claude/skills、Codex の場合は ~/.codex/skills）。

サブエージェントを使ってテストケース（プレッシャーシナリオ）を書き、失敗する様子（ベースラインの振る舞い）を確認してから、スキル（ドキュメント）を書きます。次に、テストに合格する様子（エージェントが指示に従うこと）を確認し、リファクタリング（抜け穴を塞ぐこと）を行います。

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

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

公式ガイダンス： Anthropic の公式なスキル作成のベストプラクティスについては、anthropic-best-practices.md を参照してください。このドキュメントでは、このスキルの TDD 中心のアプローチを補完する、追加のパターンとガイドラインを紹介します。

スキルとは？

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

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

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

スキル作成への TDD の対応付け

TDD の概念	スキルの作成
テストケース	サブエージェントを使ったプレッシャーシナリオ
本番コード	スキルドキュメント（SKILL.md）
テスト失敗（RED）	スキルなしでエージェントがルールに違反する（ベースライン）
テスト合格（GREEN）	スキルがある状態でエージェントが指示に従う
リファクタリング	指示への準拠を保ちながら抜け穴を塞ぐ
先にテストを書く	スキルを書く前にベースラインシナリオを実行する
失敗を確認する	エージェントが使う具体的な正当化の言葉を記録する
最小限のコード	具体的な違反に対処するスキルを書く
合格を確認する	エージェントが指示に従うようになったことを検証する
リファクタリングサイクル	新たな正当化を見つける -> 塞ぐ -> 再検証する

スキル作成の全工程は、RED-GREEN-REFACTOR に従います。

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

次の場合に作成します：

• 手法が直感的にはわかりにくかった
• プロジェクトをまたいで、再び参照することになりそう
• パターンが幅広く当てはまる（特定のプロジェクトに限らない）
• 他の人にも役立つ

次の場合は作成しません：

• 一度限りの解決策
• 他の場所で十分に文書化されている標準的な手法
• プロジェクト固有の規約（CLAUDE.md に記載してください）
• 機械的な制約（正規表現やバリデーションで適用できる場合は、自動化して、ドキュメントは判断が必要な場合に使ってください）

スキルの種類

手法

従うべき手順を示す具体的な方法（condition-based-waiting、root-cause-tracing）

パターン

問題の考え方を示す方法（flatten-with-flags、test-invariants）

リファレンス

API ドキュメント、構文ガイド、ツールのドキュメント（office docs）

ディレクトリ構成

skills/
  skill-name/
    SKILL.md              # Main reference (required)
    supporting-file.*     # Only if needed

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

別ファイルにするもの：

1. 大規模なリファレンス（100 行以上） - API ドキュメント、包括的な構文資料
2. 再利用可能なツール - スクリプト、ユーティリティ、テンプレート

本文に含めるもの：

• 原則と概念
• コードパターン（50 行未満）
• その他すべて

SKILL.md の構成

フロントマター（YAML）：

• サポートされるフィールドは name と description の 2 つのみ
• 合計 1024 文字まで
• name：英字、数字、ハイフンのみを使用します（括弧や特殊文字は使用しません）
• description：三人称で、使用するタイミングのみを説明します（何をするものかは説明しません）
  • 使用条件に焦点を当てるため、「Use when...」で始めます
  • 具体的な症状、状況、文脈を含めます
  • スキルの手順やワークフローを要約してはいけません（理由については CSO の項を参照）
  • 可能であれば 500 文字未満にします

---
name: Skill-Name-With-Hyphens
description: Use when [specific triggering conditions and symptoms]
---

# 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）

発見されるために重要です： 将来の Claude があなたのスキルを見つけられるようにします

1. 詳細な説明フィールド

目的： Claude は説明を読んで、特定のタスクでどのスキルを読み込むかを判断します。「今、このスキルを読むべきか？」に答えられるようにします。

形式： トリガー条件に焦点を当てるため、「Use when...」で始めます。

重要：説明は「いつ使うか」を示すものであり、「スキルで何をするか」ではありません

説明では、トリガー条件のみを記述してください。スキルのプロセスやワークフローを説明に要約しないでください。

これが重要な理由： テストの結果、説明にスキルのワークフローを要約すると、Claude はスキルの全内容を読まず、説明に従ってしまう可能性があることがわかりました。「タスク間のコードレビュー」と書かれた説明のせいで、スキルのフローチャートには（仕様への準拠確認とコード品質確認の）2回のレビューが明確に示されていたにもかかわらず、Claude はレビューを1回だけ行いました。

説明をワークフローの要約を含まない「独立したタスクを含む実装計画を実行するときに使用」に変更すると、Claude はフローチャートを正しく読み、2段階のレビュープロセスに従いました。

落とし穴： ワークフローを要約する説明は、Claude が利用する近道を作り出します。その結果、Claude はスキル本文を読み飛ばし、ドキュメントとして扱ってしまいます。

# X BAD: Summarizes workflow - Claude may follow this instead of reading skill
description: Use when executing plans - dispatches subagent per task with code review between tasks

# X BAD: Too much process detail
description: Use for TDD - write test first, watch it fail, write minimal code, refactor

# V GOOD: Just triggering conditions, no workflow summary
description: Use when executing implementation plans with independent tasks in the current session

# V GOOD: Triggering conditions only
description: Use when implementing any feature or bugfix, before writing implementation code

内容：

• このスキルが適用されることを示す、具体的なトリガー、症状、状況を使用します
• 問題（競合状態、一貫性のない動作）を説明し、言語固有の症状（setTimeout、sleep）は説明しません
• スキル自体が技術固有でない限り、技術に依存しないトリガーにします
• スキルが特定の技術に固有の場合は、トリガーでそのことを明示します
• 三人称で記述します（システムプロンプトに挿入されます）
• スキルのプロセスやワークフローを絶対に要約しないでください

# X BAD: Too abstract, vague, doesn't include when to use
description: For async testing

# X BAD: First person
description: I can help you with async tests when they're flaky

# X BAD: Mentions technology but skill isn't specific to it
description: Use when tests use setTimeout/sleep and are flaky

# V GOOD: Starts with "Use when", describes problem, no workflow
description: Use when tests have race conditions, timing dependencies, or pass/fail inconsistently

# V GOOD: Technology-specific skill with explicit trigger
description: Use when using React Router and handling authentication redirects

2. キーワードの網羅

Claude が検索しそうな語句を使います。

• エラーメッセージ：「Hook timed out」、「ENOTEMPTY」、「race condition」
• 症状：「flaky」、「hanging」、「zombie」、「pollution」
• 同義語：「timeout/hang/freeze」、「cleanup/teardown/afterEach」
• ツール：実際のコマンド、ライブラリ名、ファイル形式

3. 説明的な命名

能動態を使い、動詞から始めます：

• V creating-skills を使い、skill-creation は使わない
• V condition-based-waiting を使い、async-test-helpers は使わない

4. トークン効率（重要）

問題： getting-started と頻繁に参照されるスキルは、すべての会話で読み込まれます。すべてのトークンが重要です。

目標の語数：

• getting-started のワークフロー：それぞれ150語未満
• 頻繁に読み込まれるスキル：合計200語未満
• その他のスキル：500語未満（簡潔さを保ちます）

テクニック：

詳細はツールのヘルプに移します：

# X BAD: Document all flags in SKILL.md
search-conversations supports --text, --both, --after DATE, --before DATE, --limit N

# V GOOD: Reference --help
search-conversations supports multiple modes and filters. Run --help for details.

相互参照を使います：

# X BAD: Repeat workflow details

When searching, dispatch subagent with template...
[20 lines of repeated instructions]

# V GOOD: Reference other skill

Always use subagents (50-100x context savings). REQUIRED: Use [other-skill-name] for workflow.

例を簡潔にします：

# X BAD: Verbose example (42 words)

your human partner: "How did we handle authentication errors in React Router before?"
You: I'll search past conversations for React Router authentication patterns.
[Dispatch subagent with search query: "React Router authentication error handling 401"]

# V GOOD: Minimal example (20 words)

Partner: "How did we handle auth errors in React Router?"
You: Searching...
[Dispatch subagent -> synthesis]

重複をなくします：

• 相互参照先のスキルにある内容を繰り返さないでください
• コマンドを見れば明らかなことを説明しないでください
• 同じパターンの例を複数含めないでください

検証：

wc -w skills/path/SKILL.md
# getting-started workflows: aim for <150 each
# Other frequently-loaded: aim for <200 total

実行すること、または核心となる知見に基づいて命名します：

• V condition-based-waiting > async-test-helpers
• V using-skills を使い、skill-usage は使わない
• V flatten-with-flags > data-structure-refactoring
• V root-cause-tracing > debugging-techniques

プロセスには動名詞（-ing形）が適しています：

• creating-skills、testing-skills、debugging-with-logs
• 能動的で、自分が行うアクションを表します

4. 他のスキルへの相互参照

他のスキルを参照するドキュメントを作成する場合：

スキル名だけを使い、必須であることを明示するマーカーを付けます。

• V 良い例：**REQUIRED SUB-SKILL:** Use tdd
• V 良い例：**REQUIRED BACKGROUND:** You MUST understand debugging
• X 悪い例：See skills/testing/test-driven-development（必須かどうか不明確です）
• X 悪い例：@skills/testing/test-driven-development/SKILL.md（強制的に読み込まれ、コンテキストを消費します）

@リンクを使わない理由： @ 構文はファイルをただちに強制読み込みするため、必要になる前に20万以上のコンテキストを消費します。

フローチャートの使い方

digraph when_flowchart {
    "Need to show information?" [shape=diamond];
    "Decision where I might go wrong?" [shape=diamond];
    "Use markdown" [shape=box];
    "Small inline flowchart" [shape=box];

    "Need to show information?" -> "Decision where I might go wrong?" [label="yes"];
    "Decision where I might go wrong?" -> "Small inline flowchart" [label="yes"];
    "Decision where I might go wrong?" -> "Use markdown" [label="no"];
}

フローチャートは次の場合にのみ使用してください。

• 自明でない判断ポイント
• 早く止めすぎる可能性があるプロセスのループ
• 「A と B のどちらを使うか」の判断

次の場合はフローチャートを使用しないでください。

• 参照資料 → 表、リスト
• コード例 → Markdown ブロック
• 直線的な手順 → 番号付きリスト
• 意味を持たないラベル（step1、helper2）

Graphviz のスタイルルールについては、@graphviz-conventions.dot を参照してください。

人間のパートナー向けの可視化： このディレクトリにある render-graphs.js を使って、スキルのフローチャートを SVG にレンダリングできます。

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

コード例

平凡な例をたくさん示すより、優れた例をひとつ示すほうが効果的です。

最も関連性の高い言語を選んでください。

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

良い例：

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

避けること：

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

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

ファイル構成

自己完結型のスキル

defense-in-depth/
  SKILL.md    # Everything inline

次の場合：すべてのコンテンツが収まり、大量の参照資料を必要としない

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

condition-based-waiting/
  SKILL.md    # Overview + patterns
  example.ts  # Working helpers to adapt

次の場合：ツールが単なる説明文ではなく、再利用可能なコードである

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

pptx/
  SKILL.md       # Overview + workflows
  pptxgenjs.md   # 600 lines API reference
  ooxml.md       # 500 lines XML structure
  scripts/       # Executable tools

次の場合：参照資料が大きすぎて、本文に含められない

鉄則（TDD と同じ）

NO SKILL WITHOUT A FAILING TEST FIRST

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

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

例外はありません。

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

必須の背景知識： なぜこれが重要なのかは、tdd スキルで説明されています。同じ原則はドキュメントにも当てはまります。

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

スキルの種類によって、適切なテスト方法は異なります。

規律を徹底させるスキル（ルール／要件）

例： TDD、完了前の検証、コーディング前の設計

次の方法でテストします。

• 学術的な質問：ルールを理解していますか？
• プレッシャーのかかるシナリオ：ストレス下でもルールに従いますか？
• 複数のプレッシャーを組み合わせた状況：時間＋埋没コスト＋疲労
• 合理化を特定し、それを明確に否定する説明を追加する

成功基準： 最大のプレッシャーの下でも、エージェントがルールに従う

手法のスキル（手順ガイド）

例： 条件に基づく待機、根本原因の追跡、防御的プログラミング

次の方法でテストします。

• 適用シナリオ：手法を正しく適用できますか？
• バリエーションシナリオ：エッジケースに対応できますか？
• 情報不足のテスト：指示に抜けがありませんか？

成功基準： エージェントが新しいシナリオに手法を適用し、適切に対処できる

パターンのスキル（メンタルモデル）

例： 複雑さの軽減、情報隠蔽の概念

次の方法でテストします。

• 認識シナリオ：パターンが当てはまる場面を認識できますか？
• 適用シナリオ：メンタルモデルを使えますか？
• 反例：適用すべきでない場面を理解していますか？

成功基準： エージェントがパターンを適用するタイミングと方法を正しく判断する

参照スキル（ドキュメント／API）

例： API ドキュメント、コマンドリファレンス、ライブラリガイド

次の方法でテストします。

• 情報検索シナリオ：適切な情報を見つけられますか？
• 適用シナリオ：見つけた情報を正しく使えますか？
• 網羅性テスト：一般的なユースケースが網羅されていますか？

成功基準： エージェントが参照情報を見つけ、正しく適用する

テストを省略するよくある言い訳

言い訳	実際のところ
「スキルの内容は明らかです」	あなたにとって明らかでも、ほかのエージェントにとって明らかとは限りません。テストしてください。
「これは単なるリファレンスです」	リファレンスにも抜けや不明瞭な箇所があることがあります。検索をテストしてください。
「テストはやりすぎです」	テストしていないスキルには、必ず問題があります。15分のテストで何時間も節約できます。
「問題が起きたらテストします」	問題が起きると、エージェントはスキルを使えません。デプロイする前にテストしてください。
「テストは面倒すぎます」	本番環境で質の低いスキルをデバッグするより、テストのほうが面倒ではありません。
「良いものだと確信しています」	過信すれば、必ず問題が起きます。それでもテストしてください。
「学術的なレビューで十分です」	読むことと使うことは違います。適用シナリオをテストしてください。
「テストする時間がありません」	テストせずにデプロイすると、後で修正するために、さらに多くの時間を無駄にします。

これらはすべて、デプロイ前にテストするという意味です。例外はありません。

合理化に対抗できるスキルを作る

TDDのように規律を徹底させるスキルは、合理化に抵抗できる必要があります。エージェントは賢いため、プレッシャーがかかると抜け道を見つけます。

心理学に関する注記： 説得の手法が効果を発揮する理由を理解すると、それらを体系的に適用できます。権威、一貫性、希少性、社会的証明、一体性の原則に関する研究の基盤については、persuasion-principles.md（Cialdini, 2021; Meincke et al., 2025）を参照してください。

すべての抜け道を明示的にふさぐ

ルールを述べるだけでなく、具体的な回避策を禁止します。

```markdown Write code before test? Delete it. ``` ```markdown Write code before test? Delete it. Start over.

No exceptions:

• Don't keep it as "reference"
• Don't "adapt" it while writing tests
• Don't look at it
• Delete means delete

</Good>

### 「精神か文言か」という議論に対処する

基礎となる原則を早い段階で追加します。

```markdown
**Violating the letter of the rules is violating the spirit of the rules.**

これにより、「精神には従っています」という合理化をまとめて封じられます。

合理化の一覧表を作る

ベースラインテストで見つかった合理化を記録します（下記の「テスト」セクションを参照）。エージェントが口にする言い訳はすべて一覧表に追加します。

| Excuse                           | Reality                                                                 |
| -------------------------------- | ----------------------------------------------------------------------- |
| "Too simple to test"             | Simple code breaks. Test takes 30 seconds.                              |
| "I'll test after"                | Tests passing immediately prove nothing.                                |
| "Tests after achieve same goals" | Tests-after = "what does this do?" Tests-first = "what should this do?" |

危険信号の一覧を作る

合理化しているときに、エージェントが自分で確認しやすいようにします。

## Red Flags - STOP and Start Over

- Code before test
- "I already manually tested it"
- "Tests after achieve the same purpose"
- "It's about spirit not ritual"
- "This is different because..."

**All of these mean: Delete code. Start over with TDD.**

違反の兆候に合わせてCSOを更新する

説明に、ルールに違反しようとしているときの兆候を追加します。

description: use when implementing any feature or bugfix, before writing implementation code

スキルのRED-GREEN-REFACTOR

TDDサイクルに従います。

RED：失敗するテストを書く（ベースライン）

スキルを使わずに、サブエージェントでプレッシャーシナリオを実行します。実際の振る舞いを正確に記録します。

• どのような選択をしましたか？
• どのような合理化を使いましたか（そのまま記録）？
• どのプレッシャーが違反を引き起こしましたか？

これは「テストが失敗するのを見る」段階です。スキルを書く前に、エージェントが自然にどう振る舞うかを確認する必要があります。

GREEN：最小限のスキルを書く

それらの具体的な合理化に対処するスキルを書きます。仮定上のケースに備えて余計な内容を追加しないでください。

同じシナリオを、今度はスキルを使って実行します。エージェントはルールに従うはずです。

REFACTOR：抜け道をふさぐ

エージェントが新たな合理化を見つけましたか？ 明示的な対抗策を追加します。完全に防げるまで再テストします。

テスト方法： テスト方法の全容については、@testing-skills-with-subagents.mdを参照してください。

• プレッシャーシナリオの書き方
• プレッシャーの種類（時間、埋没コスト、権威、疲労）
• 抜け穴を体系的にふさぐ方法
• メタテストの手法

アンチパターン

X 物語形式の例

「2025-10-03のセッションでは、空のprojectDirが原因で……という問題が見つかりました」 よくない理由： 具体的すぎて、再利用できません。

X 多言語化による質の低下

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

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

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

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

X 汎用的なラベル

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

次のスキルに進む前に必ず停止してください

スキルを作成したら、必ず停止してデプロイプロセスを完了してください。

次のことは禁止です：

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

以下のデプロイチェックリストは、各スキルで必ず実施してください。

テストしていないスキルのデプロイは、テストしていないコードのデプロイと同じです。品質基準への違反です。

スキル作成チェックリスト（TDD に適合）

重要：以下のチェックリスト項目ごとに、TaskCreate を使ってタスクを作成してください。

RED フェーズ - 失敗するテストを書く：

• プレッシャーシナリオを作成する（規律を扱うスキルでは、3 つ以上のプレッシャーを組み合わせる）
• スキルを使わずにシナリオを実行し、ベースラインの動作を一字一句そのまま記録する
• 言い訳や失敗に見られるパターンを特定する

GREEN フェーズ - 最小限のスキルを書く：

• 名前には英字、数字、ハイフンのみを使う（括弧や特殊文字は使わない）
• YAML フロントマターには name と description のみを記述する（最大 1024 文字）
• description は「Use when...」で始め、具体的なトリガーや症状を含める
• description は三人称で書く
• 検索しやすいキーワードを全体に含める（エラー、症状、ツールなど）
• 中核となる原則を含む、明確な概要を記述する
• RED で特定したベースラインの失敗に具体的に対処する
• コードをインラインで記述するか、別ファイルへのリンクを含める
• 優れた例を 1 つ用意する（複数の言語は使わない）
• スキルを使ってシナリオを実行し、エージェントが適切に従うようになったことを確認する

REFACTOR フェーズ - 抜け穴をふさぐ：

• テストで新たに見つかった言い訳を特定する
• 明示的な対策を追加する（規律を扱うスキルの場合）
• すべてのテスト反復から、言い訳の一覧表を作成する
• 危険信号のリストを作成する
• 完全に堅牢になるまで再テストする

品質チェック：

• 判断が明白でない場合に限り、簡潔なフローチャートを含める
• クイックリファレンス表を含める
• よくある間違いのセクションを含める
• 物語形式の記述は使わない
• 補助ファイルはツールや大量のリファレンスにのみ使う

デプロイ：

• スキルを git にコミットし、設定されている場合は自分のフォークにプッシュする
• 広く役立つ場合は、PR での貢献を検討する

発見のワークフロー

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

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

この流れに合わせて最適化してください。検索可能な用語を早い段階から、頻繁に配置します。

要点

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

同じ鉄則：まず失敗するテストを書く。テストなしにスキルを作成しない。 同じサイクル：RED（ベースライン）-> GREEN（スキルを書く）-> REFACTOR（抜け穴をふさぐ）。 同じ効果：品質の向上、予期せぬ事態の減少、堅牢な成果。

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

文体のガイドライン

スキルの内容を書く際は、明確で直接的な表現にするため、以下の文章作成ガイドラインに従ってください。

語り口とトーン

• 人が話すように書きます。企業的な専門用語や宣伝文句は避けます。
• 自信を持って率直に書きます。「I think」「maybe」「could」のような、表現を弱める言い回しは避けます。
• 受動態ではなく能動態を使います。
• 肯定的な表現を使います。何かが「何ではないか」ではなく、「何であるか」を伝えます。
• 外部の読者に向ける場合は、「we」より「you」を多く使います。
• 親しみやすいトーンにするため、「I'll」「won't」「can't」のような短縮形を使います。

具体性と根拠

• 曖昧な最上級表現ではなく、具体的な事実やデータを示します。
• 主張は具体例や指標で裏付けます。
• 企業の実績よりも、顧客やコミュニティのメンバーを取り上げます。
• コードでは foo/bar/baz ではなく、現実的な製品ベースの例を使います。
• 具体的で、視覚的に分かりやすく、反証可能な内容にします。

タイトルの作成

• 読者がクリックしたときに何を得られるのか、正確に伝える約束をタイトルに盛り込みます。
• 読者が関心を持つ論争点を取り上げ、データで裏付けます（賢く活用し、釣りタイトルは避けてください）。
• 読者の生活の大切な側面をより良くする、独自に役立つ情報を共有します。
• 「XYZについての私の考え」のような曖昧なタイトルは避けます。タイトルには意見や共有する価値のある事実を盛り込みます。
• まず仮のタイトルを書き、本文を完成させてから、最後に時間をかけてタイトルを練り直します。

使用禁止の単語（置き換え表）

• a bit → 削除
• a little → 削除
• actually/actual → 削除
• agile → 削除
• arguably → 削除
• assistance → 「help」
• attempt → 「try」
• battle tested → 削除
• best practices → 「proven approaches」
• blazing fast/lightning fast → 「build XX% faster」
• business logic → 削除
• cognitive load → 削除
• commence → 「start」
• delve → 「go into」
• disrupt/disruptive → 削除
• facilitate → 「help」または「ease」
• game-changing → 具体的な利点
• great → 削除するか、具体的に表現
• implement → 「do」
• individual → 「man」または「woman」
• initial → 「first」
• innovative → 削除
• just → 削除
• leverage → 「use」
• mission-critical → 「important」
• modern/modernized → 削除
• numerous → 「many」
• out of the box → 削除
• performant → 「fast and reliable」
• pretty/quite/rather/really/very → 削除
• referred to as → 「called」
• remainder → 「rest」
• robust → 「strong」
• seamless/seamlessly → 「automatic」
• sufficient → 「enough」
• that → 文脈に応じて削除
• thing → 具体的な表現
• utilize → 「use」
• webinar → 「online event」

使用禁止のフレーズ

• I think/I believe/we believe → 直接的に述べる
• it seems → 削除
• sort of/kind of → 削除
• pretty much → 削除
• a lot/a little → 具体的に表現
• By developers, for developers → 削除
• We can't wait to see what you'll build → 削除
• We obsess over ___ → 削除
• The future of ___ → 削除
• We're excited → 「We look forward」
• Today, we're excited to → 削除

LLM によくある表現を避ける

• emダッシュ（—）はセミコロン、カンマ、または文の区切りに置き換えます。
• 「素晴らしい質問です！」「おっしゃるとおりです！」「お手伝いします。」で回答を始めないでください。
• 「詳しく見ていきましょう」のような表現は使わないでください。
• 「今日のペースの速いデジタル世界では」や「絶えず進化する状況において」のような決まり文句の導入は避けてください。
• 「単に[x]というだけではなく、[y]でもある」のような表現は避けてください。
• 「AIとして」や「お手伝いするためにここにいます」のような自己言及の免責表現は避けてください。
• 「結論として」「全体として」「要約すると」のような学校作文風の締めくくりは避けてください。
• 箇条書きが適している場合は、番号付きリストを避けてください。
• 「お役に立てば幸いです！」のような締めくくりは避けてください。
• 「さらに」「加えて」「そのうえ」などのつなぎ言葉を多用しないでください。
• 「結論として」は、内容を直接述べる表現に置き換えてください。
• 「かもしれない」「おそらく」「潜在的に」などの曖昧な言葉は、実際に不確実な場合を除いて避けてください。
• 「可能性があるかもしれない」「注意が必要であることに留意してください」のように、曖昧な表現を重ねないでください。
• 「第一に……第二に……」で始まるような、対称的すぎる段落やリストは作らないでください。
• 見出しではタイトルケースを避け、文頭のみ大文字にする形式を推奨します。
• コピー時に混入したUnicode文字の問題を取り除いてください。スマート引用符（"）、emダッシュ、改行なしスペースなどが該当します。
• `` ではなく '' を使用してください。
• 実際の出典がない空の引用プレースホルダー（「[1]」など）は削除してください。

句読点と書式

• Oxford commaを一貫して使用してください。
• 感嘆符は控えめに使ってください。
• 「しかし」や「そして」で文を始めてもかまいません。ただし多用は避けてください。
• 明瞭さを優先し、可能な場合はカンマではなくピリオドを使ってください。

鉄則

1. 必ず TDD を適用します。スキルを書く前に、まず RED のベースライン（スキルを使わない場合の現在の動作）を記録します。
2. 絶対に スキルの説明に実装の詳細や「方法」の指示を含めません。説明にはトリガー条件のみを記載します。
3. 必ず REFACTOR フェーズで新たな合理化による抜け穴を塞えてから、スキルを完成とします。
4. 絶対に バリデーター（最低基準は 8/0/3）に合格することを確認せずにスキルを公開しません。
5. 必ず スキルの内容には平易で能動的な表現を使います。受動態や曖昧な表現は排除します。

アンチパターン

アンチパターン	失敗する理由	正しい方法
RED のベースラインを省略する	ベースラインがなければ改善を測定できません	まずスキルなしでテストを実行し、失敗を記録します
説明に実装の詳細を含める	誤った条件で起動し、ルーティングが混乱します	説明はトリガー条件のみに限定します
スキルの内容に曖昧で歯切れの悪い表現を使う	曖昧なルールではエージェントの動作を変えられません	具体的な基準を示し、必ず／絶対にという命令形を使います
抜け穴を塞ぐ REFACTOR フェーズを設けない	エージェントがエッジケースを見つけ、都合よく解釈します	失敗のパターンを確認したら、スキルを繰り返し改善します
バリデーターで確認せずに公開する	統合上の問題を検出できません	validate-integration.cjs を実行し、8/0/3 を目標にします

メモリープロトコル（必須）

開始前： .claude/context/memory/learnings.md を読みます。

完了後：

• 新しいパターン -> .claude/context/memory/learnings.md
• 見つかった問題 -> .claude/context/memory/issues.md
• 決定事項 -> .claude/context/memory/decisions.md

中断を想定してください。メモリに記録されていなければ、実行されなかったものとみなします。