Skill sebagai konteks: rumahnya, versinya, dan cara ia hadir di Sandbox

Part of #131

Question

Premis mengunci skill dipakai apa adanya: /wayfinder, /grilling, /prototype, /research berjalan di dalam Sandbox seperti ia berjalan di terminal hari ini. Yang belum diputuskan: skill itu tinggal di mana, versinya bagaimana, dan bagaimana ia sampai ke Sandbox.

Hari ini skill hidup di ~/.claude-lexicon/skills/ — direktori pribadi di mesin seseorang, di luar repo mana pun, tidak ter-versi bersama pekerjaan yang ia hasilkan.

1. Rumahnya di mana — repo skill tersendiri milik org (bisa dibaca seperti knowledge repo), direktori di dalam repo kerja (.claude/skills/, sudah ada di repo ini dan di repo product), atau keduanya dengan aturan penggabungan. Repo ini sudah memuat .claude/skills/ dan .claude/commands/, jadi bentuk kedua bukan hipotesis.
2. Snapshot atau segar — Run menyimpan salinan penuh definisi dan isi berkas prompt supaya tetap terbaca meski aslinya berubah. Skill adalah instruksi yang menentukan perilaku agent sama kuatnya dengan prompt. Kalau ia tidak ikut di-snapshot, dua Run dengan definisi identik bisa berperilaku berbeda tanpa jejak.
3. Bagaimana ia hadir di Sandbox — ikut checkout (kalau ia di repo kerja), disalin masuk Runner, atau ditulis ke lokasi yang dibaca alat (~/.claude/skills/ dan padanannya). Tiap alat punya konvensi sendiri, dan premis netralitas alat berlaku di sini juga.
4. Skill mana yang boleh — apakah Step menyebut skill yang ia butuh, atau seluruh direktori selalu hadir. Menyebutnya membuat prompt final terbaca dan permukaannya sempit; selalu hadir lebih sederhana tapi membuat "apa yang mengarahkan agent" tidak terbaca di definisi.
5. Siapa yang boleh menyunting skill — ia menentukan perilaku agent yang memegang token repo. Skill yang bisa disunting siapa saja adalah jalur eskalasi yang lebih halus dari prompt injection: ia permanen dan terlihat sah.

Fakta dari riset (#138, sudah tertutup)

Diuji dengan menjalankan, bukan dibaca: Claude Code 2.1.232 (8 run), OpenCode 1.18.15, Codex 0.147.0 (end-to-end gagal karena akun, bentuk perintah tetap terbaca), pi tidak terpasang.

• Skill bekerja non-interaktif — /grilling, /prototype, /research jalan apa adanya dalam bentuk perintah yang sandcastle kirim. Premis peta ini selamat.
• Kecuali /wayfinder, dan sebabnya satu karakter. Sandcastle memanggil claude … -p - (dist/index.js:3431), dan literal - itu ikut jadi teks prompt (transcript menyimpan "-\n/nonce-plain"). Garis miring bukan karakter pertama ⇒ ekspansi slash sisi-klien mati, dan yang tersisa hanya jalur "model memanggil Skill tool" — yang tertutup untuk skill ber-disable-model-invocation: true. /wayfinder satu-satunya di set ini yang memakainya. Keempat bentuk alternatif (-p telanjang, argv, tanpa -p) diuji dan /wayfinder langsung jalan.
  Keputusan yang lahir dari ini: perbaikannya ada di dalam sandcastle, di luar seam startTurn(spec), jadi ia menuntut pnpm patch — katup yang ticket 12 siapkan, lengkap dengan peringatannya bahwa patch yang membengkak adalah pemicu meninjau ulang keputusan dependency-vs-fork. Alternatifnya: larang skill ber-disable-model-invocation dipakai di dalam factory, dan itu berarti /wayfinder harus diubah, bukan sandcastle.
• Skill punya ketergantungan ke skill lain, dan gagalnya senyap. wayfinder/SKILL.md menyuruh membaca setup-matt-pocock-skills/issue-tracker-github.md. Tanpa berkas itu hadir di Sandbox, /wayfinder diam-diam jatuh ke tracker local-markdown — menghasilkan berkas, bukan issue. Jadi sub-pertanyaan 4 tiket ini ("skill mana yang boleh") tidak bisa dijawab per-skill: yang hadir harus satu himpunan yang tertutup terhadap ketergantungannya.
• "Dipakai apa adanya" benar di tingkat berkas, tidak di tingkat perilaku. OpenCode mengabaikan disable-model-invocation dan membaca .claude/skills/ project apa adanya. Jadi dua alat yang diberi direktori yang sama bisa berperilaku berbeda — dan premis netralitas alat tidak menutupi selisih itu.

Opsi ketiga: factory yang merender skill ke prompt

Riset menyisakan dikotomi patch sandcastle vs ubah skill, dan keduanya memperbaiki satu alat sambil membiarkan selisih antar-alat tetap ada. Opsi ketiga menghapus pertanyaannya alih-alih menjawabnya:

Runner membaca SKILL.md dan menempelkannya ke prompt, sementara berkas pendukung skill hadir di disk Sandbox supaya rujukan di dalamnya tetap terbaca agent — termasuk ketergantungan lintas-skill yang riset temukan (wayfinder/SKILL.md → setup-matt-pocock-skills/issue-tracker-github.md), yang tanpa kehadirannya jatuh senyap ke tracker markdown lokal.

Yang ia beli:

• Nol patch, nol perubahan skill. Katup pnpm patch ticket 12 tidak dipakai untuk ini, dan skill milik orang lain tidak perlu di-fork.
• Netralitas alat berhenti bergantung pada loader tiap alat — dan itu penting karena premisnya sudah terbukti bocor: OpenCode mengabaikan disable-model-invocation, Claude Code bergantung pada bentuk argumen, dan pi belum terverifikasi punya mekanismenya sama sekali.
• Reproduksibilitas jatuh gratis: prompt sudah di-snapshot ke runs.definition_files, jadi Run lama tetap terbaca walau skill-nya berubah. Ini menjawab sub-pertanyaan 2 tiket ini tanpa mekanisme baru.
• Pemanggilannya pasti, bukan keputusan model — berbeda dari opsi "cabut disable-model-invocation", yang menukar alur kerja yang ditentukan dengan alur kerja yang mungkin dipanggil.

Harganya, dinyatakan di muka:

• Progressive disclosure hilang untuk SKILL.md itu sendiri — ia selalu masuk penuh dan dibayar token walau sebagian tidak terpakai. Berkas rujukannya tetap lazy karena agent yang memilih membacanya.
• Opsi ini tidak menghapus kebutuhan berkas skill hadir di Sandbox; ia hanya menghapus ketergantungan pada loader alat. Sub-pertanyaan 1, 3, dan 5 tiket ini tetap harus dijawab.
• Kalau sebuah skill mengandalkan perilaku khusus loader (frontmatter yang ditafsirkan alat, argumen $ARGUMENTS, atau nama perintah), perilaku itu hilang dan harus digantikan oleh bentuk prompt yang kita tulis sendiri.

Start with the documented findings in #138, especially dist/index.js:3431, the .claude/skills/ layout, and runs.definition_files. Compare the listed skill-loading options and dependencies, then define the chosen storage, snapshot, Sandbox delivery, allowed-skill, and editing rules; done means the policy and its implementation boundaries are recorded.