1仕組みと動作原理
完全なプロンプトオーケストレーション：スキルの全機能はモデルに対する指示テキストのみで構成され、ディレクトリ内には SKILL.md と1つのインターフェース宣言ファイルのみが存在し、スクリプトやコードは一切ありません。「議論済みの内容を spec にまとめる」という振る舞いを、規律あるドキュメント作成フローとしてモデル化しています。
skills/engineering/to-spec/SKILL.md
This skill takes the current conversation context and codebase understanding and produces a spec. Do NOT interview the user; just synthesize what you already know.
冒頭で入力＝セッションのコンテキスト＋コードベースの理解と定義し、続いて振る舞いの制約（追加インタビューの禁止）を宣言しています。ファイル全体がモデルへの指示文であり、実行可能コードは一切含みません。
リポジトリ内のエンジニアリングスキル群とランタイム規約を共有：イシュートラッカーやトリアージ用のラベル語彙はこのスキル内にハードコードされず、setup-matt-pocock-skills によって一度設定されて docs/agents/*.md に書き出され、to-spec が必要に応じて読み取ります。これにより、自身にコードを持たずに GitHub／GitLab／ローカル markdown を切り替えられます。
skills/engineering/setup-matt-pocock-skills/SKILL.md
Skills like `to-tickets`, `triage`, and `to-spec` read from and write to it. They need to know whether to call `gh issue create`, write a markdown file under `.scratch/`, or follow some other workflow you describe.
setup の SKILL.md では、to-spec がイシュートラッカーの読み書きを行う側の1つとして明記されています。具体的なチャンネル（gh issue create、.scratch/ 配下のローカル md、またはその他のワークフロー）は setup 時にユーザーが選定し、docs/agents/issue-tracker.md に保存されます。to-spec 自体は特定のチャンネルを前提としません。
公開アクションとラベル付けがプロセスの終点：テンプレートを記入した後にトラッカーへ公開し、ready-for-agent ラベルを付与します。ラベル文字列は triage-labels.md の「ロール→実際の文字列」マッピングを介して解決されるため、ユーザー定義の語彙（例：bug:triage）にも対応します。
skills/engineering/to-spec/SKILL.md
Write the spec using the template below, then publish it to the project issue tracker. Apply the `ready-for-agent` triage label - no need for additional triage.
triage-labels.md のシードテーブルは5つの標準ロールを実際のラベル文字列にマッピングしています（「スキルがロールに言及した場合、このテーブルの対応するラベル文字列を使用する」）。to-spec が参照する ready-for-agent もその1つです。
仕様本文に対する厳格なコンテンツ規律：spec は設計判断を記録するものであり、コードのダンプではありません。テンプレートでは陳腐化を防ぐためファイルパスやコードスニペットの記述を明示的に禁止し、散文よりも正確なプロトタイプ由来の決定事項の断片（ステートマシン、reducer、スキーマ、型の形状など）のみ例外的にインライン記述を許可しています。
skills/engineering/to-spec/SKILL.md
Do NOT include specific file paths or code snippets. They may end up being outdated very quickly. Exception: if a prototype produced a snippet that encodes a decision more precisely than prose can (state machine, reducer, schema, type shape), inline it within the relevant decision and note briefly that it came from a prototype.
これは一般的な「ドキュメント作成」スキルと一線を画す設計上の重要点です。spec は将来の AFK（自律実行）エージェント向けに作成されるため、陳腐化しやすい実装の詳細は意図的に排除されています。
テスタビリティの先行設計：フローのステップ2では、spec を書く前にテストシーム（既存のシームを優先、より上位レイヤー、リポジトリ全体で理想的には1つ）の設計を要求し、そのシームが期待通りであるかをユーザーに確認することを義務付けています。「どうテストするか」を仕様出力前の人間による確認ポイントとして組み込んでいます。
skills/engineering/to-spec/SKILL.md
Sketch out the seams at which you're going to test the feature. Existing seams should be preferred to new ones. Use the highest seam possible. If new seams are needed, propose them at the highest point you can. The fewer seams across the codebase, the better - the ideal number is one. Check with the user that these seams match their expectations.
「seams（シーム）」の概念は spec の Testing Decisions セクション全体を通じて貫かれており（外部振る舞いのみをテスト）、テストファーストのエンジニアリング思想と一致しています。
2コア機能
01インタビュー不要の仕様統合：現在の会話内容を直接 spec へ統合
02リポジトリ認識：spec 作成前にコードベースの現状を調査し、ドメイン語彙や ADR に準拠
03テストシームの計画：テスト可能な境界をあらかじめ定め、可能な限り上位かつ最小限のシームを選択
04テストシームの人手確認ポイント：spec 作成前にテストシームをユーザーと確認
05固定された7セクションの仕様テンプレート出力（問題、解決策、ユーザーストーリー、実装の決定事項、テストの決定事項、対象外、備考）
06プロジェクトのイシュートラッカーへ公開し、ready-for-agent ラベルを付与（追加トリアージを省略）
07陳腐化を防ぐコンテンツ規律：spec へのファイルパスやコードスニペットの記述を禁止し、プロトタイプの決定事項の断片のみ例外的にインライン記述
3外部依存関係
| Kind | Dependency / Endpoint |
|---|---|
| cli | gh (GitHub CLI) |
| cli | glab 或自定义工作流（GitLab/其他 tracker 场景） |
| network | 用户自有的 issue tracker 端点（GitHub 默认：github.com API） |
4推奨統制措置と判定根拠
安全運用のための推奨統制措置
Agent 向け
アクセス可能ドメインとキー範囲を宣言
管理者向け
最小権限のキー、リクエストログを保持
判定根拠（ファイルパスと抜粋）
- 外部服务: ホストのネットワークツールまたは外部 API 取得に依存
監査ノート： 純粋なプロンプト型スキルです。スクリプトや認証情報の読み込みはなく、スキルファイル内にもネットワークエンドポイントは存在しません。ただし、中核機能である「イシュートラッカーへの spec 公開」は実行ごとに外部状態を変更します。トラッカーが GitHub（setup のデフォルト）の場合は公式の gh CLI を経由してネットワーク経由でユーザー自身のリポジトリに書き込みを行い、送信先は予測可能です。トラッカーがローカル markdown の場合はローカルファイルへの書き込みにフォールバックします。ユーザーが明示的にトリガーした場合にのみ実行され（disable-model-invocation および allow_implicit_invocation: false の二重安全措置）、自律的に実行されることはありません。
5二重目の独立検証
- [ok] 文件清单：skills/engineering/to-spec/ 恰为 SKILL.md + agents/openai.yaml 两文件，无隐藏脚本 — gh api 递归树确认；本地工作树 engineering/to-spec/ 同构（本地为 skills/ 子目录内容平铺）
- [ok] 外部依赖 gh CLI：to-spec 自身不含调用 — to-spec 两文件全文重读，确实零 gh/命令引用；gh 命令只存在于 setup 的 issue-tracker-github.md 种子与 setup 流程产出的 docs/agents/issue-tracker.md——引用关系真实存在（setup SKILL.md: 'Skills like to-tickets, triage, and to-spec read from and write to it'）
- [ok] ready-for-agent 标签与词表映射 — triage-labels.md 五行词表中 ready-for-agent 存在，映射语义='Fully specified, ready for an AFK agent'，与 to-spec『spec 发布后免额外 triage』自洽
- [ok] 触发限制声明 — SKILL.md frontmatter disable-model-invocation: true 与 openai.yaml allow_implicit_invocation: false 两份文件均实读确认
- [ok] 功能声明 vs 实际能力相符性 — 描述称『publish to the project issue tracker』，实际靠 setup 预置文档提供通道，流程第 1 行也明说词表应已提供、缺失则叫用户跑 /setup-matt-pocock-skills——有条件前提但如实声明，无夸大
- [ok] 网络端点/凭据读取反例搜索 — 两文件内无 URL、无 env/keychain 读取、无文件写入指令；唯一外发是经宿主 CLI 到用户自有 tracker
- [ok] LICENSE/元数据 — gh api: license MIT（仓库根 LICENSE）、stars 253957（2026-09-06 实时快照值）、pushed_at 2026-09-04T08:45:43Z
6結論
最適な用途： setup-matt-pocock-skills を実行済みで、「実装前に仕様を定義する」プロセスを採用しているエンジニアリングチームに最適です。開発者が AI とソリューションを議論した後、単一のコマンドで標準化された spec にまとめ、後続エージェント実行用の ready-for-agent キューに投入できます。「仕様をドキュメントとして残し、追跡可能性を維持する」ワークフローを重視し、成熟したイシュートラッカーを持つリポジトリに最も適しています。
不向きな用途： 不向きなケース：イシュートラッカーを持たない、または事前のセットアップを行いたくない一時的なプロジェクト。要件がまだ曖昧で質問による確認が必要な場面（このスキルは意図的に聞き取りを行いません）。具体的な実装詳細やファイルパスレベルの指示を含む仕様を必要とするチーム（テンプレートで明示的に禁止）。
Install Agent-Ready
① Verified Mirror 2026-09-06
Option A · Direct DownloadDownload to-spec.tar.gz
sha256:
Option B · Copy Guide for Agent3a4ea2541cdd9f0b…Agent はこの JSON ガイドから自動的にダウンロードして検証します。
② Upstream GitHub
GitHub Repo ↗
Pinned to commit 3cca18b368.