{
  "markdown": "# skills\n\n自作 Agent Skill の原本を置くリポジトリ。\n\n配布されている skill は実体を持たず、[`external/manifest.toml`](external/manifest.toml) に依存として記録する。\n`package.json` と同じ考え方で、書いてあるものが「使うもの」、`install` で現実を宣言に合わせ、\n`status` で現実が宣言とずれていないかを見る。「導入予定」のような中間状態は持たない。\n[EXTERNAL.md](EXTERNAL.md) はそこから生成する読み物で、手では編集しない。\n\n管理モデルと作業手順は、OKF 形式の[運用ガイド](docs/)から辿れる。\n\n## 自作 skill\n\n| skill | 概要 |\n| --- | --- |\n| [delegate-implementation](skills/delegate-implementation/) | 開発タスクを分割し、ネイティブのサブエージェントや外部CLIへ委譲・統合する。worktreeの要否を判断し、依頼に応じてPR・CI・mergeまで扱う |\n| [dependency-pr-release-summary](skills/dependency-pr-release-summary/) | Renovate などの依存更新 PR を、リポジトリ上の差分だけでなく上流アプリケーションのリリース影響まで含めて要約する |\n| [okf](skills/okf/) | Open Knowledge Format v0.2（YAML frontmatter を持つ Markdown のナレッジバンドル）の作成・検証・利用 |\n\n## 配置\n\n原本はこのリポジトリだけに置き、各エージェントの読み取り先へは symlink を張る。\n\n```\n<repo>/skills/<name>          原本（git 管理下）\n~/.agents/skills/<name>   ->  原本                        Codex などが読む\n~/.claude/skills/<name>   ->  ../../.agents/skills/<name>  Claude Code が読む\n```\n\n`~/.agents/skills` を経由させるのは、`npx skills add -g` で入れた配布 skill と同じ流儀に揃えるため。\nこれにより `~/.claude/skills` 配下は「symlink = どこかで管理されている」「実ディレクトリ = 野良」で判別できる。\n\nなお `~/.agents/skills` 配下は、このリポジトリ由来のものが symlink、配布 skill が実ディレクトリになる。\n判別規則が成り立つのは `~/.claude/skills` 配下だけである点に注意する。\n\n## 使い方\n\n```bash\n./scripts/install.sh                  # dry-run。自作の symlink と配布の導入状況を出す\n./scripts/install.sh --apply          # 両方まとめて適用\n```\n\nサブコマンドで片方だけ扱える。\n\n```bash\n./scripts/install.sh link --apply           # 自作: symlink だけ\n./scripts/install.sh external status        # 配布: 導入状況と pin・上流の一致\n./scripts/install.sh external install --apply\n./scripts/install.sh external update --apply\n./scripts/install.sh external add <url>     # manifest に項目を足す\n./scripts/install.sh docs                   # EXTERNAL.md を生成\n./scripts/install.sh docs --check           # 生成物が manifest と食い違っていないか\n```\n\n`link` / `external install` / `external update` は `--apply` を付けない限り何も書き換えない。\n名前を渡せばその skill だけを対象にできる。\n`external add` は manifest に、`docs` は EXTERNAL.md に、それぞれ即座に書き込む。\n\n### 自作 skill（link）\n\n冪等なので、原本を編集したあとに張り直す必要はない。リンクが壊れたり張り替えられたときだけ再実行する。\n\n`skills/*/SKILL.md` があり、かつディレクトリ名と frontmatter の `name` が一致するものだけを対象にする。\nリンク先に既存の実ディレクトリがある場合、内容・ファイル種別・実行ビットが原本と完全一致するときだけ、\n`~/.skills-backup/<timestamp>/` へ退避したうえで symlink に置き換える。\n一致しなければ `CONFLICT` として差分を表示し、何もせずに終了する（終了コード 1）。\n差分を確認したうえで原本で上書きしてよければ `--force` を付ける。この場合も退避は行う。\n\n管理対象にない skill には一切触れない。\n\n### 配布 skill（external）\n\n`external/manifest.toml` の `kind` で扱いが変わる。\n\n| kind | install | update |\n| --- | --- | --- |\n| `gist` | pin した revision を取得して `~/.agents/skills/<name>/SKILL.md` に置き、`~/.claude/skills` から symlink を張る | 上流の最新 revision との差分を表示し、`--apply` で本体と manifest の pin を同時に更新する |\n| `skills-cli` | `npx skills add <repo> -g -a … --skill … -y` を呼ぶ | `npx skills update <name> -g -y` を呼び、前後の folder hash を比較する |\n\n`gist` は revision と SKILL.md の sha256 を pin するので、いつでも同じ内容を取り直せる。\n`status --offline` はネットワークに出ず、手元のファイルをこの sha256 とだけ照合する。\n\n`skills-cli` は導入と更新を CLI に任せる。ただし `~/.agents/.skill-lock.json` の\n`source` / `sourceUrl` / `skillPath` を台帳と照合するので、同名の別 skill が\n入っていれば `CONFLICT` として終了コード 1 になる。\n\nどちらの kind でも、`~/.agents/skills/<name>` の実体と `~/.claude/skills/<name>` の\nsymlink を同じ規則で確かめる。symlink が消えたり別の場所を向いていれば `--apply` で張り直す。\n\n上書きの前には `~/.skills-backup/<timestamp>/external/` へ退避する。\n\n### どこに何があるか\n\n| | 対応するもの | git |\n| --- | --- | --- |\n| `external/manifest.toml` | `package.json`（依存の宣言と pin） | 追跡する |\n| `~/.agents/skills/<name>` | `node_modules`（導入された実体） | repo の外 |\n| `~/.agents/.skill-lock.json` | `npx skills` が書く機械記録 | repo の外 |\n\nmanifest には端末固有の値を入れない。`install` も `status` も manifest を書き換えない。\n書き換えるのは、pin を進める `update --apply` と、項目を足す `add` だけで、\nどちらも人が意図して打つコマンドである。\n\nその結果 `EXTERNAL.md` は manifest だけから決まり、どの環境で生成しても同じものになる。\n\n## skill を追加する\n\n### 自作\n\n1. `skills/<name>/SKILL.md` を作る。frontmatter の `name` はディレクトリ名と一致させる\n2. `./scripts/install.sh link --apply`\n\n### 配布\n\n1. `./scripts/install.sh external add <gist または GitHub の URL>`\n   id と skill 名の重複は弾く\n2. `external/manifest.toml` の `TODO` を埋める。ライセンスは gist のコメントも確認する\n3. `./scripts/install.sh external install --apply`（gist なら sha256 もここで記録される）\n4. `./scripts/install.sh docs`\n\n使うのをやめるときは manifest から項目を消す。実体は消えないので、\n`~/.agents/skills/<name>` は自分で消すか `npx skills remove` を使う。\n\n## テスト\n\n```bash\n./tests/run.sh\n```\n\nネットワークには出ない。gist の取得先は `GIST_RAW_BASE` と `GITHUB_API_BASE` で\nローカルのフィクスチャに差し替えている。\n\n名前で絞り込める（`./tests/run.sh okf` など）。\nokf validator のテストは PyYAML があるときだけ走り、無ければ skip する。\n",
  "bytes": 4442,
  "sha": "49c85e0685d6eb7ac6985d0e3236edd32c5e643fe5b0da0272e728807ec39295",
  "repo_slug": "soli0222/skills",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/okf_soli0222_skills_docs_index_md_6483ee9a/readme"
}