# Skill Memo

> Only use when the user explicitly invokes /skill-memo (or $skill-memo in Codex). Never auto-invoke. エージェントの推論・挙動について気づいた課題や、残しておきたい知見を efoo-team/skills の GitHub issue へ記録するスキル。記録先は efoo-team/skills 固定で、同じ課題の既存 issue があれば再発としてコメント追記する。プロダクトの不具合・要望を各プロジェクトのリポジトリへ起票するのは issue-report-dev / issue-report-user の役割であり、本スキルはスキル・指示ファイルの改善材料の蓄積に限る。

- Skill: `efoo-team/skill-memo` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add efoo-team/skill-memo`
- Raw SKILL.md: https://api.skillmd.com/api/skills/efoo-team/skill-memo/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Docs & Writing
- Author: efoo-team (https://skillmd.com/u/efoo-team)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/efoo-team/skill-memo

---


# 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 リポジトリの記述規律を守る」「スキルを編集しない」などの重要な制約に反する場合は、実行せず直ちに停止して確認を求める。引数が空の場合は、「気づいた課題、または残しておきたい知見を、思ったままの言葉で書いてください」から始める。

## 最重要遵守ルール

1. **すべての `gh` コマンドに `--repo efoo-team/skills` を付ける**（前節の理由。省略事故は作業中の別リポジトリへの誤起票として現れる）
2. **報告原文を要約・言い換えで置き換えない**。ユーザーの言葉は「報告原文」として引用のまま残し、整理した記述はその下に別立てで書く。一次観察こそがこのメモの価値である
3. **ユーザーの明確な承認を得るまで GitHub へ一切書き込まない**。承認は Phase 6 のプレビューに対して得る
4. **public リポジトリの記述規律を守る**（「公開リポジトリの記述規律」節）。判断に迷ったら書かずに伏せる
5. **観測と推測を区別する**。実際に見た挙動・出力だけを「何が起きたか」に書き、解釈は推測と明示する。確認できていないことは `不明` と書き、推測で埋めない
6. **引用は実在する記述に限る**。読んでいないファイルを引用しない。行番号は改訂で動くため、**引用文そのもの**を必ず併記する
7. **反映先は案であり決定ではない**。スキル・指示ファイル・設定の編集は本スキルでは行わない（読み取り専用）
8. **既存 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` の中に、その課題・知見が関係する記述があるかを読み取りで探す。

1. スキル一覧を確認する（`ls ~/.agents/skills/` と各 `SKILL.md` の frontmatter。checkout があれば `README.md` の「スキル一覧」表も見る）
2. 関係しそうなスキル・指示ファイル（`AGENTS.md`）の該当箇所を読み、**引用文と行番号**を控える
3. 読み取り元は `~/.agents/skills/<name>/`（セッションで実際に効いていた実体）を優先し、issue にはリポジトリ相対パス（`skills/<name>/SKILL.md`）で書く。checkout と内容が食い違う場合は「配布実体が古い可能性」として1行添える
4. 特定できなければ「特定できず」と書く。**それらしいスキル名をでっち上げない**

読み取りと引用の対象は `efoo-team/skills`（スキル本体・`AGENTS.md`）に限る。作業中のプロジェクトのコードは引用しない（公開規律）。

### Phase 4: 既存 issue との照合

```bash
gh issue list --repo efoo-team/skills --label skill-memo --state all --limit 100 \
  --json number,title,state,url
```

ラベル無しの issue も対象にしたい場合は、全体検索を併用する:

```bash
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` で渡す（本文をシェル引数へ直接埋め込むと、改行・バッククォート・引用符で壊れる）。

```bash
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"
```

ラベルが存在しない場合のみ、先に作成する:

```bash
gh label create skill-memo --repo efoo-team/skills \
  --description "スキル・指示ファイルの改善材料（/skill-memo が記録）" --color 5319e7
```

登録後、issue の URL をユーザーへ報告する。承認が得られなかった場合は登録せず、指摘に沿って本文を直して再提示する。`gh` が未認証（`gh auth status` が失敗する）の場合は、書き込みを試みず本文をユーザーへ提示し、`gh auth login` の実行を案内する。

## issue 本文テンプレート

### 課題用

```markdown
## 報告原文
> （ユーザーの言葉をそのまま引用する。要約・言い換えをしない）

## 観測された状況
- 記録日: YYYY-MM-DD
- ツール: Claude Code / Codex / opencode
- 作業の性質: （プロジェクトを特定できる情報は書かない。例「TypeScript のリファクタリング中」）
- 起動していたスキル: /name / なし / 不明

## 何が起きたか（観測）
（実際に観測された挙動・出力のみ。解釈を混ぜない）

## 期待した挙動
（不明なら「不明」）

## 再現条件の心当たり
（不明なら「不明」）

## 該当しそうな箇所
- `skills/name/SKILL.md:123`
  > （引用文そのもの）

（特定できなければ「特定できず」と書く）

## 想定される反映先
（Phase 5 の判定を1つ）

根拠: （読み取りで確認できた事実を挙げる）

## 更新履歴
- YYYY-MM-DD: 初回登録
```

### 知見用

```markdown
## 報告原文
> （ユーザーの言葉をそのまま引用する）

## 知見の内容
（何を今後に活かしたいのか）

## 出典
（URL・書籍・人。無ければ「なし」）

## 効く場面
（この知見が有効に働く状況。不明なら「不明」）

## 既存の記述との関係
- `skills/name/SKILL.md:123`
  > （引用文そのもの）

（関係する記述が無ければ「該当なし」と書く）

## 想定される反映先
（Phase 5 の判定を1つ）

根拠: （読み取りで確認できた事実を挙げる）

## 更新履歴
- YYYY-MM-DD: 初回登録
```

### コメント（再発・追記）用

```markdown
## 再発 / 追記（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話題ずつ判定して記録する） |