Frontmatter Kemahiran

context: fork menjalankan kemahiran dalam konteks terpencil yang bercabang daripada titik dikongsi, kemudian hanya mengembalikan hasil kepada perbualan utama. Output terperinci dan perantaraan kekal dalam cabang tersebut dan tidak pernah mencemarkan tetingkap utama anda.

Ini ialah prinsip pengasingan yang sama di sebalik ejen bawahan Explore: kerja penemuan menghasilkan banyak gangguan, jadi anda mengasingkannya dan mengembalikan ringkasan yang bersih. Kemahiran menjadikan corak itu bersifat deklaratif — satu baris frontmatter.

Ruang konteks tidak terhingga, dan model memberi lebih perhatian kepada permulaan dan pengakhiran konteks yang panjang berbanding bahagian tengah ("kehilangan di tengah"). Kemahiran yang mencari dalam ratusan fail atau mencurahkan log binaan yang panjang ke dalam sesi utama boleh menolak tugas sebenar anda ke zon tengah yang lemah itu.

context: fork mengekalkan kandungan besar tersebut di luar sesi utama. Anda mengekalkan perhatian untuk perkara yang penting dan mengelakkan pembaziran token pada celoteh alat sementara yang tidak akan dirujuk lagi.

Buat cabang apabila kemahiran menghasilkan output berlebihan yang tidak perlu disimpan: imbasan kebergantungan, analisis log, penerokaan pangkalan kod secara menyeluruh, atau pelaksanaan rangkaian ujian.

Jangan buat cabang apabila keseluruhan output kemahiran itu ialah hasil yang ingin anda kekalkan sebaris dalam perbualan utama — contohnya pemfaktoran semula ringkas bagi satu fail yang bakal anda bincangkan. Membuat cabang dalam keadaan ini hanya menambah satu pusingan pergi balik dan menyembunyikan butiran yang sebenarnya anda perlukan.

• Buat cabang: penemuan yang bising, kemudian pulangkan ringkasan.
• Jangan buat cabang: suntingan kecil dan terarah yang akan terus anda gunakan.

allowed-tools mengehadkan kemahiran kepada set alat yang dinamakan. Ini ialah prinsip keistimewaan minimum yang diterapkan pada aliran kerja: kemahiran audit baca sahaja tidak sepatutnya mempunyai Write atau Edit.

Konsep ini mencerminkan cara anda mengehadkan skop allowed_tools ejen mengikut peranannya. Akses alat yang terhad mengurangkan kesan kerosakan dan turut mempertajam pemilihan — alat yang lebih sedikit dan skopnya jelas dipilih dengan lebih konsisten berbanding himpunan alat yang besar dan bercampur-campur.

Nyatakan dengan tepat perkara yang dijamin oleh allowed-tools. Ia mengehadkan menu alat yang boleh dipilih oleh kemahiran — sempadan keupayaan yang berguna dan ditentukan secara pasti.

Namun, ia bukan pengganti cangkuk apabila peraturan perniagaan mesti dipatuhi dengan pasti. Jika "jangan sekali-kali pulangkan wang melebihi $500" atau "jangan sekali-kali hantar ke main" melibatkan kepentingan kewangan, undang-undang, atau keselamatan, kuatkuasakan peraturan itu dengan cangkuk yang ditentukan secara pasti (contohnya PostToolUse atau penyekatan panggilan keluar), bukannya dengan berharap gesaan dan senarai alat kemahiran akan berfungsi seperti yang dikehendaki. Gesaan bersifat ~90% kebarangkalian; cangkuk pula 100%.

argument-hint menerangkan argumen yang dijangka oleh kemahiran. Ia memaparkan cara penggunaan kepada pemanggil dan mendokumentasikan tujuan — konvensyen tanda kurung sudut dan tanda kurung siku menandakan parameter wajib berbanding pilihan.

Di dalam badan, argumen tersebut tiba melalui $ARGUMENTS (atau $1, $2 mengikut kedudukan). Petunjuk ini adalah untuk manusia dan alat; ia tidak menghuraikan atau mengesahkan input — badan kemahiran anda menentukan cara mentafsir input tersebut.

Petunjuk yang baik mengikut disiplin yang sama seperti penerangan alat yang baik: nyatakan format input, tunjukkan bentuk yang dijangka, dan tandakan bahagian yang pilihan.

• Gunakan <required> untuk argumen wajib.
• Gunakan [optional] untuk bendera dan tambahan.
• Susun argumen mengikut kedudukan berdasarkan urutan badan membacanya.

Petunjuk yang kabur menyebabkan penggunaan yang salah, sama seperti penerangan alat yang kabur menyebabkan penghalaan yang salah — kejelasan pada sempadan menghalang ralat pada langkah seterusnya.

Kunci-kunci ini bergabung menjadi satu kontrak yang koheren. Kemahiran yang dibentuk dengan baik menyatakan: inilah perkara yang saya terima (argument-hint), inilah perkara yang dibenarkan untuk saya sentuh (allowed-tools), dan inilah cara saya memastikan sesi anda kekal kemas (context: fork).

Jika dibaca bersama, bahagian hadapan membolehkan rakan sepasukan memahami tingkah laku dan sempadan keselamatan kemahiran tanpa membaca badannya — tepat seperti yang sepatutnya disediakan oleh konfigurasi dikongsi yang dikawal versinya.

Lokasi fail kemahiran menentukan siapa yang mendapatkannya. Kemahiran dalam .claude/skills/ projek diserahkan kepada VCS dan dikongsi dengan seluruh pasukan. Kemahiran di bawah ~/.claude/skills/ adalah peribadi — rakan sepasukan baharu yang mengklon repositori tidak akan dapat melihatnya.

Ini ialah pertukaran yang sama seperti CLAUDE.md peringkat pengguna berbanding peringkat projek. Jika kemahiran mengekodkan piawaian pasukan, serahkannya kepada skop projek supaya kontrak itu bergerak bersama kod.

Bahagian hadapan kemahiran ialah kontrak keselamatan dan kejelasan yang padat, dibina daripada tiga kunci:

• context: fork — mengasingkan output berlebihan, memulangkan ringkasan yang kemas, dan melindungi tetingkap konteks utama daripada kehilangan maklumat di bahagian tengah.
• allowed-tools — sempadan keupayaan berkeistimewaan minimum; mengehadkan menu alat tetapi TIDAK menguatkuasakan peraturan perniagaan — gunakan cangkuk yang ditentukan secara pasti untuk dasar yang melibatkan kepentingan kewangan, undang-undang atau keselamatan.
• argument-hint — mendokumentasikan input yang dijangka (<required> berbanding [optional]); seperti penerangan alat yang baik, kejelasan di sini menghalang penggunaan yang salah. Ia tidak mengesahkan input.

Serahkan kemahiran pasukan ke .claude/skills/ projek supaya kontrak dihantar bersama kod; simpan kemahiran peribadi di ~/.claude/.