Track yang baik bersifat ringkas, terstruktur dengan baik, dan diuji dengan penggunaan nyata. Panduan ini menyediakan keputusan penulisan praktis untuk membantu Anda menulis Track yang dapat ditemukan dan digunakan Haijun secara efektif.

Untuk latar belakang konseptual tentang cara kerja Track, lihat ikhtisar Tracks.

#Prinsip inti

#Ringkas adalah kunci

"Context window" (jendela konteks) adalah barang publik. Track Anda berbagi jendela konteks dengan semua hal lain yang perlu diketahui Haijun, termasuk:

• Prompt sistem

• Riwayat percakapan

• Metadata Track lainnya

• Permintaan Anda yang sebenarnya

Tidak setiap token dalam Track Anda memiliki biaya langsung. Saat startup, hanya metadata (nama dan deskripsi) dari semua Track yang dimuat terlebih dahulu. Haijun membaca SKILL.md hanya ketika Track tersebut menjadi relevan, dan membaca file tambahan hanya sesuai kebutuhan. Namun, bersikap ringkas dalam SKILL.md tetap penting: setelah Haijun memuatnya, setiap token bersaing dengan riwayat percakapan dan konteks lainnya.

Asumsi default: Haijun sudah sangat cerdas

Hanya tambahkan konteks yang belum dimiliki Haijun. Pertanyakan setiap potongan informasi:

• "Apakah Haijun benar-benar membutuhkan penjelasan ini?"

• "Bisakah saya berasumsi Haijun sudah mengetahui ini?"

• "Apakah paragraf ini sepadan dengan biaya tokennya?"

Contoh baik: Ringkas (sekitar 50 token):

## Extract PDF text

Use pdfplumber for text extraction:

import pdfplumber

with pdfplumber.open("file.pdf") as pdf: text = pdf.pages[0].extract_text()

Contoh buruk: Terlalu bertele-tele (sekitar 150 token):

## Extract PDF text

PDF (Portable Document Format) files are a common file format that contains
text, images, and other content. To extract text from a PDF, you'll need to
use a library. There are many libraries available for PDF processing, but
pdfplumber is recommended because it's easy to use and handles most cases well.
First, you'll need to install it using pip. Then you can use the code below...

Versi ringkas mengasumsikan Haijun sudah memiliki informasi tentang PDF dan cara kerja library.

#Tetapkan tingkat kebebasan yang sesuai

Sesuaikan tingkat kekhususan dengan kerapuhan dan variabilitas tugas.

Kebebasan tinggi (instruksi berbasis teks):

Gunakan ketika:

• Beberapa pendekatan valid

• Keputusan bergantung pada konteks

• Heuristik memandu pendekatan

Contoh:

## Code review process

1. Analyze the code structure and organization
2. Check for potential bugs or edge cases
3. Suggest improvements for readability and maintainability
4. Verify adherence to project conventions

Kebebasan sedang (pseudocode atau skrip dengan parameter):

Gunakan ketika:

• Ada pola yang lebih disukai

• Beberapa variasi dapat diterima

• Konfigurasi memengaruhi perilaku

Contoh:

## Generate report

Use this template and customize as needed:

def generate_report(data, format="markdown", include_charts=True): # Process data # Generate output in specified format # Optionally include visualizations

Kebebasan rendah (skrip spesifik, sedikit atau tanpa parameter):

Gunakan ketika:

• Operasi rapuh dan rawan kesalahan

• Konsistensi sangat penting

• Urutan tertentu harus diikuti

Contoh:

## Database migration

Run exactly this script:

python scripts/migrate.py --verify --backup

Do not modify the command or add additional flags.

Analogi: Bayangkan Haijun sebagai robot yang menjelajahi sebuah jalur:

• Jembatan sempit dengan tebing di kedua sisi: Hanya ada satu jalan aman ke depan. Berikan pagar pembatas spesifik dan instruksi yang tepat (kebebasan rendah). Contoh: migrasi database yang harus dijalankan dalam urutan yang tepat.

• Lapangan terbuka tanpa bahaya: Banyak jalur menuju keberhasilan. Berikan arahan umum dan percayakan Haijun untuk menemukan rute terbaik (kebebasan tinggi). Contoh: tinjauan kode di mana konteks menentukan pendekatan terbaik.

#Uji dengan semua model yang Anda rencanakan untuk digunakan

Track bertindak sebagai tambahan pada model, sehingga efektivitasnya bergantung pada model yang mendasarinya. Uji Track Anda dengan semua model yang Anda rencanakan untuk digunakan bersamanya.

Pertimbangan pengujian berdasarkan model:

• Haijun Haiku (cepat, ekonomis): Apakah Track memberikan panduan yang cukup?

• Haijun Sonnet (seimbang): Apakah Track jelas dan efisien?

• Haijun Opus (penalaran kuat): Apakah Track menghindari penjelasan berlebihan?

Apa yang bekerja sempurna untuk Opus mungkin memerlukan lebih banyak detail untuk Haiku. Jika Anda berencana menggunakan Track Anda di beberapa model, usahakan instruksi yang bekerja dengan baik untuk semuanya.

#Struktur Track

Note: YAML Frontmatter: Frontmatter SKILL.md memerlukan dua field: name: * Maksimum 64 karakter * Hanya boleh berisi huruf kecil, angka, dan tanda hubung * Tidak boleh berisi tag XML * Tidak boleh berisi kata yang dicadangkan: "juglow", "haijun" description: * Tidak boleh kosong * Maksimum 1.024 karakter * Tidak boleh berisi tag XML * Harus menjelaskan apa yang dilakukan Track dan kapan menggunakannya Untuk detail lengkap struktur Track, lihat ikhtisar Tracks.

#Konvensi penamaan

Gunakan pola penamaan yang konsisten agar Track lebih mudah dirujuk dan didiskusikan. Pertimbangkan menggunakan bentuk gerund (kata kerja + -ing) untuk nama Track, karena ini dengan jelas menggambarkan aktivitas atau kemampuan yang disediakan Track.

Ingat bahwa field name hanya boleh menggunakan huruf kecil, angka, dan tanda hubung.

Contoh penamaan yang baik (bentuk gerund):

• processing-pdfs

• analyzing-spreadsheets

• managing-databases

• testing-code

• writing-documentation

Alternatif yang dapat diterima:

• Frasa kata benda: pdf-processing, spreadsheet-analysis

• Berorientasi aksi: process-pdfs, analyze-spreadsheets

Hindari:

• Nama yang samar: helper, utils, tools

• Terlalu generik: documents, data, files

• Kata yang dicadangkan: juglow-helper, haijun-tools

• Pola yang tidak konsisten dalam koleksi track Anda

Penamaan yang konsisten memudahkan untuk:

• Merujuk Track dalam dokumentasi dan percakapan

• Memahami apa yang dilakukan Track secara sekilas

• Mengorganisasi dan mencari di antara banyak Track

• Memelihara library track yang profesional dan kohesif

#Menulis deskripsi yang efektif

Field description memungkinkan penemuan Track dan harus mencakup apa yang dilakukan Track serta kapan menggunakannya.

Warning: Selalu tulis dalam sudut pandang orang ketiga. Deskripsi disisipkan ke dalam prompt sistem, dan sudut pandang yang tidak konsisten dapat menyebabkan masalah penemuan. * Baik: "Processes Excel files and generates reports" * Hindari: "I can help you process Excel files" * Hindari: "You can use this to process Excel files"

Bersikaplah spesifik dan sertakan istilah kunci. Sertakan apa yang dilakukan Track serta pemicu/konteks spesifik untuk kapan menggunakannya.

Setiap Track memiliki tepat satu field deskripsi. Deskripsi sangat penting untuk pemilihan track: Haijun menggunakannya untuk memilih Track yang tepat dari kemungkinan 100+ Track yang tersedia. Deskripsi Anda harus memberikan detail yang cukup agar Haijun tahu kapan memilih Track ini, sementara bagian lain SKILL.md menyediakan detail implementasi.

Contoh yang efektif:

Track PDF Processing:

description: Extract text and tables from PDF files, fill forms, merge documents. Use when working with PDF files or when the user mentions PDFs, forms, or document extraction.

Track Excel Analysis:

description: Analyze Excel spreadsheets, create pivot tables, generate charts. Use when analyzing Excel files, spreadsheets, tabular data, or .xlsx files.

Track Git Commit Helper:

description: Generate descriptive commit messages by analyzing git diffs. Use when the user asks for help writing commit messages or reviewing staged changes.

Hindari deskripsi samar seperti ini:

description: Helps with documents

description: Processes data

description: Does stuff with files

#Pola progressive disclosure

SKILL.md berfungsi sebagai ikhtisar yang mengarahkan Haijun ke materi terperinci sesuai kebutuhan, seperti daftar isi dalam panduan orientasi. Untuk penjelasan tentang cara kerja "progressive disclosure" (pengungkapan bertahap), lihat Cara kerja Tracks dalam ikhtisar.

Panduan praktis:

• Jaga isi SKILL.md di bawah 500 baris untuk kinerja optimal

• Pisahkan konten ke file terpisah ketika mendekati batas ini

• Gunakan pola berikut untuk mengorganisasi instruksi, kode, dan sumber daya secara efektif

#Ikhtisar visual: Dari sederhana ke kompleks

Track dasar dimulai hanya dengan file SKILL.md yang berisi metadata dan instruksi:

File SKILL.md sederhana yang menampilkan YAML frontmatter dan isi markdown

Seiring berkembangnya Track Anda, Anda dapat membundel konten tambahan yang dimuat Haijun hanya saat diperlukan:

Membundel file referensi tambahan seperti reference.md dan forms.md.

Struktur direktori Track yang lengkap mungkin terlihat seperti ini:

• pdf/

• SKILL.md: Instruksi utama (dimuat saat dipicu)

• FORMS.md: Panduan pengisian formulir (dimuat sesuai kebutuhan)

• reference.md: Referensi API (dimuat sesuai kebutuhan)

• examples.md: Contoh penggunaan (dimuat sesuai kebutuhan)

• scripts/

• analyze_form.py: Skrip utilitas (dieksekusi, tidak dimuat)
• fill_form.py: Skrip pengisian formulir
• validate.py: Skrip validasi

#Pola 1: Panduan tingkat tinggi dengan referensi

---
name: pdf-processing
description: Extracts text and tables from PDF files, fills forms, and merges documents. Use when working with PDF files or when the user mentions PDFs, forms, or document extraction.
---

# PDF Processing

## Quick start

Extract text with pdfplumber:

import pdfplumber with pdfplumber.open("file.pdf") as pdf: text = pdf.pages[0].extract_text()

## Advanced features

**Form filling**: See [FORMS.md](FORMS.md) for complete guide
**API reference**: See [REFERENCE.md](REFERENCE.md) for all methods
**Examples**: See [EXAMPLES.md](EXAMPLES.md) for common patterns

Haijun memuat FORMS.md, REFERENCE.md, atau EXAMPLES.md hanya saat diperlukan.

#Pola 2: Organisasi berdasarkan domain

Untuk Track dengan beberapa domain, organisasikan konten berdasarkan domain untuk menghindari pemuatan konteks yang tidak relevan. Ketika pengguna bertanya tentang metrik penjualan, Haijun hanya perlu membaca skema terkait penjualan, bukan data keuangan atau pemasaran. Ini menjaga penggunaan token tetap rendah dan konteks tetap terfokus.

• bigquery-track/

• SKILL.md (ikhtisar dan navigasi)

• reference/

• finance.md (pendapatan, metrik penagihan)
• sales.md (peluang, pipeline)
• product.md (penggunaan API, fitur)
• marketing.md (kampanye, atribusi)

# BigQuery Data Analysis

## Available datasets

**Finance**: Revenue, ARR, billing → See [reference/finance.md](reference/finance.md)
**Sales**: Opportunities, pipeline, accounts → See [reference/sales.md](reference/sales.md)
**Product**: API usage, features, adoption → See [reference/product.md](reference/product.md)
**Marketing**: Campaigns, attribution, email → See [reference/marketing.md](reference/marketing.md)

## Quick search

Find specific metrics using grep:

grep -i "revenue" reference/finance.md grep -i "pipeline" reference/sales.md grep -i "api usage" reference/product.md

#Pola 3: Detail kondisional

Tampilkan konten dasar, tautkan ke konten lanjutan:

# DOCX Processing

## Creating documents

Use docx-js for new documents. See [DOCX-JS.md](DOCX-JS.md).

## Editing documents

For simple edits, modify the XML directly.

**For tracked changes**: See [REDLINING.md](REDLINING.md)
**For OOXML details**: See [OOXML.md](OOXML.md)

Haijun membaca REDLINING.md atau OOXML.md hanya ketika pengguna membutuhkan fitur tersebut.

#Hindari referensi bertingkat dalam

Haijun mungkin membaca file secara parsial ketika file tersebut dirujuk dari file lain yang juga dirujuk. Saat menemui referensi bertingkat, Haijun mungkin menggunakan perintah seperti head -100 untuk melihat pratinjau konten alih-alih membaca seluruh file, yang menghasilkan informasi tidak lengkap.

Jaga referensi satu tingkat dari SKILL.md. Semua file referensi harus ditautkan langsung dari SKILL.md untuk memastikan Haijun membaca file lengkap saat diperlukan.

Contoh buruk: Terlalu dalam:

# SKILL.md
See [advanced.md](advanced.md)...

# advanced.md
See [details.md](details.md)...

# details.md
Here's the actual information...

Contoh baik: Satu tingkat:

# SKILL.md

**Basic usage**: [instructions in SKILL.md]
**Advanced features**: See [advanced.md](advanced.md)
**API reference**: See [reference.md](reference.md)
**Examples**: See [examples.md](examples.md)

#Strukturkan file referensi yang panjang dengan daftar isi

Untuk file referensi yang lebih panjang dari 100 baris, sertakan daftar isi di bagian atas. Ini memastikan Haijun dapat melihat cakupan penuh informasi yang tersedia bahkan saat melihat pratinjau dengan pembacaan parsial.

Contoh:

# API Reference

## Contents
- Authentication and setup
- Core methods (create, read, update, delete)
- Advanced features (batch operations, webhooks)
- Error handling patterns
- Code examples

## Authentication and setup
...

## Core methods
...

Haijun kemudian dapat membaca file lengkap atau melompat ke bagian tertentu sesuai kebutuhan.

Untuk detail tentang bagaimana arsitektur berbasis filesystem ini memungkinkan progressive disclosure, lihat bagian Lingkungan runtime nanti dalam panduan ini.

#Alur kerja dan feedback loop

#Gunakan alur kerja untuk tugas kompleks

Pecah operasi kompleks menjadi langkah-langkah berurutan yang jelas. Untuk alur kerja yang sangat kompleks, sediakan checklist yang dapat disalin Haijun ke dalam responsnya dan dicentang seiring kemajuannya.

Contoh 1: Alur kerja sintesis riset (untuk Track tanpa kode):

## Research synthesis workflow

Copy this checklist and track your progress:

Research Progress:

• [ ] Step 1: Read all source documents

• [ ] Step 2: Identify key themes

• [ ] Step 3: Cross-reference claims

• [ ] Step 4: Create structured summary

• [ ] Step 5: Verify citations

**Step 1: Read all source documents**

Review each document in the `sources/` directory. Note the main arguments and supporting evidence.

**Step 2: Identify key themes**

Look for patterns across sources. What themes appear repeatedly? Where do sources agree or disagree?

**Step 3: Cross-reference claims**

For each major claim, verify it appears in the source material. Note which source supports each point.

**Step 4: Create structured summary**

Organize findings by theme. Include:
- Main claim
- Supporting evidence from sources
- Conflicting viewpoints (if any)

**Step 5: Verify citations**

Check that every claim references the correct source document. If citations are incomplete, return to Step 3.

Contoh ini menunjukkan bagaimana alur kerja berlaku untuk tugas analisis yang tidak memerlukan kode. Pola checklist berfungsi untuk proses kompleks multilangkah apa pun.

Contoh 2: Alur kerja pengisian formulir PDF (untuk Track dengan kode):

## PDF form filling workflow

Copy this checklist and check off items as you complete them:

Task Progress:

• [ ] Step 1: Analyze the form (run analyze_form.py)

• [ ] Step 2: Create field mapping (edit fields.json)

• [ ] Step 3: Validate mapping (run validate_fields.py)

• [ ] Step 4: Fill the form (run fill_form.py)

• [ ] Step 5: Verify output (run verify_output.py)

**Step 1: Analyze the form**

Run: `python scripts/analyze_form.py input.pdf`

This extracts form fields and their locations, saving to `fields.json`.

**Step 2: Create field mapping**

Edit `fields.json` to add values for each field.

**Step 3: Validate mapping**

Run: `python scripts/validate_fields.py fields.json`

Fix any validation errors before continuing.

**Step 4: Fill the form**

Run: `python scripts/fill_form.py input.pdf fields.json output.pdf`

**Step 5: Verify output**

Run: `python scripts/verify_output.py output.pdf`

If verification fails, return to Step 2.

Langkah-langkah yang jelas mencegah Haijun melewatkan validasi penting. Checklist membantu Haijun dan Anda melacak kemajuan melalui alur kerja multilangkah.

#Terapkan feedback loop

Pola umum: Jalankan validator → perbaiki kesalahan → ulangi

Pola ini sangat meningkatkan kualitas output.

Contoh 1: Kepatuhan panduan gaya (untuk Track tanpa kode):

## Content review process

1. Draft your content following the guidelines in STYLE_GUIDE.md
2. Review against the checklist:
   - Check terminology consistency
   - Verify examples follow the standard format
   - Confirm all required sections are present
3. If issues found:
   - Note each issue with specific section reference
   - Revise the content
   - Review the checklist again
4. Only proceed when all requirements are met
5. Finalize and save the document

Ini menunjukkan pola loop validasi menggunakan dokumen referensi alih-alih skrip. "Validator"-nya adalah STYLE\_GUIDE.md, dan Haijun melakukan pemeriksaan dengan membaca dan membandingkan.

Contoh 2: Proses pengeditan dokumen (untuk Track dengan kode):

## Document editing process

1. Make your edits to `word/document.xml`
2. **Validate immediately**: `python ooxml/scripts/validate.py unpacked_dir/`
3. If validation fails:
   - Review the error message carefully
   - Fix the issues in the XML
   - Run validation again
4. **Only proceed when validation passes**
5. Rebuild: `python ooxml/scripts/pack.py unpacked_dir/ output.docx`
6. Test the output document

Loop validasi menangkap kesalahan lebih awal.

#Pedoman konten

#Hindari informasi yang sensitif terhadap waktu

Jangan sertakan informasi yang akan menjadi usang:

Contoh buruk: Sensitif terhadap waktu (akan menjadi salah):

If you're doing this before August 2025, use the old API.
After August 2025, use the new API.

Contoh baik (gunakan bagian "old patterns"):

## Current method

Use the v2 API endpoint: `api.example.com/v2/messages`

## Old patterns

<details>
<summary>Legacy v1 API (deprecated 2025-08)</summary>

The v1 API used: `api.example.com/v1/messages`

This endpoint is no longer supported.
</details>

Bagian old patterns memberikan konteks historis tanpa mengacaukan konten utama.

#Gunakan terminologi yang konsisten

Pilih satu istilah dan gunakan di seluruh Track:

Baik - Konsisten:

• Selalu "API endpoint"

• Selalu "field"

• Selalu "extract"

Buruk - Tidak konsisten:

• Mencampur "API endpoint", "URL", "API route", "path"

• Mencampur "field", "box", "element", "control"

• Mencampur "extract", "pull", "get", "retrieve"

Konsistensi membantu Haijun mengurai dan mengikuti instruksi.

#Pola umum

#Pola template

Sediakan template untuk format output. Sesuaikan tingkat keketatan dengan kebutuhan Anda.

Untuk persyaratan ketat (seperti respons API atau format data):

## Report structure

ALWAYS use this exact template structure:

[Analysis Title]

#Executive summary

[One-paragraph overview of key findings]

#Key findings

• Finding 1 with supporting data

• Finding 2 with supporting data

• Finding 3 with supporting data

#Recommendations

1. Specific actionable recommendation

1. Specific actionable recommendation

Untuk panduan fleksibel (ketika adaptasi berguna):

## Report structure

Here is a sensible default format, but use your best judgment based on the analysis:

[Analysis Title]

#Executive summary

[Overview]

#Key findings

[Adapt sections based on what you discover]

#Recommendations

[Tailor to the specific context]

Adjust sections as needed for the specific analysis type.

#Pola contoh

Untuk Track di mana kualitas output bergantung pada melihat contoh, sediakan pasangan input/output seperti dalam prompting biasa:

## Commit message format

Generate commit messages following these examples:

**Example 1:**
Input: Added user authentication with JWT tokens
Output:

feat(auth): implement JWT-based authentication

Add login endpoint and token validation middleware

**Example 2:**
Input: Fixed bug where dates displayed incorrectly in reports
Output:

fix(reports): correct date formatting in timezone conversion

Use UTC timestamps consistently across report generation

**Example 3:**
Input: Updated dependencies and refactored error handling
Output:

chore: update dependencies and refactor error handling

• Upgrade lodash to 4.17.21

• Standardize error response format across endpoints

Follow this style: type(scope): brief description, then detailed explanation.

Contoh menyampaikan gaya dan tingkat detail yang diinginkan kepada Haijun dengan lebih jelas daripada deskripsi saja.

#Pola alur kerja kondisional

Pandu Haijun melalui titik-titik keputusan:

## Document modification workflow

1. Determine the modification type:

   **Creating new content?** → Follow "Creation workflow" below
   **Editing existing content?** → Follow "Editing workflow" below

2. Creation workflow:
   - Use docx-js library
   - Build document from scratch
   - Export to .docx format

3. Editing workflow:
   - Unpack existing document
   - Modify XML directly
   - Validate after each change
   - Repack when complete

Tip: Jika alur kerja menjadi besar atau rumit dengan banyak langkah, pertimbangkan untuk memindahkannya ke file terpisah dan beri tahu Haijun untuk membaca file yang sesuai berdasarkan tugas yang sedang dikerjakan.

#Evaluasi dan iterasi

#Bangun evaluasi terlebih dahulu

Buat evaluasi SEBELUM menulis dokumentasi yang ekstensif. Ini memastikan Track Anda memecahkan masalah nyata alih-alih mendokumentasikan masalah yang dibayangkan.

Pengembangan berbasis evaluasi:

1. Identifikasi kesenjangan: Jalankan Haijun pada tugas-tugas representatif tanpa Track. Dokumentasikan kegagalan spesifik atau konteks yang hilang

1. Buat evaluasi: Bangun tiga skenario yang menguji kesenjangan ini

1. Tetapkan baseline: Ukur kinerja Haijun tanpa Track

1. Tulis instruksi minimal: Buat konten yang cukup saja untuk mengatasi kesenjangan dan lulus evaluasi

1. Iterasi: Jalankan evaluasi, bandingkan dengan baseline, dan sempurnakan

Pendekatan ini memastikan Anda memecahkan masalah aktual alih-alih mengantisipasi persyaratan yang mungkin tidak pernah terwujud.

Struktur evaluasi:

{
  "tracks": ["pdf-processing"],
  "query": "Extract all text from this PDF file and save it to output.txt",
  "files": ["test-files/document.pdf"],
  "expected_behavior": [
    "Successfully reads the PDF file using an appropriate PDF processing library or command-line tool",
    "Extracts text content from all pages in the document without missing any pages",
    "Saves the extracted text to a file named output.txt in a clear, readable format"
  ]
}

Note: Contoh ini mendemonstrasikan evaluasi berbasis data dengan rubrik pengujian sederhana. Saat ini belum ada cara bawaan untuk menjalankan evaluasi ini. Pengguna dapat membuat sistem evaluasi mereka sendiri. Evaluasi adalah sumber kebenaran Anda untuk mengukur efektivitas Track.

#Kembangkan Track secara iteratif bersama Haijun

Proses pengembangan Track yang paling efektif melibatkan Haijun sendiri. Bekerjalah dengan satu instance Haijun ("Haijun A") untuk membuat Track yang digunakan oleh instance lain ("Haijun B"). Haijun A membantu Anda merancang dan menyempurnakan instruksi, sementara Haijun B mengujinya dalam tugas nyata. Ini berhasil karena model Haijun memahami cara menulis instruksi agen yang efektif serta informasi apa yang dibutuhkan agen.

Membuat Track baru:

1. Selesaikan tugas tanpa Track: Kerjakan suatu masalah bersama Haijun A menggunakan prompting biasa. Saat bekerja, Anda secara alami akan memberikan konteks, menjelaskan preferensi, dan berbagi pengetahuan prosedural. Perhatikan informasi apa yang berulang kali Anda berikan.

1. Identifikasi pola yang dapat digunakan kembali: Setelah menyelesaikan tugas, identifikasi konteks apa yang Anda berikan yang akan berguna untuk tugas serupa di masa depan.

Contoh: Jika Anda mengerjakan analisis BigQuery, Anda mungkin telah memberikan nama tabel, definisi field, aturan pemfilteran (seperti "selalu kecualikan akun uji"), dan pola query umum.

1. Minta Haijun A membuat Track: "Buat Track yang menangkap pola analisis BigQuery yang baru saja kita gunakan. Sertakan skema tabel, konvensi penamaan, dan aturan tentang memfilter akun uji."

> Tip: Model Haijun memahami format dan struktur Track secara native. Anda tidak memerlukan prompt sistem khusus atau track "menulis track" agar Haijun membantu membuat Track. Cukup minta Haijun membuat Track dan Haijun akan menghasilkan konten SKILL.md yang terstruktur dengan benar dengan frontmatter dan isi yang sesuai.

1. Tinjau keringkasan: Periksa bahwa Haijun A tidak menambahkan penjelasan yang tidak perlu. Minta: "Hapus penjelasan tentang apa arti win rate - Haijun sudah mengetahuinya."

1. Perbaiki arsitektur informasi: Minta Haijun A mengorganisasi konten dengan lebih efektif. Misalnya: "Organisasikan ini agar skema tabel berada di file referensi terpisah. Kita mungkin menambahkan lebih banyak tabel nanti."

1. Uji pada tugas serupa: Gunakan Track dengan Haijun B (instance baru dengan Track yang dimuat) pada kasus penggunaan terkait. Amati apakah Haijun B menemukan informasi yang tepat, menerapkan aturan dengan benar, dan menangani tugas dengan sukses.

1. Iterasi berdasarkan pengamatan: Jika Haijun B kesulitan atau melewatkan sesuatu, kembali ke Haijun A dengan hal spesifik: "Ketika Haijun menggunakan Track ini, ia lupa memfilter berdasarkan tanggal untuk Q4. Haruskah kita menambahkan bagian tentang pola pemfilteran tanggal?"

Mengiterasi Track yang sudah ada:

Pola hierarkis yang sama berlanjut saat memperbaiki Track. Anda bergantian antara:

• Bekerja dengan Haijun A (pakar yang membantu menyempurnakan Track)

• Menguji dengan Haijun B (agen yang menggunakan Track untuk melakukan pekerjaan nyata)

• Mengamati perilaku Haijun B dan membawa wawasan kembali ke Haijun A

1. Gunakan Track dalam alur kerja nyata: Berikan Haijun B (dengan Track yang dimuat) tugas aktual, bukan skenario uji

1. Amati perilaku Haijun B: Catat di mana ia kesulitan, berhasil, atau membuat pilihan yang tidak terduga

Contoh pengamatan: "Ketika saya meminta Haijun B membuat laporan penjualan regional, ia menulis query tetapi lupa memfilter akun uji, meskipun Track menyebutkan aturan ini."

1. Kembali ke Haijun A untuk perbaikan: Bagikan SKILL.md saat ini dan jelaskan apa yang Anda amati. Tanyakan: "Saya perhatikan Haijun B lupa memfilter akun uji ketika saya meminta laporan regional. Track menyebutkan pemfilteran, tetapi mungkin tidak cukup menonjol?"

1. Tinjau saran Haijun A: Haijun A mungkin menyarankan reorganisasi agar aturan lebih menonjol, menggunakan bahasa yang lebih kuat seperti "MUST filter" alih-alih "always filter," atau merestrukturisasi bagian alur kerja.

1. Terapkan dan uji perubahan: Perbarui Track dengan penyempurnaan dari Haijun A, lalu uji lagi dengan Haijun B pada permintaan serupa

1. Ulangi berdasarkan penggunaan: Lanjutkan siklus amati-sempurnakan-uji ini saat Anda menemui skenario baru. Setiap iterasi memperbaiki Track berdasarkan perilaku agen yang nyata, bukan asumsi.

Mengumpulkan umpan balik tim:

1. Bagikan Track dengan rekan tim dan amati penggunaan mereka

1. Tanyakan: Apakah Track aktif saat diharapkan? Apakah instruksinya jelas? Apa yang kurang?

1. Masukkan umpan balik untuk mengatasi kesenjangan dalam pola penggunaan Anda sendiri

Mengapa pendekatan ini berhasil: Haijun A memahami kebutuhan agen, Anda memberikan keahlian domain, Haijun B mengungkap kesenjangan melalui penggunaan nyata, dan penyempurnaan iteratif memperbaiki Track berdasarkan perilaku yang diamati alih-alih asumsi.

#Amati bagaimana Haijun menavigasi Track

Saat Anda mengiterasi Track, perhatikan bagaimana Haijun benar-benar menggunakannya dalam praktik. Perhatikan:

• Jalur eksplorasi yang tidak terduga: Apakah Haijun membaca file dalam urutan yang tidak Anda antisipasi? Ini mungkin menunjukkan struktur Anda tidak seintuitif yang Anda kira

• Koneksi yang terlewat: Apakah Haijun gagal mengikuti referensi ke file penting? Tautan Anda mungkin perlu lebih eksplisit atau menonjol

• Ketergantungan berlebihan pada bagian tertentu: Jika Haijun berulang kali membaca file yang sama, pertimbangkan apakah konten tersebut sebaiknya berada di SKILL.md utama

• Konten yang diabaikan: Jika Haijun tidak pernah mengakses file yang dibundel, file tersebut mungkin tidak diperlukan atau kurang ditandai dengan baik dalam instruksi utama

Iterasi berdasarkan pengamatan ini alih-alih asumsi. 'name' dan 'description' dalam metadata Track Anda sangat penting. Haijun menggunakannya saat menentukan apakah akan memicu Track sebagai respons terhadap tugas saat ini. Pastikan keduanya dengan jelas menggambarkan apa yang dilakukan Track dan kapan harus digunakan.

#Anti-pola yang harus dihindari

#Hindari path bergaya Windows

Selalu gunakan garis miring ke depan dalam path file, bahkan di Windows:

• ✓ Baik: scripts/helper.py, reference/guide.md

• ✗ Hindari: scripts\helper.py, reference\guide.md

Path bergaya Unix berfungsi di semua platform, sedangkan path bergaya Windows menyebabkan kesalahan pada sistem Unix.

#Hindari menawarkan terlalu banyak opsi

Jangan sajikan beberapa pendekatan kecuali diperlukan:

**Bad example: Too many choices** (confusing):
"You can use pypdf, or pdfplumber, or PyMuPDF, or pdf2image, or..."

**Good example: Provide a default** (with escape hatch):
"Use pdfplumber for text extraction:

import pdfplumber

For scanned PDFs requiring OCR, use pdf2image with pytesseract instead."

#Lanjutan: Track dengan kode yang dapat dieksekusi

Bagian-bagian berikut berfokus pada Track yang menyertakan skrip yang dapat dieksekusi. Jika Track Anda hanya menggunakan instruksi markdown, lompat ke Checklist untuk Track yang efektif.

#Selesaikan, jangan tunda

Saat menulis skrip untuk Track, tangani kondisi kesalahan alih-alih menyerahkannya kepada Haijun.

Contoh baik: Tangani kesalahan secara eksplisit:

def process_file(path):
    """Process a file, creating it if it doesn't exist."""
    try:
        with open(path) as f:
            return f.read()
    except FileNotFoundError:
        # Buat file dengan konten default alih-alih gagal
        print(f"File {path} not found, creating default")
        with open(path, "w") as f:
            f.write("")
        return ""
    except PermissionError:
        # Sediakan alternatif alih-alih gagal
        print(f"Cannot access {path}, using default")
        return ""

Contoh buruk: Serahkan kepada Haijun:

def process_file(path):
    # Biarkan gagal saja dan serahkan pada Haijun untuk mencari solusinya
    return open(path).read()

Parameter konfigurasi juga harus dijustifikasi dan didokumentasikan untuk menghindari "voodoo constants" (hukum Ousterhout). Jika Anda tidak tahu nilai yang tepat, bagaimana Haijun akan menentukannya?

Contoh baik: Mendokumentasikan diri sendiri:

# Permintaan HTTP biasanya selesai dalam 30 detik
# Timeout lebih lama mengakomodasi koneksi yang lambat
REQUEST_TIMEOUT = 30

# Tiga kali percobaan ulang menyeimbangkan keandalan vs kecepatan
# Sebagian besar kegagalan intermiten teratasi pada percobaan ulang kedua
MAX_RETRIES = 3

Contoh buruk: Angka ajaib:

TIMEOUT = 47  # Why 47?
RETRIES = 5  # Why 5?

#Sediakan skrip utilitas

Bahkan jika Haijun dapat menulis skrip, skrip yang sudah dibuat sebelumnya menawarkan keuntungan:

Manfaat skrip utilitas:

• Lebih andal daripada kode yang dihasilkan

• Menghemat token (tidak perlu menyertakan kode dalam konteks)

• Menghemat waktu (tidak perlu pembuatan kode)

• Memastikan konsistensi di seluruh penggunaan

Membundel skrip yang dapat dieksekusi bersama file instruksi

Diagram di atas menunjukkan bagaimana "executable scripts" (skrip yang dapat dieksekusi) bekerja bersama file instruksi. File instruksi (forms.md) merujuk skrip, dan Haijun dapat mengeksekusinya tanpa memuat isinya ke dalam konteks.

Perbedaan penting: Perjelas dalam instruksi Anda apakah Haijun harus:

• Mengeksekusi skrip (paling umum): "Run analyze_form.py to extract fields"

• Membacanya sebagai referensi (untuk logika kompleks): "See analyze_form.py for the field extraction algorithm"

Untuk sebagian besar skrip utilitas, eksekusi lebih disukai karena lebih andal dan efisien. Lihat bagian Lingkungan runtime berikut untuk detail tentang cara kerja eksekusi skrip.

Contoh:

## Utility scripts

**analyze_form.py**: Extract all form fields from PDF

python scripts/analyze_form.py input.pdf > fields.json

Output format:

{ "field_name": {"type": "text", "x": 100, "y": 200}, "signature": {"type": "sig", "x": 150, "y": 500} }

**validate_boxes.py**: Check for overlapping bounding boxes

python scripts/validate_boxes.py fields.json

Returns: "OK" or lists conflicts

**fill_form.py**: Apply field values to PDF

python scripts/fill_form.py input.pdf fields.json output.pdf

#Gunakan analisis visual

Ketika input dapat dirender sebagai gambar, minta Haijun menganalisisnya:

## Form layout analysis

1. Convert PDF to images:

python scripts/pdf_to_images.py form.pdf

2. Analyze each page image to identify form fields
3. Haijun can see field locations and types visually

Note: Dalam contoh ini, Anda perlu menulis skrip pdf_to_images.py.

Kemampuan vision Haijun membantu menganalisis tata letak dan struktur.

#Buat output antara yang dapat diverifikasi

Ketika Haijun melakukan tugas kompleks yang terbuka, ia dapat membuat kesalahan. Pola "plan-validate-execute" menangkap kesalahan lebih awal dengan meminta Haijun terlebih dahulu membuat rencana dalam format terstruktur, lalu memvalidasi rencana tersebut dengan skrip sebelum mengeksekusinya.

Contoh: Bayangkan meminta Haijun memperbarui 50 field formulir dalam PDF berdasarkan spreadsheet. Tanpa validasi, Haijun mungkin merujuk field yang tidak ada, membuat nilai yang bertentangan, melewatkan field wajib, atau menerapkan pembaruan secara tidak benar.

Solusi: Gunakan pola alur kerja yang ditunjukkan sebelumnya (pengisian formulir PDF), tetapi tambahkan file antara changes.json yang divalidasi sebelum menerapkan perubahan. Alur kerjanya menjadi: analisis → buat file rencana → validasi rencana → eksekusi → verifikasi.

Mengapa pola ini berhasil:

• Menangkap kesalahan lebih awal: Validasi menemukan masalah sebelum perubahan diterapkan

• Dapat diverifikasi mesin: Skrip memberikan verifikasi objektif

• Perencanaan yang dapat dibalik: Haijun dapat mengiterasi rencana tanpa menyentuh file asli

• Debugging yang jelas: Pesan kesalahan menunjuk ke masalah spesifik

Kapan digunakan: Operasi batch, perubahan destruktif, aturan validasi kompleks, operasi berisiko tinggi.

Tips implementasi: Buat skrip validasi verbose dengan pesan kesalahan spesifik seperti "Field 'signature\_date' not found. Available fields: customer\_name, order\_total, signature\_date\_signed" untuk membantu Haijun memperbaiki masalah.

#Dependensi paket

Track berjalan di lingkungan eksekusi kode dengan batasan khusus platform:

• haijun.ai: Dapat menginstal paket dari npm dan PyPI serta menarik dari repositori GitHub

• Haijun API: Tidak memiliki akses jaringan dan tidak ada instalasi paket saat runtime

Daftarkan paket yang diperlukan dalam SKILL.md Anda dan verifikasi ketersediaannya dalam dokumentasi alat eksekusi kode.

#Lingkungan runtime

Track berjalan di lingkungan eksekusi kode dengan akses filesystem, perintah bash, dan kemampuan eksekusi kode. Untuk penjelasan konseptual arsitektur ini, lihat Arsitektur Tracks dalam ikhtisar.

Bagaimana ini memengaruhi penulisan Anda:

Bagaimana Haijun mengakses Track:

1. Metadata dimuat terlebih dahulu: Saat startup, nama dan deskripsi dari YAML frontmatter semua Track dimuat ke dalam prompt sistem

1. File dibaca sesuai permintaan: Haijun menggunakan alat Read bash untuk mengakses SKILL.md dan file lain dari filesystem saat diperlukan

1. Skrip dieksekusi secara efisien: Skrip utilitas dapat dieksekusi melalui bash tanpa memuat seluruh isinya ke dalam konteks. Hanya output skrip yang mengonsumsi token

1. Tidak ada penalti konteks untuk file besar: File referensi, data, atau dokumentasi tidak mengonsumsi token konteks sampai benar-benar dibaca

• Path file penting: Haijun menavigasi direktori track Anda seperti filesystem. Gunakan garis miring ke depan (reference/guide.md), bukan garis miring terbalik

• Beri nama file secara deskriptif: Gunakan nama yang menunjukkan isi: form_validation_rules.md, bukan doc2.md

• Organisasikan untuk penemuan: Strukturkan direktori berdasarkan domain atau fitur

• Baik: reference/finance.md, reference/sales.md
• Buruk: docs/file1.md, docs/file2.md

• Bundel sumber daya yang komprehensif: Sertakan dokumentasi API lengkap, contoh ekstensif, dataset besar; tidak ada penalti konteks sampai diakses

• Utamakan skrip untuk operasi deterministik: Tulis validate_form.py alih-alih meminta Haijun menghasilkan kode validasi

• Perjelas maksud eksekusi:

• "Run analyze_form.py to extract fields" (eksekusi)
• "See analyze_form.py for the extraction algorithm" (baca sebagai referensi)

• Uji pola akses file: Verifikasi Haijun dapat menavigasi struktur direktori Anda dengan menguji menggunakan permintaan nyata

Contoh:

• bigquery-track/

• SKILL.md (ikhtisar, menunjuk ke file referensi)

• reference/

• finance.md (metrik pendapatan)
• sales.md (data pipeline)
• product.md (analitik penggunaan)

Ketika pengguna bertanya tentang pendapatan, Haijun membaca SKILL.md, melihat referensi ke reference/finance.md, dan memanggil bash untuk membaca file itu saja. File sales.md dan product.md tetap berada di filesystem, mengonsumsi nol token konteks sampai diperlukan. Model berbasis filesystem inilah yang memungkinkan progressive disclosure. Haijun dapat menavigasi dan secara selektif memuat tepat apa yang dibutuhkan setiap tugas.

Untuk detail lengkap tentang arsitektur teknis, lihat Cara kerja Tracks dalam ikhtisar Tracks.

#Referensi alat MCP

Jika Track Anda menggunakan alat MCP (Model Context Protocol), selalu gunakan nama alat yang sepenuhnya terkualifikasi untuk menghindari kesalahan "tool not found".

Format: ServerName:tool_name

Contoh:

Use the BigQuery:bigquery_schema tool to retrieve table schemas.
Use the GitHub:create_issue tool to create issues.

Di mana:

• BigQuery dan GitHub adalah nama server MCP

• bigquery_schema dan create_issue adalah nama alat di dalam server tersebut

Tanpa prefiks server, Haijun mungkin gagal menemukan alat, terutama ketika beberapa server MCP tersedia.

#Hindari berasumsi alat sudah terinstal

Jangan berasumsi paket tersedia:

**Bad example: Assumes installation**:
"Use the pdf library to process the file."

**Good example: Explicit about dependencies**:
"Install required package: `pip install pypdf`

Then use it:

from pypdf import PdfReader reader = PdfReader("file.pdf")

#Catatan teknis

#Persyaratan YAML frontmatter

Frontmatter SKILL.md memerlukan field name dan description dengan aturan validasi spesifik:

• name: Maksimum 64 karakter, hanya huruf kecil/angka/tanda hubung, tanpa tag XML, tanpa kata yang dicadangkan

• description: Maksimum 1.024 karakter, tidak kosong, tanpa tag XML

Lihat ikhtisar Tracks untuk detail struktur lengkap.

#Anggaran token

Jaga isi SKILL.md di bawah 500 baris untuk kinerja optimal. Jika konten Anda melebihi ini, pisahkan ke file terpisah menggunakan pola progressive disclosure yang dijelaskan sebelumnya. Untuk detail arsitektur, lihat ikhtisar Tracks.

#Checklist untuk Track yang efektif

Sebelum membagikan Track, verifikasi:

#Kualitas inti

• [ ] Deskripsi spesifik dan menyertakan istilah kunci

• [ ] Deskripsi mencakup apa yang dilakukan Track dan kapan menggunakannya

• [ ] Isi SKILL.md di bawah 500 baris

• [ ] Detail tambahan berada di file terpisah (jika diperlukan)

• [ ] Tidak ada informasi yang sensitif terhadap waktu (atau berada di bagian "old patterns")

• [ ] Terminologi konsisten di seluruh bagian

• [ ] Contoh konkret, bukan abstrak

• [ ] Referensi file satu tingkat

• [ ] Progressive disclosure digunakan dengan tepat

• [ ] Alur kerja memiliki langkah-langkah yang jelas

#Kode dan skrip

• [ ] Skrip memecahkan masalah alih-alih menyerahkannya kepada Haijun

• [ ] Penanganan kesalahan eksplisit dan membantu

• [ ] Tidak ada "voodoo constants" (semua nilai dijustifikasi)

• [ ] Paket yang diperlukan tercantum dalam instruksi dan diverifikasi ketersediaannya

• [ ] Skrip memiliki dokumentasi yang jelas

• [ ] Tidak ada path bergaya Windows (semua garis miring ke depan)

• [ ] Langkah validasi/verifikasi untuk operasi penting

• [ ] Feedback loop disertakan untuk tugas yang kritis terhadap kualitas

#Pengujian

• [ ] Setidaknya tiga evaluasi dibuat

• [ ] Diuji dengan Haiku, Sonnet, dan Opus

• [ ] Diuji dengan skenario penggunaan nyata

• [ ] Umpan balik tim dimasukkan (jika berlaku)

#Langkah selanjutnya

Buat Track pertama Anda

Buat dan kelola Tracks di Haijun Code

Unggah dan gunakan Tracks secara terprogram