ljg-push

ljg-push：推送 ljg-* 技能

将本地 ~/.agents/skills/ljg-* 中已修改的技能，一键同步到 github 仓库，覆盖 master 和 md 两个分支。

仓库路径（硬编码）

SKILLS_REPO="$HOME/code/ljg-skills"     # 本地工作 repo
SKILLS_LOCAL="$HOME/.agents/skills"      # 本地 skill 源
REPO_URL="[email protected]:lijigang/ljg-skills.git"

如果 $SKILLS_REPO 不存在，脚本会自动克隆。如果它存在但不是 ljg-skills 的 git 仓库，脚本会报错退出（不会破坏现有目录）。

两条分支的差异

分支	输出格式	文件扩展名	加粗	文件头
master（默认）	org-mode	.org	*bold*	#+title: 等
md	Markdown	.md	**bold**	YAML フロントマター

~/.agents/skills/ 内のスキルは master スタイル（ソース版）です。md ブランチとの差異は、スクリプトが自動変換し、必要に応じて手動で補います。

スクリプトは md へのプッシュ後、自動的に master に切り替えます。ローカルの $HOME/code/ljg-skills は、次回の確認とインストールに備えて、常にソースブランチに置いておく必要があります。

ワークフロー

Workflows/Push.md の手順を実行 → Tools/Push.sh を呼び出します。

README の整合性（必須ゲート）

プッシュのたびに、スクリプトは必ず README とローカルのスキルを照合 します。

• ~/.agents/skills/ljg-* にあるすべてのスキル名を列挙
• $SKILLS_REPO/README.md に記載された ljg-xxx を grep
• ローカルにはあるが README にない項目を検出——README の更新漏れである可能性が非常に高いです
• 一致した場合 → プッシュを中止し、差分を報告

プッシュのたびに README を見直す機会があります。次の点を確認してください。

1. スキルを追加しましたか？README のスキル一覧／インストールコマンドに 1 行追加する必要があります
2. スキルを削除しましたか？README の該当行を削除する必要があります
3. スキルの説明を大幅に変更しましたか？README の概要も更新が必要な場合があります

README を確認し、更新が不要であると確かめたうえで、ゲートを回避するには次のようにします。

/ljg-push --skip-readme-check

自動変換の範囲

md ブランチへの同期時に自動変換します（2026-06-12 以降は org ファイル本体も対象です）。

Org ファイル内の #+begin_example / #+end_example ブロックは text のフェンスに変換され、ブロック内のテキストを保持します。ブロック内のアスタリスクやシャープ記号が誤って見出しやコメントとして扱われることはありません。マーカーの大文字・小文字は区別されません。

• org ファイル本体：スキル内の各 .org ファイル（assets/ を除く）を同名の .md に変換し、元ファイルを削除します——org ヘッダーブロック→YAML フロントマター（--- フェンスを含む。filetags→tags）、* 見出し→# 見出し（階層を保持）、#+ATTR_* 行を削除、[[file:x]]→![](x)、#+begin_src→``` フェンス。Markdown およびランタイムテキストファイル（.ts / .js / .json / .sh など）内にある、実際に名前が変更されたファイルへの参照も同時に書き換えます
• Markdown に埋め込まれた完全な Org サンプル：```org テンプレートと、先頭行が #+key: である言語指定なしのフェンステンプレートは、いずれも ```markdown に変換されます。連続したヘッダーブロックは --- を付けた YAML フロントマターになり、見出し、リンク、強調、等幅テキスト、区切り線もテンプレートとともに変換されます。元ファイルが純粋な CRLF の場合は、その改行形式を保持します
• ファイル拡張子の参照：__qa.org → __qa.md、__paper.org → __paper.md など（denote の命名規約）
• キーワード：org-mode → markdown、Org-mode → Markdown
• org 形式の書式指示：加粗用 *bold*（单星号）… → 加粗用 **bold**（双星号）、标题层级从 * 开始 → 从 # 开始、Org 文件头 → Markdown 文件头、行頭の #+title: など 8 つのサンプルキー → YAML のキー行
• 構造化された強調ラベル：行頭の - *标签*： → - **标签**：。この種のラベルに隣接する org フェンスも同時に markdown に変更します
• 出力契約とランタイムのデフォルト値：evals/*.json で Org 形式での保存を明示的に求めるプロンプトと期待値を Markdown に変更します。stdin__*.org のデフォルト値を .md に変更しつつ、明示的な Org 入力とテストフィクスチャは保持します
• ljg-is の生成契約：出力見出し、デフォルトのファイル拡張子、パスの呼称、メタデータ名、タグ、二形式での受け入れ文をすべて Markdown/YAML + Denote に統一し、Org 専用の lint 阻止表現を削除します。コミット前の残存物監査では、変換されていない Org 出力指示をすべて拒否します

検出と同期では、同じファイル境界を使用します。チェックサムに基づいて内容を比較し、ファイルの追加、削除、内容および実行可能ビットの変更を確実に検出します。タイムスタンプのみの変更、ディレクトリのメタデータ、空ディレクトリは、単独では公開のトリガーになりません。任意の階層にある .git/、node_modules/、.DS_Store は同期対象に含めません。除外リストには、この 3 種類の明確な不要物のみが含まれます。.bak、.backup など実際のバックアップは、引き続き同期され、公開前の確認対象になります。

自動変換されないもの（必要に応じて手動で対応）：

• 本文中の *bold* マークアップ：Markdown では *x* は斜体を表すため、無差別な置換はドキュメント自体の書式を壊すおそれがあります。「行頭の箇条書き + 全角コロン」のラベルのみ安全に変換されます

音声通知

curl -s -X POST http://localhost:31337/notify \
  -H "Content-Type: application/json" \
  -d '{"message": "Running Push in ljg-push"}' \
  > /dev/null 2>&1 &

出力テキスト：Running **Push** in **ljg-push**...

例

例 1：一括プッシュ

User: /ljg-push
→ 检测 ~/.agents/skills/ljg-* 中跟 repo 有差异的 skills
→ master: rsync + bump version + commit + push
→ md: rsync + mdize + bump version + commit + push
→ 切回 master
→ 报告：哪些 skills 推了，新版本号，剩余手工差异

例 2：プッシュ内容を確認するだけで、実際にはプッシュしない

User: /ljg-push --dry-run
→ 列出会被同步的 skills
→ 列出会做的 markdown 化转换
→ 不执行 rsync / commit / push

注意点

• README の更新漏れは最も見落としやすい問題です——新しい skill を追加してすぐに push すると、README が古いリストのままになります。スクリプトにはこれを防ぐハードゲートが追加されています。止められたときに安易に --skip-readme-check を付けず、まず README を確認してください
• スクリプトの前提として git credentials の設定が必要です（ssh key または PAT）——ljg-push は認証を処理しません。認証に失敗すると、そのままエラーになります
• master を先に push する必要があります——md ブランチの Markdown 化は、master の org バージョンをもとに変換されます。逆の順序で push すると、順序が崩れます
• untracked の不要ファイル（例：assets/measure.js）は rsync で repo に同期されます——push したくない場合は、先にローカルで削除するか、.gitignore に追加してください
• 同期の除外項目は、範囲を絞り、一貫性を保つ必要があります——.git/、node_modules/、.DS_Store は同期されません。タイムスタンプのみのファイル、ディレクトリのメタデータ、空ディレクトリは、それだけで公開のきっかけになることはなく、Git の結果にも含まれません。通常のバックアップファイルは除外リストに含まれず、検出されます。公開される可能性のある実際の内容を隠さないためです
• org ファイル本体は自動変換されます（2026-06-12 以降）——template.org などは .md に変換され、元ファイルは削除されます。push のたびに再生成されます（rsync --delete で消えても問題ありません。冪等です）。手作業で残っている項目は、本文中の *bold* マーカーのみです。複雑な構成要素を含む org reference ファイルを追加した場合は、先に --dry-run を使うか、サンドボックスで mdize を実行して変換結果を確認してください
• 参照の名前変更は実行時コードに隠れていることがあります——たとえば、テストで new URL("../Template.org", import.meta.url) を使ってテンプレートを読み込んでいる場合、Markdown ドキュメントだけ変更すると、md ブランチにファイルがなくなります。変換器は今回実際に変換された basename に基づき、.ts／.js／.json／.sh などのテキストの読み込み元を正確に書き換えます。同時に、対応する実ファイルがない Org テストフィクスチャの文字列は保持します
• 構造化タグは例示語の列挙では対応できません——x、f(x) だけでなく、「主体／境界」「代入」などの実際のタグも使われます。変換器は - *タグ*： という構造で識別します。公開後も、md ファイルに単一アスタリスクのタグが残っていないかスキャンしてください
• Markdown 変換で小文字の org だけに一致させてはいけません——skill の本文では Org やインラインの #+description がよく使われ、Org テンプレートの # コメント も Markdown では見出しになります。変換器はこれらの形式をまとめて処理し、md commit 前に出力指示、Org マーカー、残存する .org ファイルをスキャンします
• 文書全体のテンプレートは、フェンスのラベルを変えるだけでは不十分です——```org や言語指定のないフェンス内の #+title、アスタリスク付き見出し、Org リンクは、一つの意味単位として変換する必要があります。変換器は --- を使った YAML、Markdown 見出し、リンクを生成し、元ファイルの CRLF／LF の改行形式も維持して、意味のないファイル全体の diff を避けます
• 出力形式の残存は、動詞句だけをスキャンしても不十分です——「Org ファイルを書くときに」を変換しても、同じ段落の「生成されるすべての Org ファイル」が残り、md ブランチで引き続き Org の生成を要求することがあります。変換器と commit 前の監査では、このような保存先を示す文も対象にする必要があります。そうしないと、push が成功しても古い形式の契約がリモートに持ち戻されます
• 出力契約は Markdown ドキュメントだけにあるとは限りません——evals/*.json の prompt／expected_output は、skill に特定の形式で生成するよう直接要求することがあります。また、実行時コードの stdin__*.org がデフォルトのパーサーを選択する場合もあります。mdize と commit 前の監査では、これら2種類の利用元も対象にしつつ、Org 入力の互換性を明示的にテストするケースは維持してください
• 相互排他的な形式指定の文は、形式名だけを置換してはいけません——「ソース形式を必ず使う」と「ターゲット形式を禁止する」を同時に示す文では、単語単位で置換すると、肯定する形式と禁止する形式が一致してしまいます。mdize は文全体でターゲット形式と除外対象を入れ替える必要があります。また、残存チェックでは両者が同じ文を拒否する必要があります
• 形式名が変わっても、構文規則まで変わるとは限りません——org-mode が markdown に置き換わっても、単一アスタリスクによる太字、~code~、「バッククォートを使わない」という指示が残っていれば、モデルは Org を出力するよう指示されます。変換器は、この相互排他的な規則一式を Markdown の規則にまとめて置き換える必要があります。監査でも、旧規則をブロッカーとして扱ってください
• スクリプトは plugin.json と marketplace.json の patch version を自動で bump します——minor／major を bump したい場合は、先に手動で変更してからスクリプトを実行してください。スクリプトが追加するのは patch のみです
• md ブランチのリモートがローカルより新しい場合（別のマシンから push された場合）、スクリプトは pull --rebase の失敗後に一度だけ reset --hard origin/md を試してから再適用します。これにより、ローカルにあって未 push の md ブランチの commit は破棄されます。スクリプトの実行前に警告が表示されます
• 現在のパス：skill のソースは ~/.agents/skills/ に固定され、作業用 repo は ~/code/ljg-skills/ に固定されています。過去のバックアップディレクトリから読み込んだり、そこから push したりしないでください