substack-skill 設計書

Appearance

スキル配置・配布方針 ​

最終更新: 2026-05-15 関連: #28 (A-2), DESIGN.md §9

0. TL;DR ​

  • 開発リポジトリ: github.com:aieo-product/substackTools.git（GitHub Private）
  • ローカル開発作業ツリー: /Volumes/AIWorkSSD/AIWorkSpace/github/aieo-product/substackTools/
  • アクティブskill位置: /Volumes/AIWorkSSD/AIWorkSpace/Skills/substack-skill/ から作業ツリーへの symlink
  • Claude Code 統合: ~/.claude/commands/ と ~/.claude/skills/ へ symlink（install.sh が実施）
  • claude-skills-marketplace への登録: Phase 1 では行わない（substackTools は private、個人用途のため）。M6 段階で再評価

1. 既存スキル配置の調査結果 ​

1.1 候補ディレクトリ比較 ​

ディレクトリ状態役割
/Users/takehiro/Documents/WorkSpace/otani/Skills/非アクティブ — SKILL.md は 0 バイト placeholder のみ古い置き場、現在は事実上使われていない
/Volumes/AIWorkSSD/AIWorkSpace/Skills/アクティブ — 各 skill が独自 .git を持つ実運用中の skills 置き場
/Volumes/AIWorkSSD/AIWorkSpace/Skills/claude-skills-marketplace/plugins/配布 — .claude-plugin/plugin.json 付きパッケージ内部マーケットプレイス（gitlab.ethan-tech.jp）経由配布用

1.2 既存スキルのパターン ​

  • dev-workflow, create-blog, agent-browser など多くは:
    • 開発repo（gitlab / GitHub）↔ /Volumes/AIWorkSSD/AIWorkSpace/Skills/<name>/ に git clone
    • 公開する場合: claude-skills-marketplace/plugins/<name>/ にビルド済みパッケージ（.claude-plugin/plugin.json、node_modules 除外、git履歴 除外）

1.3 substack-skill 固有の事情 ​

  • substackTools は GitHub Private（社外公開しない）
  • 個人運用かつ自分の Substack アカウントに紐付くスキル
  • 将来的に aieo-product 組織メンバーには共有する可能性あり
  • 既存マーケットプレイス（gitlab.ethan-tech.jp / 社内向け）の対象範囲とは異なる

2. 採用する配置 ​

2.1 リポジトリと作業ツリー ​

種別パス
上流リポジトリgit@github.com:aieo-product/substackTools.git
ローカルクローン（開発作業）/Volumes/AIWorkSSD/AIWorkSpace/github/aieo-product/substackTools/

GitHubクローン先パスは既存パターン（/Volumes/AIWorkSSD/AIWorkSpace/github/<org>/<repo>/）を踏襲。

2.2 アクティブskill位置 ​

/Volumes/AIWorkSSD/AIWorkSpace/Skills/substack-skill
    → symlink → /Volumes/AIWorkSSD/AIWorkSpace/github/aieo-product/substackTools

理由:

  • 開発したコードが即時にスキルとして反映される（コピーや再ビルド不要）
  • 単一の正本（source-of-truth）。Skills/substack-skill/ 配下に別 .git を作ると同期事故が起きる
  • 既存 dev-workflow 等は clone モデルだが、本スキルは開発と利用が同一マシン・同一ユーザーのため symlink で十分

2.3 Claude Code への統合 ​

scripts/install.sh が以下を実施:

  1. アクティブskill位置の symlink を作成（既存があれば force update）
  2. slash commands の登録:
    • commands/*.md を ~/.claude/commands/ へ symlink
  3. SKILL.md の登録:
    • ~/.claude/skills/substack-skill を作業ツリーへ symlink
  4. CLAUDE.md の更新:
    • /Volumes/AIWorkSSD/CLAUDE.md のスキル一覧テーブルに行を追加（既存なら skip）

2.4 Marketplace への登録（将来） ​

Phase 1 では行わない。判断保留の根拠:

  • substackTools は GitHub Private、claude-skills-marketplace は社内向け
  • 個人運用用途で、社内共有の有無は M6 までに判断
  • 後から marketplace に登録する場合の手順:
    1. aieo-product/substackTools の public 化 or 社内 gitlab に mirror
    2. claude-skills-marketplace/plugins/substack-skill/.claude-plugin/plugin.json 作成
    3. CONTRIBUTING.md の手順に従って PR

3. アンインストール ​

scripts/uninstall.sh:

  • ~/.claude/commands/substack-*.md symlinks を削除
  • ~/.claude/skills/substack-skill symlink を削除
  • /Volumes/AIWorkSSD/AIWorkSpace/Skills/substack-skill symlink を削除
  • /Volumes/AIWorkSSD/CLAUDE.md の該当行を削除
  • 作業ツリー本体・Keychain値・~/.cache/substack-skill/ には触らない（ユーザー判断）

4. DESIGN.md §9 への反映 ​

DESIGN.md §9（配置・配布）の記述は本書（PLACEMENT.md）に詳細化された。 DESIGN.md は次回改訂時に「詳細は PLACEMENT.md 参照」の1行に縮約する（軽微改訂）。

5. 残課題 ​

  • scripts/install.sh / scripts/uninstall.sh の実装 → F-5 (#58)
  • ~/.claude/skills/ の Claude Code 仕様確認（skill loader の挙動）→ F-3 (#56) の冒頭で実施
  • 複数マシン展開（dotfiles と組み合わせる）→ M6 以降に検討

substack-skill 内部設計書 — 公開非対象

© 2026 aieo-product