efoo-team skill-memo
エージェントとの作業中に気づいた「推論・挙動の課題」と「残しておきたい知見」を、efoo-team/skills の GitHub issue として記録・蓄積するスキル。
目的
スキルや指示ファイルの改善は、気づいた瞬間の一次観察がなければ始まらない。その観察はセッションが終われば失われ、後から思い出しても「なんとなく変だった」に劣化する。本スキルは、その場の観察を証拠つきで issue に固定し、後日の改善判断（誰が・どこを・どう直すか）が行える状態にするところまでを行う。
改善の実施は行わない。既存スキルの改訂は別セッションの仕事であり、新規スキルの作成は /create-skill の仕事である。
記録先（固定値）
| 項目 | 値 |
|---|---|
| リポジトリ | efoo-team/skills（public。誰でも読める） |
| ラベル | skill-memo（全メモに必ず付与する） |
| スキル実体の読み取り元 | ~/.agents/skills/<name>/（配布実体。セッションで実際に効いていた版） |
| 正本の checkout | ~/ghq/github.com/efoo-team/skills（存在すれば併せて参照する） |
| issue 本文でのパス表記 | 正本のリポジトリ相対パス（skills/<name>/SKILL.md） |
本スキルは、作業中のリポジトリが何であれ、常に efoo-team/skills へ記録する。 gh は cwd の git リポジトリを既定の対象にするため、すべての gh コマンドに --repo efoo-team/skills を明示する。省略すると、作業中のプロジェクト（クライアント案件を含む）のリポジトリへメモが立つ。
追加指示の扱い
ユーザーが引数として渡した内容（Claude では /skill-memo の引数、Codex では $skill-memo の引数）は、記録したい課題・知見の最初の説明として扱い、本スキル内の他の方針より優先して適用する。ただし「承認なしに GitHub へ書き込まない」「public リポジトリの記述規律を守る」「スキルを編集しない」などの重要な制約に反する場合は、実行せず直ちに停止して確認を求める。引数が空の場合は、「気づいた課題、または残しておきたい知見を、思ったままの言葉で書いてください」から始める。
最重要遵守ルール
- すべての
ghコマンドに--repo efoo-team/skillsを付ける（前節の理由。省略事故は作業中の別リポジトリへの誤起票として現れる） - 報告原文を要約・言い換えで置き換えない。ユーザーの言葉は「報告原文」として引用のまま残し、整理した記述はその下に別立てで書く。一次観察こそがこのメモの価値である
- ユーザーの明確な承認を得るまで GitHub へ一切書き込まない。承認は Phase 6 のプレビューに対して得る
- public リポジトリの記述規律を守る（「公開リポジトリの記述規律」節）。判断に迷ったら書かずに伏せる
- 観測と推測を区別する。実際に見た挙動・出力だけを「何が起きたか」に書き、解釈は推測と明示する。確認できていないことは
不明と書き、推測で埋めない - 引用は実在する記述に限る。読んでいないファイルを引用しない。行番号は改訂で動くため、引用文そのものを必ず併記する
- 反映先は案であり決定ではない。スキル・指示ファイル・設定の編集は本スキルでは行わない（読み取り専用）
- 既存 issue の本文は原則書き換えず、追記はコメントで行う。本文の更新は「反映先の判定が変わった」「タイトルが実態と合わなくなった」等の理由がある場合に限り、承認を得て行い、変更点をコメントにも残す
実行手順
進捗チェックリスト（応答に貼って使う）:
- [ ] Phase 1: 報告原文を保存し、種別（課題 / 知見）を判定
- [ ] Phase 2: 不足している状況を補完（全質問スキップ可）
- [ ] Phase 3: efoo-team/skills 内の該当箇所を特定して引用
- [ ] Phase 4: 既存 issue と照合（新規 or コメント）
- [ ] Phase 5: 想定される反映先を判定
- [ ] Phase 6: 本文をプレビュー → 承認 → gh で登録
Phase 1: 受け取りと種別の判定
引数（または会話）の内容をそのままの文言で控える。これが issue の「報告原文」になる。
| 種別 | 該当するもの | タイトル接頭辞 |
|---|---|---|
| 課題 | エージェントの推論・判断・出力に対して「おかしい」「こうしてほしくない」と感じたこと | [課題] |
| 知見 | 今後の指示・スキルへ取り込みたい情報、参考にしたい外部の記事・手法・事実 | [知見] |
1回の入力に複数の話題が混ざっている場合は話題ごとに分割し、1話題ずつ Phase 2 以降を回す（まとめて1 issue にしない）。分割した結果をユーザーへ提示して確認してから進む。
Phase 2: 状況の補完
issue として使えるだけの情報が揃っているかを確認し、足りない項目だけを質問する。揃っていれば質問しない。
| 種別 | 確認すること |
|---|---|
| 課題 | 何が起きたか（実際の挙動）／期待した挙動／どのスキル・どの作業の最中だったか／再現条件の心当たり |
| 知見 | 内容そのもの／出典（URL・書籍・人）／どういう場面で効くと思うか |
- すべての質問はスキップできる。質問のたびに「わからなければ飛ばして構いません」と明示し、得られなかった項目は
不明と書く - 別セッションでの出来事で詳細を思い出せない場合は、
/search-history <キーワード>（Codex では$search-history）でその会話を掘り起こしてから戻るよう案内する。明示起動専用のスキルであり、本スキルからは起動できない
Phase 3: 該当箇所の特定と引用
efoo-team/skills の中に、その課題・知見が関係する記述があるかを読み取りで探す。
- スキル一覧を確認する（
ls ~/.agents/skills/と各SKILL.mdの frontmatter。checkout があればREADME.mdの「スキル一覧」表も見る） - 関係しそうなスキル・指示ファイル（
AGENTS.md）の該当箇所を読み、引用文と行番号を控える - 読み取り元は
~/.agents/skills/<name>/（セッションで実際に効いていた実体）を優先し、issue にはリポジトリ相対パス（skills/<name>/SKILL.md）で書く。checkout と内容が食い違う場合は「配布実体が古い可能性」として1行添える - 特定できなければ「特定できず」と書く。それらしいスキル名をでっち上げない
読み取りと引用の対象は efoo-team/skills（スキル本体・AGENTS.md）に限る。作業中のプロジェクトのコードは引用しない（公開規律）。
Phase 4: 既存 issue との照合
gh issue list --repo efoo-team/skills --label skill-memo --state all --limit 100 \
--json number,title,state,url
ラベル無しの issue も対象にしたい場合は、全体検索を併用する:
gh search issues --repo efoo-team/skills "キーワード" --json number,title,state,url
| 照合結果 | 対応 |
|---|---|
| 同じ課題・知見の open な issue がある | その issue へコメント追記する（再発・追記として記録） |
| 一致する issue が closed | 「再オープンして追記」か「新規作成して closed issue を参照」かをユーザーへ確認する |
| 一致するものが無い | 新規 issue を作成する |
「同じ課題」の判定は、現象の一致ではなく失敗の型の一致で行う。表面の言葉が違っても「同じ記述を同じように読み違えている」なら同一とみなし、逆に同じスキル名が出てきても失敗の型が違えば別 issue にする。判断根拠は本文またはコメントに書く。
Phase 5: 想定される反映先の判定
読み取った事実をもとに、どこを直せばこの課題が解消するか／この知見はどこに置くべきかを1つ選び、根拠を添える。
| 反映先 | 選ぶ条件 |
|---|---|
既存スキル <name> への追記 |
その場面で起動する（または起動すべき）スキルが既にあり、記述の追加・修正で対処できる |
| 新規スキルの候補 | 対応する既存スキルが無く、かつ特定の場面でだけ必要になる手順・知識・判断基準である |
指示ファイル（AGENTS.md / CLAUDE.md） |
全セッションで常時必要な規約・憲章であり、スキルの発火に依存させてはならない |
| スキル以外の機構（hook / 設定 / スクリプト） | 100% 守られる必要がある保証、または入出力が決定的な処理である |
| 判断保留 | 情報が足りず、上のどれとも決められない |
- 既存スキルへの追記を第一候補とする。新規スキルは「既存のどれにも収まらない」ことを確認してから選ぶ
- 新規スキル候補と判定した場合も、名前案・本文案は書かない（
/create-skillのヒアリングで決めるべきものであり、ここで先取りすると判断を固定してしまう）。「どういう場面で発火してほしいか」だけを書く - この判定は案であり、issue の読み手が覆してよい。断定形で書かない
Phase 6: 起草・承認・登録
本文を組み立て、登録前に必ずユーザーへプレビューを提示する。提示するもの:
- 新規作成か、既存 issue（番号・タイトル）へのコメントか
- タイトル案
- 本文の全文
- 公開規律に基づいて伏せた項目の一覧（伏せたものがある場合）
承認を得たら本文を一時ファイルへ書き出し、--body-file で渡す（本文をシェル引数へ直接埋め込むと、改行・バッククォート・引用符で壊れる）。
BODY="$(mktemp "${TMPDIR:-/tmp}/skill-memo.XXXXXX")"
cat > "$BODY" <<'EOF'
（本文）
EOF
# 新規作成
gh issue create --repo efoo-team/skills --label skill-memo \
--title "[課題] 対象: 1行要約" --body-file "$BODY"
# 既存 issue へコメント
gh issue comment 12 --repo efoo-team/skills --body-file "$BODY"
ラベルが存在しない場合のみ、先に作成する:
gh label create skill-memo --repo efoo-team/skills \
--description "スキル・指示ファイルの改善材料（/skill-memo が記録）" --color 5319e7
登録後、issue の URL をユーザーへ報告する。承認が得られなかった場合は登録せず、指摘に沿って本文を直して再提示する。gh が未認証（gh auth status が失敗する）の場合は、書き込みを試みず本文をユーザーへ提示し、gh auth login の実行を案内する。
issue 本文テンプレート
課題用
## 報告原文
> （ユーザーの言葉をそのまま引用する。要約・言い換えをしない）
## 観測された状況
- 記録日: YYYY-MM-DD
- ツール: Claude Code / Codex / opencode
- 作業の性質: （プロジェクトを特定できる情報は書かない。例「TypeScript のリファクタリング中」）
- 起動していたスキル: /name / なし / 不明
## 何が起きたか（観測）
（実際に観測された挙動・出力のみ。解釈を混ぜない）
## 期待した挙動
（不明なら「不明」）
## 再現条件の心当たり
（不明なら「不明」）
## 該当しそうな箇所
- `skills/name/SKILL.md:123`
> （引用文そのもの）
（特定できなければ「特定できず」と書く）
## 想定される反映先
（Phase 5 の判定を1つ）
根拠: （読み取りで確認できた事実を挙げる）
## 更新履歴
- YYYY-MM-DD: 初回登録
知見用
## 報告原文
> （ユーザーの言葉をそのまま引用する）
## 知見の内容
（何を今後に活かしたいのか）
## 出典
（URL・書籍・人。無ければ「なし」）
## 効く場面
（この知見が有効に働く状況。不明なら「不明」）
## 既存の記述との関係
- `skills/name/SKILL.md:123`
> （引用文そのもの）
（関係する記述が無ければ「該当なし」と書く）
## 想定される反映先
（Phase 5 の判定を1つ）
根拠: （読み取りで確認できた事実を挙げる）
## 更新履歴
- YYYY-MM-DD: 初回登録
コメント（再発・追記）用
## 再発 / 追記（YYYY-MM-DD）
- 状況: （ツール・作業の性質・起動していたスキル）
- 今回の観測: （実際の挙動・出力）
- 同一と判断した根拠: （失敗の型のどこが一致するか）
- 前回との差分: （無ければ「同一」）
コメントを追記したら、issue 本文の「更新履歴」へ1行追記する（この1行のみ本文編集の例外とし、承認済みプレビューに含める）。
公開リポジトリの記述規律
efoo-team/skills は public であり、issue は誰でも読める。メモの素材は他プロジェクトでの作業中に生まれるため、そのまま書くと第三者の情報が公開される。
書かないもの
- クライアント名・屋号・案件名・サービス名・リポジトリ名・ブランチ名・他リポジトリの issue / PR 番号
- 他リポジトリのファイルパス・シンボル名・ソースコードの引用・ログの生貼り
- 個人名・メールアドレス・社内 URL・ドメイン・認証情報・環境変数の値
書いてよいもの
efoo-team/skills内のファイルパスと引用（このリポジトリ自体が公開されているため）- プロジェクトを特定できない一般的な技術表現での作業の性質
- エージェントの推論・出力を、固有名詞を伏せて抽象化した記述
抽象化の書き方
伏せる前:
~/ghq/github.com/ORG/PROJECT/src/features/billing/invoice.tsの請求書生成で、エージェントがtaxRateを 0.1 の決め打ちにした
伏せた後:
あるプロジェクトの金額計算処理で、設定値を参照すべき箇所へエージェントが定数を直接書き込んだ
伏せた項目がある場合は、その位置に （プロジェクト固有のため伏せる） と明記する。伏せたこと自体は隠さない。
対象外（本スキルで行わないこと）
| やらないこと | 代わりに使うもの |
|---|---|
| スキル・指示ファイル・設定の編集 | 改訂は別セッション、新規作成は /create-skill |
| プロダクトの不具合・機能要望の起票 | /issue-report-dev（エンジニア）/ /issue-report-user（非エンジニア） |
| 会話履歴の検索 | /search-history |
| 複数メモのグルーピング・優先順位付け | 行わない（1話題ずつ判定して記録する） |