writing-skills

Files (12)

• LICENSE
• README.md
• README_ja.md
• SKILL.md
• openai.yaml · agents/
• CLAUDE_MD_TESTING.md · references/
• anthropic-best-practices.md · references/
• graphviz-conventions.dot · references/
• persuasion-principles.md · references/
• test-driven-development.md · references/
• testing-skills-with-subagents.md · references/
• render-graphs.js · scripts/

SKILL.md (first lines)

# Writing Skills

## 概要

**skillの作成は、プロセス文書にテスト駆動開発を適用したものだ。**

**個人用のskillは、実行環境のskillsディレクトリに置く** (Claude Codeでは `~/.claude/skills/`)。Codex、Copilot CLI、Gemini CLIは、実行環境をまたぐ別名として `~/.agents/skills/` も認識する。

テストケース(subagentによるプレッシャーシナリオ)を書き、失敗する様子(baselineの挙動)を観察し、skill(文書)を書き、テストが通る様子(agentが従う)を観察し、refactorする(抜け道を塞ぐ)。

**中心原則:** skillなしでagentが失敗する様子を観察していなければ、そのskillが正しい内容を教えているかどうかは分からない。

**必須の前提知識:** このskillを使う前に、[references/test-driven-development.md](references/test-driven-development.md) を必ず理解すること。この文書は基本となるRED-GREEN-REFACTORサイクルを定義している。このskillはTDDを文書に適用したものだ。

**公式ガイダンス:** Anthropicによるskill作成のベストプラクティスは [references/anthropic-best-practices.md](references/anthropic-best-practices.md) を参照すること。この文書は、このskillのTDD中心のアプローチを補う追加のパターンとガイドラインを示す。

## skillとは

**skill**は、実績のある技法・パターン・ツールのリファレンスガイドだ。将来のagentが有効なアプローチを見つけて適用するのを助ける。

**skillであるもの:** 再利用できる技法、パターン、ツール、リファレンスガイド

**skillでないもの:** 一度問題をどう解決したかの物語

## skillに対するTDDの対応

| TDDの概念              | skillの作成                                   |
| ---------------------- | --------------------------------------------- |
| **テストケース**       | subagentによるプレッシャーシナリオ            |
| **本番コード**         | skill文書 (SKILL.md)                          |
| **テスト失敗 (RED)**   | skillなしでagentがルールに違反する (baseline) |
| **テスト成功 (GREEN)** | skillがある状態でagentが従う                  |
| **Refactor**           | 従う状態を保ったまま抜け道を塞ぐ              |
| **先にテストを書く**   | skillを書く前にbaselineシナリオを実行する     |
| **失敗を観察する**     | agentが使う言い訳を一字一句記録する           |
| **最小限のコード**     | その具体的な違反に対処するskillを書く         |
| **成功を観察する**     | agentが従うようになったことを確認する         |
| **Refactorサイクル**   | 新しい言い訳を見つける → 塞ぐ → 再検証する    |

skill作成の全工程はRED-GREEN-REFACTORに従う。

## skillを作る場面

**作るのは次の場合:**

- その技法が直感的には自明でなかった
- プロジェクトをまたいで再び参照する
- パターンが広く当てはまる(プロジェクト固有ではない)
- 他の人も恩恵を受ける

**作らないのは次の場合:**

- 一度きりの解決策
- 他で十分に文書化されている標準的な慣行
- プロジェクト固有の規約(instructionsファイルに書く)
- 機械的な制約(regexやバリデーションで強制できるなら自動化する。文書は判断が必要な事柄のために取っておく)

## skillの種類

### Technique

従うべき手順を持つ具体的な方法 (condition-based-waiting、root-cause-tracing)

### Pattern

問題の捉え方 (flatten-with-flags、test-invariants)

### Reference

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

## ディレクトリ構成

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

**フラットな名前空間** - すべてのskillを、検索できる1つの名前空間に置く

**別ファイルにするもの:**

1. **大きなリファレンス** (100行以上) - APIドキュメント、網羅的な構文
2. **再利用できるツール** - script、ユーティリティ、template

**インラインに残すもの:**

- 原則と概念
- コードパターン (50行未満)
- それ以外すべて

## SKILL.mdの構造

**Frontmatter (YAML):**

- 必須フィールドは `name` と `description` の2つ (対応するすべてのフィールドは [agentskills.io/specification](https://agentskills.io/specification) を参照)
- 合計で最大1024文字
- `name`: 英字、数字、ハイフンだけを使う(括弧や特殊文字は不可)
- `description`: 何をするskillかを1文目で示し、続けていつ使うかを書く
  - 発動条件として、典型的な依頼フレーズ (「〜して」と依頼したら使うこと) や具体的な症状、状況を含める
  - 誤発動しやすい隣接ケースがあれば「〜の場合は使わない」と書く
  - 「私が」「あなたは」を主語にせず、「お手伝いします」のような語りかけをしない
  - **skillのプロセスやワークフローを決して要約しない** (理由はSDOの節を参照)
  - できれば500文字未満にする

```markdown
---
name: Skill-Name-With-Hyphens
description: [何をするskillかを1文で]。[典型的な依頼フレーズや症状]のときに使うこと。
---

# Skill Name

## 概要

これは何か。中核となる原則を1〜2文で書く。

From mjun0812/skills, MIT.

More from mjun0812/skills