dir-entry

name	dir-entry
description	TRIGGER: 作業ディレクトリの入り口に「AI エージェント用 INDEX.md」と「人間用 README.md」を整備したい場合。ユーザーが /dir-entry [path] を入力、または「INDEX と README 作って」「作業ディレクトリの入り口ファイルを整備」「AI 用 index と人間用 readme を作って」と依頼したとき。SKIP: 既存 README を機械的に上書きしたいだけの場合・入り口ファイルを増やしたくない単発ディレクトリ・INDEX/README 以外のドキュメント生成。

/dir-entry

任意の作業ディレクトリの入り口に、AI エージェントが最初に読む INDEX.md と 人間が最初に読む README.md を生成・更新する共通スキル。既存 README.md は保持し、不足を補う形で更新する。

引数

引数	必須	既定
path	×	カレントディレクトリ（$PWD）

引数なしで呼ばれた場合はカレントディレクトリ。/dir-entry ~/Dev/foo のように指定されればそこへ。 複数の候補が考えられる場合（例：カレントがクラウド同期配下の PJ なのか、その親ディレクトリなのか）は 1 問だけ問い返す。

ファイル責務の分離

ファイル	読者	内容
INDEX.md	AI エージェント（各種コーディングエージェント等）	機械可読寄り。frontmatter・ツリー・キーファイル・規約・関連スキル・最近のログ
README.md	人間（オーナー・チームメンバー）	目的・クイックスタート・運用ルール・現状サマリ・FAQ

両者は 目的の補完関係：人間向け README に書ききれない構造情報を INDEX に集約する。両者で同じ事を書かない（リンクで参照する）。

実行手順

1. ディレクトリの状態把握

• ls -la <path> でルート直下のファイル・ディレクトリ一覧
• 既存 README.md / INDEX.md / CLAUDE.md / AGENTS.md の有無確認
• プロジェクトタイプの簡易推定（次のヒューリスティクス）:
  • package.json → Node/JS プロジェクト
  • pyproject.toml / requirements.txt → Python プロジェクト
  • .git/ あり → ローカル git リポ
  • パスにクラウド同期フォルダ（例：CloudStorage/...）を含む → クラウド同期領域
  • operations/log.jsonl / handoff/ / strategy/ の組合せ → 業務 PJ 構造
  • personas/ / agents/ → エージェント開発プロジェクト

2. 既存 README.md の読み取りと保持判断

• 既存があれば全文を読む
• 以下のセクションは 保持 する（ユーザーが意図的に書いたものとみなす）:
  • 目的 / Purpose / 概要 / About
  • ライセンス / License
  • 寄稿 / Contributing
  • 引用 / 著者
  • 警告 / 禁止事項（例：「ここに置かないもの」「ローカル機密境界」）
• 以下のセクションは 更新/再生成 する（時間で陳腐化するため）:
  • ディレクトリ構成 / ツリー
  • 現状サマリ / ステータス
  • 最近の更新 / 直近ログ

3. INDEX.md の生成

以下のテンプレートに沿って生成。項目はディレクトリ実態に応じて取捨。

---
type: ai-index
generated: <yyyy-mm-dd>
project: <ディレクトリ名 or 推定 PJ 名>
project_type: <local-repo | cloud-sync-pj | personal-workspace | etc.>
visibility: <PUBLIC | PRIVATE | local-only>
canonical_path: <絶対パス>
---

# INDEX — AI エージェント向け案内

> このファイルは **AI エージェントが最初に読むこと** を想定しています。
> 人間向けの説明は `README.md` を参照してください。

## エントリポイント（先に読むべき順）

1. `<file1>` — <一文の目的説明>
2. `<file2>` — <同上>
3. `<file3>` — <同上>

## ディレクトリ構造（責務マップ）

| パス | 責務 | 主な拡張子・形式 |
|---|---|---|
| `<dir1>/` | <一文の責務> | `.md` |
| `<dir2>/` | <同上> | `.jsonl` |
| ... | ... | ... |

## ファイル命名・形式の規約

- <例: `yyyymmdd-<内容>` プレフィックス>
- <例: `log.jsonl` の 1 行 JSON フォーマット>
- <例: 人名禁止・actor は `owner`/`agent`/`system` のみ>

## 関連スキル

| コマンド | 用途 |
|---|---|
| `/<skill1>` | <一文> |
| `/<skill2>` | <一文> |

## 直近の状態（生成時点のスナップショット）

- 最新ログ ID: `<LOG-NNNN>`（あれば）
- 最終更新ファイル: `<path>` (`<yyyy-mm-dd>`)
- 進行中タスク: `<簡潔に>`

## このディレクトリで「やってはいけないこと」

- <例: PUBLIC リポへの混入禁止>
- <例: 人名の記載禁止>
- <例: 外部データソースの直接編集不可（handoff 経由）>

## 関連外部リソース

- <ドキュメント基盤・データソース等への参照リンク（あれば）>

## このファイルの保守

- `/dir-entry` を再実行すれば更新可
- ヘッダーの `generated:` 日付を見て、古ければ再生成する

4. README.md の生成または更新

既存があれば（手順 2 で抽出した保持セクションを温存しつつ）以下構造に整える。 無ければゼロから生成。

# <プロジェクト名 or ディレクトリ名>

<1〜2 行の目的説明>

> AI エージェントは `INDEX.md` を先に読んでください。

## 目的

<既存があれば保持＋必要なら補強>

## ディレクトリ構成

| パス | 中身 |
|---|---|
| `<dir>/` | <人間向けの説明> |
| ... | ... |

## クイックスタート

1. <最初にやるべきこと>
2. <2 番目>
3. <3 番目>

## 運用ルール / ここに置かないもの

<既存の禁止事項は保持＋AI 関連の標準ルールを補強>

## ステータス（<yyyy-mm-dd> 時点）

- 直近のフォーカス: <1 行>
- 直近の変更: <1 行>
- 次の節目: <1 行>

## 関連リソース

- <外部リンク>

## メンテナンス

- このファイルは `/dir-entry` スキルで更新可能
- AI エージェント向けの構造情報は `INDEX.md` に集約

5. 書き出し

• <path>/INDEX.md を新規 or 上書き
• <path>/README.md を新規 or マージ更新
• 両ファイルとも、書き出し前に最終内容をユーザーに 要約報告（差分の概要・新規追加セクション・上書きしたセクション）

6. 完了報告

• 作成/更新したファイルパス
• 主要セクションの一覧
• 次に推奨するアクション（例：「/dir-entry を 6 か月後に再実行して状態を最新化」）

制約

• 既存内容を不用意に消さない: ユーザーが意図的に書いたセクションは保持
• 重複を避ける: README.md と INDEX.md で同じことを書かない（リンクで参照）
• AI 機密境界の尊重:
  • グローバルルール（例：ホームの CLAUDE.md 等）に従う
  • 公開リポなら 人名禁止・社内固有情報禁止を README/INDEX に明示
  • PRIVATE なら逆に「ここには実情報を書いてよい」を明示
• ファイル拡張子の判定: 既に .cursorrules / AGENTS.md / CLAUDE.md 等の AI 向けファイルがある場合は、INDEX.md でそれらを「先に読むべき」として案内
• 再実行可能性: 同スキルを 1 ヶ月後に再実行しても破壊的にならない。INDEX.md の generated: 日付で更新タイミングが識別できる
• PUBLIC / PRIVATE 判定: ディレクトリのパスから判定（クラウド同期配下は基本 PRIVATE、~/Dev/ 配下の git リポは要 git remote -v 確認）

関連

• 実プロジェクト適用時は SKILL.md とは別に、各 PJ の INDEX.md README.md を実コンテンツで埋める。テンプレ通りに書くのではなく、そのディレクトリで本当に重要な情報を抽出して並べること。