| name | things-url |
| description | Things 3とClaude Codeのタスクを双方向で共有する。URLスキームによるタスク送信とAppleScriptによるタスク読み取りに対応する。macOS環境でThings 3とのタスク同期が必要な場合に使用する。Do NOT use for macOS以外の環境でのタスク管理。 |
| metadata | {"version":"1.0.0"} |
Things URL タスク共有スキル
Claude Codeで管理しているタスクとThings 3を双方向で共有するスキルです。URLスキームによるタスク送信（書き込み）と、AppleScript（osascript）によるタスク読み取りの両方をサポートし、人間とClaude Codeが同じタスク情報を共有できます。
概要
このスキルは以下の機能を提供します：
書き込み（Claude Code → Things 3）
- docs/sdd/tasks/のタスクをThings 3のプロジェクト・To-Doとして送信
- TodoWriteの現在のタスクリストをThings 3に送信
- 個別のTo-Do・プロジェクトを作成するURLを生成
add-jsonコマンドによる一括インポートURL生成- macOSの
openコマンドによるURL直接実行
読み取り（Things 3 → Claude Code）（macOS限定）
- Things 3の今日・受信箱・各リストのタスクを取得
- プロジェクト一覧とプロジェクト内タスクの取得
- タスクの完了状態・タグ・メモの読み取り
- Things 3のタスク状態をTodoWriteやdocs/sdd/tasks/に反映
このスキルを使用する場面
以下の状況でこのスキルを使用してください：
タスク共有時（書き込み）
- Claude Codeで作成したタスクを人間のThings 3に反映したい場合
- SDDのタスク一覧を人間と共有したい場合
- プロジェクトの進捗を人間側でも確認可能にしたい場合
タスク読み取り時（読み取り）
- Things 3で人間が管理しているタスクの状況を確認したい場合
- Things 3で完了マークされたタスクをClaude Code側にも反映したい場合
- Things 3のタスクをTodoWriteやdocs/sdd/tasks/に同期したい場合
- 「Thingsの今日のタスクを教えて」「プロジェクトの進捗を確認して」と依頼された場合
プロジェクト管理時
- SDDのフェーズ全体をThingsプロジェクトとして管理したい場合
- 人間が確認すべきレビュータスクをThingsに送りたい場合
- 人間とClaude Codeのタスク分担を明確にしたい場合
基本的な使い方
1. SDDタスクをThingsに送信
「タスクをThingsに送って」「SDDのタスクをThingsと共有して」などと依頼されたら：
-
docs/sdd/tasks/の読み取り
- タスク一覧（index）を確認
- 各タスクのステータス・詳細を把握
-
送信対象の確認
- ユーザーにどのタスクを送信するか確認
- 全タスク or 特定ステータスのタスクのみ、を選択してもらう
-
Things URL の生成
- タスク構造に応じて
add、add-project、または add-json を使い分ける
- URLをユーザーに提示
-
URLの実行
- macOS環境であれば
openコマンドで直接実行を提案
- それ以外の場合はURLをコピー可能な形式で出力
2. TodoWriteタスクをThingsに送信
「今のタスクリストをThingsに送って」と依頼されたら：
-
現在のTodoWriteの状態を確認
- pending/in_progress/completedの各タスクを把握
-
Things URLを生成
- 各タスクをTo-Doとして
add-jsonで一括作成
- ステータスに応じたタグ付け（例:
in_progress → タグ「進行中」）
-
URLを実行または提示
3. 個別タスクの作成
「Thingsにタスクを追加して」と依頼されたら：
- タスクの内容をヒアリング
things:///add URLを生成- 実行または提示
4. Things 3のタスクを読み取る（macOS限定）
「Thingsのタスクを確認して」「今日のタスクを教えて」「Thingsから同期して」と依頼されたら：
-
macOS環境の確認
unameコマンドでmacOSであることを確認- macOS以外の場合はAppleScriptが使えない旨を伝えて終了
-
読み取り対象の確認
- ユーザーにどのリスト/プロジェクトを読みたいか確認
- 選択肢：今日、受信箱、特定のプロジェクト、全プロジェクト一覧
-
AppleScriptでデータ取得
-
結果の表示
- 取得したタスク一覧を整形して表示
- 必要に応じてTodoWriteやdocs/sdd/tasks/への同期を提案
5. Things 3のタスクをTodoWriteに同期する（macOS限定）
「ThingsのタスクをTodoWriteに反映して」と依頼されたら：
-
Things 3からタスクを読み取る（上記ステップ4と同様）
-
現在のTodoWriteの状態と比較
-
ステータスのマッピング（Things → TodoWrite）
| Things status | Things tag | TodoWrite status |
|---|
open | 進行中 | in_progress |
open | TODO またはタグなし | pending |
open | レビュー | in_progress（[REVIEW]付記） |
open | ブロック | pending（[BLOCKED]付記） |
completed | - | completed |
canceled | - | 除外（同期対象外） |
-
ユーザー確認
-
TodoWriteを更新
6. Things 3のタスクをSDDタスクに同期する（macOS限定）
「ThingsのステータスをSDDに反映して」と依頼されたら：
-
Things 3から該当プロジェクトのタスクを読み取る
-
docs/sdd/tasks/と照合
- タスク名に含まれる
[TASK-XXX]のIDで照合
-
ステータスの差分を検出
| Things status | Things tag | SDD ステータス |
|---|
open | TODO | TODO |
open | 進行中 | IN_PROGRESS |
open | レビュー | REVIEW |
open | ブロック | BLOCKED |
completed | - | DONE |
canceled | - | 除外（同期対象外） |
-
差分をユーザーに提示
-
ユーザー承認後にdocs/sdd/tasks/を更新
URL生成の原則
コマンドの使い分け
| ユースケース | コマンド | 説明 |
|---|
| 単一のTo-Do作成 | things:///add | 1つのタスクを素早く追加 |
| プロジェクト作成 | things:///add-project | 見出し付きプロジェクトを作成 |
| 複数アイテム一括作成 | things:///add-json | 複雑な構造を一度に送信 |
| 既存アイテム表示 | things:///show | Things内のリストを表示 |
| 検索 | things:///search | Things内をキーワード検索 |
パラメータのエンコーディング
すべてのパラメータはURLエンコード（パーセントエンコーディング）が必要です：
タイトル: "APIの実装"
→ エンコード後: API%E3%81%AE%E5%AE%9F%E8%A3%85
重要: URLエンコードにはBashのpython3 -cやjqを使用してください。手動でのエンコードは行いません。
URL生成のコード例
単一To-Doの追加（add）
python3 -c "
import urllib.parse
params = {
'title': 'APIエンドポイントの実装をレビュー',
'notes': 'Claude Codeが実装したPOST /api/auth/loginのレビュー\n\n受入基準:\n- テスト通過\n- ESLintエラーゼロ',
'when': 'today',
'tags': 'Claude Code,レビュー',
'list': 'プロジェクト名'
}
query = urllib.parse.urlencode(params, quote_via=urllib.parse.quote)
url = f'things:///add?{query}'
print(url)
"
プロジェクトの追加（add-project）
python3 -c "
import urllib.parse
params = {
'title': 'SDD Phase 1: 基盤構築',
'notes': 'SDDタスク管理 - Phase 1のタスク一覧',
'when': 'today',
'tags': 'SDD,Claude Code',
'to-dos': '\n'.join([
'TASK-001: データモデルの定義',
'TASK-002: APIエンドポイントの実装',
'TASK-003: 認証ミドルウェアの実装',
])
}
query = urllib.parse.urlencode(params, quote_via=urllib.parse.quote)
url = f'things:///add-project?{query}'
print(url)
"
JSON一括インポート（add-json）
python3 -c "
import urllib.parse, json
data = [
{
'type': 'project',
'attributes': {
'title': 'SDD Phase 1: 基盤構築',
'notes': 'Claude Codeで管理中のSDDタスク',
'when': 'today',
'tags': ['SDD', 'Claude Code'],
'items': [
{
'type': 'heading',
'attributes': {
'title': 'データ層'
}
},
{
'type': 'to-do',
'attributes': {
'title': 'TASK-001: データモデルの定義',
'notes': '推定工数: 1時間\nステータス: TODO',
'tags': ['TODO']
}
},
{
'type': 'to-do',
'attributes': {
'title': 'TASK-002: APIエンドポイントの実装',
'notes': '推定工数: 2時間\nステータス: TODO\n依存: TASK-001',
'tags': ['TODO']
}
},
{
'type': 'heading',
'attributes': {
'title': 'ミドルウェア層'
}
},
{
'type': 'to-do',
'attributes': {
'title': 'TASK-003: 認証ミドルウェアの実装',
'notes': '推定工数: 1.5時間\nステータス: IN_PROGRESS\n依存: TASK-001',
'tags': ['IN_PROGRESS']
}
}
]
}
}
]
json_str = json.dumps(data, ensure_ascii=False)
encoded = urllib.parse.quote(json_str)
url = f'things:///add-json?data={encoded}'
print(url)
"
URLの実行方法
open "things:///add?title=..."
URL=$(python3 -c "...URL生成スクリプト...")
open "$URL"
注意: openコマンドはmacOSでのみ動作します。実行前にOSを確認してください。
SDDタスクのマッピング
ステータスの対応
SDDタスクのステータスをThingsの状態にマッピングします：
| SDD ステータス | Things 状態 | タグ | when |
|---|
| TODO | 未完了 | TODO | （設定なし） |
| IN_PROGRESS | 未完了 | 進行中 | today |
| REVIEW | 未完了 | レビュー | today |
| DONE | 完了 | 完了 | （設定なし） |
| BLOCKED | 未完了 | ブロック | someday |
タスク構造のマッピング
docs/sdd/tasks/
├── index.md → Things プロジェクト（全体）
├── phase-1/
│ ├── task-001.md → Things To-Do（見出し「Phase 1」配下）
│ ├── task-002.md → Things To-Do
│ └── task-003.md → Things To-Do
└── phase-2/
├── task-004.md → Things To-Do（見出し「Phase 2」配下）
└── task-005.md → Things To-Do
マッピング結果：
Things プロジェクト: [プロジェクト名] SDDタスク
├── 見出し: Phase 1 - [フェーズ名]
│ ├── To-Do: TASK-001: [タスク名]
│ ├── To-Do: TASK-002: [タスク名]
│ └── To-Do: TASK-003: [タスク名]
└── 見出し: Phase 2 - [フェーズ名]
├── To-Do: TASK-004: [タスク名]
└── To-Do: TASK-005: [タスク名]
受入基準のマッピング
タスクの受入基準はThingsのチェックリストにマッピングします：
{
"type": "to-do",
"attributes": {
"title": "TASK-001: データモデルの定義",
"checklist-items": [
{"title": "prisma/schema.prismaにUserモデルが定義されている"},
{"title": "prisma migrateが正常に実行できる"},
{"title": "TypeScript型定義が自動生成される"}
]
}
}
ワークフロー
SDDタスク一括送信フロー
1. docs/sdd/tasks/のindex.mdを読み取る
↓
2. 各フェーズのタスク詳細を読み取る
↓
3. ユーザーに送信対象を確認（全タスク or フィルタ）
↓
4. タスク構造をThings JSONにマッピング
↓
5. add-json URLを生成
↓
6. ユーザーに確認してURL実行
↓
7. 完了を報告
詳細な実行手順
ステップ1: タスクの読み取りと確認
[things-url] ステップ 1/4: docs/sdd/tasks/を読み取り中...
docs/sdd/tasks/から以下のタスクを検出しました：
Phase 1: 基盤構築（3タスク）
- TASK-001: データモデルの定義 [TODO]
- TASK-002: APIエンドポイントの実装 [IN_PROGRESS]
- TASK-003: 認証ミドルウェア [TODO]
Phase 2: UI実装（2タスク）
- TASK-004: ログイン画面 [TODO]
- TASK-005: ダッシュボード [TODO]
すべてのタスクをThingsに送信しますか？
それとも特定のフェーズ・ステータスでフィルタしますか？
ステップ2: JSONの構築
[things-url] ステップ 2/4: Things JSON を構築中...
以下の構造でThingsに送信します：
プロジェクト: [プロジェクト名] SDDタスク
├── Phase 1: 基盤構築
│ ├── TASK-001: データモデルの定義 [タグ: TODO]
│ ├── TASK-002: APIエンドポイントの実装 [タグ: 進行中, when: today]
│ └── TASK-003: 認証ミドルウェア [タグ: TODO]
└── Phase 2: UI実装
├── TASK-004: ログイン画面 [タグ: TODO]
└── TASK-005: ダッシュボード [タグ: TODO]
この内容でURLを生成してよろしいですか？
ステップ3: URL生成と実行
[things-url] ステップ 3/4: Things URL を生成中...
URLを生成しました。macOS環境のため直接実行します。
URL=$(python3 -c "
import urllib.parse, json
# ... JSON構築とエンコード ...
")
open "$URL"
ステップ4: 完了報告
[things-url] ステップ 4/4: 完了
Things 3に以下を送信しました：
- プロジェクト: 1件
- 見出し: 2件
- To-Do: 5件
Things 3アプリで確認してください。
TodoWriteタスク送信フロー
1. 現在のTodoWriteタスクを取得
↓
2. Things To-DoのJSON配列に変換
↓
3. ステータスに応じたタグ・when設定
↓
4. add-json URLを生成・実行
↓
5. 完了を報告
変換例：
TodoWriteの状態:
- [x] TASK-001: データモデルの定義（completed）
- [>] TASK-002: APIエンドポイントの実装（in_progress）
- [ ] TASK-003: 認証ミドルウェア（pending）
Things JSONへの変換:
[
{
"type": "to-do",
"attributes": {
"title": "TASK-001: データモデルの定義",
"completed": true,
"tags": ["完了"]
}
},
{
"type": "to-do",
"attributes": {
"title": "TASK-002: APIエンドポイントの実装",
"when": "today",
"tags": ["進行中"]
}
},
{
"type": "to-do",
"attributes": {
"title": "TASK-003: 認証ミドルウェア",
"tags": ["TODO"]
}
}
]
Things 3からの読み取り（macOS限定）
前提条件の確認
読み取り機能を使用する前に、macOS環境であることを確認します：
if [[ "$(uname)" != "Darwin" ]]; then
echo "読み取り機能はmacOS環境でのみ利用可能です"
exit 1
fi
今日のタスクを読み取る
[things-url] ステップ 1/3: macOS環境を確認中...
[things-url] ステップ 2/3: Things 3から今日のタスクを読み取り中...
osascript <<'APPLESCRIPT'
tell application "Things3"
set todoList to to dos of list "Today"
set output to ""
set openCount to 0
set doneCount to 0
repeat with t in todoList
set taskName to name of t
set taskStatus to status of t
if taskStatus is not canceled then
set taskTagNames to name of tags of t
set tagStr to ""
repeat with i from 1 to count of taskTagNames
if i > 1 then set tagStr to tagStr & ", "
set tagStr to tagStr & item i of taskTagNames
end repeat
set output to output & "- " & taskName & " [" & taskStatus & "]"
if tagStr is not "" then
set output to output & " (tags: " & tagStr & ")"
end if
set output to output & linefeed
if taskStatus is open then
set openCount to openCount + 1
else
set doneCount to doneCount + 1
end if
end if
end repeat
if output is "" then
return "(今日のタスクはありません)"
end if
set totalCount to openCount + doneCount
set output to output & linefeed & "合計: " & totalCount & "件（未完了: " & openCount & "件、完了: " & doneCount & "件）"
return output
end tell
APPLESCRIPT
[things-url] ステップ 3/3: 完了
Things 3「今日」のタスク一覧：
- [TASK-001]: データモデルの定義 [open] (tags: 進行中, SDD)
- [TASK-002]: APIエンドポイントの実装 [open] (tags: TODO, SDD)
- レビュー依頼への対応 [open] (tags: レビュー)
- ミーティング準備 [completed]
合計: 4件（未完了: 3件、完了: 1件）
プロジェクト一覧とタスクを読み取る
osascript <<'APPLESCRIPT'
tell application "Things3"
set projList to projects
set output to ""
repeat with p in projList
if status of p is open then
set projName to name of p
set todoList to to dos of p
set openCount to 0
set doneCount to 0
repeat with t in todoList
if status of t is open then
set openCount to openCount + 1
else if status of t is not canceled then
set doneCount to doneCount + 1
end if
end repeat
set output to output & "## " & projName & " (未完了: " & openCount & ", 完了: " & doneCount & ")" & linefeed
repeat with t in todoList
set taskName to name of t
set taskStatus to status of t
if taskStatus is open then
set output to output & " - [ ] " & taskName & linefeed
else if taskStatus is not canceled then
set output to output & " - [x] " & taskName & linefeed
end if
end repeat
set output to output & linefeed
end if
end repeat
if output is "" then
return "(アクティブなプロジェクトはありません)"
end if
return output
end tell
APPLESCRIPT
特定タグのタスクを読み取る
「Claude Code」タグや「SDD」タグが付いたタスクのみを取得する場合。全ビルトインリストおよびプロジェクト内を横断検索します：
osascript <<'APPLESCRIPT'
tell application "Things3"
set targetTag to "SDD"
set listNames to {"Inbox", "Today", "Upcoming", "Anytime", "Someday"}
set output to ""
-- 各ビルトインリストを検索
repeat with listName in listNames
set currentList to contents of listName
repeat with t in to dos of list currentList
set tagNames to name of tags of t
if tagNames contains targetTag then
set taskName to name of t
set taskStatus to status of t
if taskStatus is open then
set output to output & "- [ ] [" & currentList & "] " & taskName & linefeed
else if taskStatus is not canceled then
set output to output & "- [x] [" & currentList & "] " & taskName & linefeed
end if
end if
end repeat
end repeat
-- 各プロジェクト内も検索
repeat with p in projects
if status of p is open then
repeat with t in to dos of p
set tagNames to name of tags of t
if tagNames contains targetTag then
set taskName to name of t
set taskStatus to status of t
if taskStatus is open then
set output to output & "- [ ] [" & name of p & "] " & taskName & linefeed
else if taskStatus is not canceled then
set output to output & "- [x] [" & name of p & "] " & taskName & linefeed
end if
end if
end repeat
end if
end repeat
if output is "" then
return "(「" & targetTag & "」タグのタスクはありません)"
end if
return output
end tell
APPLESCRIPT
Things → TodoWrite 同期フロー
1. osascriptでThings 3から対象リスト/プロジェクトのタスクを取得
↓
2. 現在のTodoWriteの状態と比較
↓
3. 差分を検出してユーザーに提示
↓
4. ユーザー承認
↓
5. TodoWriteを更新
↓
6. 完了を報告
差分提示の例：
[things-url] Things → TodoWrite 同期
以下の変更を検出しました：
変更あり:
[TASK-001]: データモデルの定義
Things: completed → TodoWrite: in_progress → 更新: completed
[TASK-003]: 認証ミドルウェア
Things: open (tag: 進行中) → TodoWrite: pending → 更新: in_progress
変更なし:
[TASK-002]: APIエンドポイントの実装 (in_progress)
TodoWriteを更新してよろしいですか？
Things → SDD タスク同期フロー
1. osascriptでThings 3からSDDプロジェクトのタスクを取得
↓
2. `[TASK-XXX]` IDでdocs/sdd/tasks/の各タスクと照合
※ `[TASK-XXX]`形式のIDを持つタスクのみ同期対象とする
※ `[TASK-XXX]`パターンに一致しないファイルはスキップして保持する
↓
3. ステータスの差分を検出
↓
4. ユーザーに差分を提示
↓
5. ユーザー承認
↓
6. docs/sdd/tasks/のタスクファイルを更新
※ `[TASK-XXX]` IDで照合されたファイルのみ更新する
※ 非SDDタスク（外部作成のファイル）は変更・削除しない
↓
7. TodoWriteも連動更新
※ 非SDDタスクのtodo（contentが`[Phase-`または`[BLOCKED] [Phase-`で始まらないもの）はそのまま保持する
↓
8. 完了を報告
既存アイテムの更新
auth-tokenの取得
既存のThingsアイテムを更新するにはauth-tokenが必要です：
auth-tokenはThings 3の設定画面から確認できます：
- Mac: Things → Settings → General → Enable Things URLs → Manage
- iOS: Settings → General → Things URLs
auth-tokenをお知らせください（このスキルでは保存しません）。
更新URLの生成
auth-tokenはコマンドライン引数に直書きせず、環境変数経由で安全に渡します：
read -s -p "Things auth-token: " THINGS_AUTH_TOKEN && echo
THINGS_AUTH_TOKEN="$THINGS_AUTH_TOKEN" python3 -c "
import urllib.parse, subprocess, os
auth_token = os.environ['THINGS_AUTH_TOKEN']
params = {
'id': 'THINGS_ITEM_ID',
'auth-token': auth_token,
'when': 'today',
'append-notes': '\n\n[更新: YYYY-MM-DD] ステータスがIN_PROGRESSに変更されました'
}
query = urllib.parse.urlencode(params, quote_via=urllib.parse.quote)
url = f'things:///update?{query}'
subprocess.run(['open', url])
"
セキュリティ上の注意:
- auth-tokenはコマンドライン引数に直書きしないでください。シェル履歴（
~/.bash_history）やプロセス一覧（ps）に残るおそれがあります
read -sで標準入力から受け取り、環境変数経由でスクリプトに渡してください- auth-tokenを含むURLは
print()で標準出力に表示しないでください
- auth-tokenはファイルに保存しません。毎回ユーザーに確認します
Areaの活用
プロジェクトをThingsのAreaに配置する場合：
params = {
'title': 'SDD Phase 1',
'area': '開発プロジェクト',
}
{
"type": "project",
"attributes": {
"title": "SDD Phase 1",
"area": "開発プロジェクト",
}
}
制約事項
Things URLスキームの制限
- 文字数制限: パラメータの最大エンコード前文字数は4,000文字（notesは10,000文字）
- レート制限: 10秒間に最大250アイテム
- macOS/iOS限定: Things 3はAppleプラットフォーム専用
- 更新にはauth-tokenが必要: 既存アイテムの更新にはユーザーからのauth-token提供が必要
- IDの取得: x-callback-urlを使わない限り、作成したアイテムのIDは自動取得できない
スキルの制限
- 読み取り機能はmacOSのみ: AppleScript（
osascript）はmacOS環境でのみ動作。Linux/Windows環境では書き込み（URL生成）のみ利用可能
- 自動同期は非対応: Things側での変更のClaude Codeへの反映はユーザーの明示的な指示が必要です。自動検知を行わない理由は、意図しないステータス変更の伝播を防ぎデータ整合性を保つためです。将来的にはThings MCPサーバーとの連携で自動同期の実現を検討しています（「今後の拡張」を参照）
- auth-tokenの永続化なし: セキュリティのため、auth-tokenは保存しない
openコマンドはmacOSのみ: Linux/Windows環境ではURLの提示のみ
ベストプラクティス
適切な粒度での送信
良い例: フェーズごとにプロジェクトを分けて送信
プロジェクト: Phase 1 - 基盤構築（5タスク）
プロジェクト: Phase 2 - UI実装（3タスク）
悪い例: 全タスクを1つのプロジェクトに詰め込む
プロジェクト: 全タスク（50タスク） # 見通しが悪い
タグの活用
一貫したタグ付けでフィルタリングを容易にします：
推奨タグ：
Claude Code: Claude Codeから送信されたタスクであることを示すSDD: SDDプロセスのタスクであることを示す- ステータスタグ:
TODO、進行中、レビュー、ブロック
notesへの文脈情報の記載
Things側で人間が判断できるよう、十分な文脈をnotesに含めます：
notes に含めるべき情報：
- タスクの目的・背景
- 受入基準（チェックリストにも反映）
- 依存関係
- 関連ファイルパス
- 推定工数
定期的な同期
大きな進捗があったタイミングで再送信を提案します：
- フェーズの開始時
- 複数タスクのステータスが変わった時
- 新しいタスクが追加された時
リソース
リファレンス
外部リソース
今後の拡張
このスキルは将来的に以下の機能追加を検討しています：
- Things MCPサーバーとの連携による自動同期（現在はAppleScriptベースの手動同期）
- Shortcuts連携によるiOS/iPadOSからの操作
- プロジェクトテンプレートの事前定義
- タスク完了時の自動通知URL生成
