Cara Menulis dan Melaksanakan Kemahiran Ejen

Pengenalan

Kemahiran Ejen adalah folder arahan, skrip, dan sumber yang boleh dimuatkan oleh Model Bahasa Besar (LLM) apabila berkaitan untuk melaksanakan tugas khusus dengan cara yang konsisten dan boleh diulang. Ia diperkenalkan sebagai rangka kerja terbuka oleh Claude pada tahun 2025, dan rangka kerja ini semakin diterima pakai oleh organisasi lain dan pembangun ejen sejak itu.

Pada masa lalu, apabila memberikan tugasan kepada LLM, adalah perlu untuk menyediakan konteks secara manual untuk aliran kerja LLM. Dengan Kemahiran Ejen, anda boleh memisahkan sumber dan arahan tambahan ke dalam folder yang hanya boleh diakses apabila LLM mengenal pasti ia diperlukan.

Sebagai contoh, jika anda ingin LLM anda membuat persembahan PowerPoint, daripada menambah panduan gaya, grafik, dan templat organisasi secara manual ke dalam prompt setiap kali, anda boleh menambahnya ke dalam folder sebagai Skill dan LLM boleh mencari dan menggunakan sumber tersebut secara sendiri setiap kali anda memerlukan persembahan dibuat. Anda boleh menambah sejumlah besar Skill, dan LLM boleh merujuknya seperti alat.

Dalam tutorial ini, anda akan membuat Kemahiran Ejen untuk pengekstrak PDF dengan folder pilihan untuk dokumentasi rujukan dan aset lain.

Kesimpulan Utama

  • Kemahiran Ejen adalah folder yang mengandungi fail SKILL.md dengan metadata dan arahan yang membolehkan LLM memuatkan keupayaan khusus hanya apabila berkaitan, bukannya memerlukan semua konteks dalam setiap arahan. Claude memperkenalkan rangka kerja ini pada tahun 2025, dan ia membolehkan aliran kerja ejen yang lebih cekap dengan memisahkan sumber ke dalam modul yang boleh diakses secara bebas.

  • Untuk ejen menggunakan kemahiran, mereka perlu dapat menemui, memuat, dan melaksanakannya. Ini melibatkan penyusunan kemahiran yang tersedia dan mencari yang terbaik untuk permintaan pengguna.

  • Kemahiran agen kemungkinan akan menjadi standard penting untuk menambah kebolehan kepada agen. Ia menawarkan banyak penyesuaian dan potensi dinamik untuk agen.

Langkah 1 — Mencipta Kemahiran

Pelaksanaan kemahiran yang paling mudah adalah folder yang mengandungi fail SKILL.md. Fail markdown ini termasuk metadata dan arahan untuk ejen yang menerangkan cara untuk melaksanakan tugas-tugas tertentu. Anda juga boleh menyertakan sumber tambahan, templat, skrip, dan bahan rujukan dalam folder tersebut.

Folder Structure
your-skill-name/
├── SKILL.md          # Required: instructions + metadata
├── scripts/          # Optional: executable code
├── references/       # Optional: documentation
└── assets/           # Optional: templates, resources

Nama folder Kemahiran akan menjadi nama Kemahiran. Kemudian di dalam folder terdapat fail SKILL.md dan sebarang bahan tambahan yang ingin anda sertakan.

Pertama, buat satu folder yang dipanggil skills. Folder ini akan mengandungi semua Skills yang anda tulis. Di dalam folder skills, buat satu lagi folder yang dipanggil pdf-parsing. Folder ini akan mengandungi semua fail dan dokumentasi untuk Skill pdf-parsing anda. Di dalam folder pdf-parsing, buat satu fail SKILL.md dengan kandungan berikut.

---
name: pdf-processing
description: Extracts text from PDF files using PyPDF2.
---

# PDF Processing Skill

## When to use this skill
Use this skill when a user needs to extract text from a PDF file.

## How to Use this Skill
This skill provides the `extract_text()` function from the `parse_pdf.py` script. Import it into your agent script:

python
from skills.pdf_parsing.parse_pdf import extract_text

result = extract_text(
    file_path="/path/to/document.pdf",
    pages="all"  # or "1-3" or "1,2,3"
)

### Parameters
- `file_path` (str): Path to the PDF file
- `pages` (str): Pages to extract - "all", "1-3" (range), or "1,2,3" (specific pages)

### Returns
JSON object with:
- `success` (bool): Whether extraction succeeded
- `file_path` (str): Path to the processed file
- `total_pages` (int): Total pages in PDF
- `extracted_pages` (int): Number of pages extracted
- `pages` (list): Array of {page: number, text: string} objects

Alternatively, you can call the script directly from the command line:
command
python skills/pdf-parsing/parse_pdf.py extract_text --file_path /path/to/file.pdf --pages all

name dan description diperlukan di bahagian atas fail markdown dalam frontmatter supaya ejen dapat menguraikan deskripsi. Frontmatter adalah bahagian di bahagian atas fail markdown yang mengandungi metadata. Ejen akan menggunakan bidang ini dari setiap Kemahiran untuk mengenal pasti Kemahiran mana yang paling sesuai untuk sesuatu permintaan. Anda boleh menyertakan bidang pilihan dalam frontmatter termasuk lesen, keserasian, metadata, dan alat-dibenarkan. Untuk aliran kerja ejen tersuai, anda boleh menambah mana-mana bidang yang anda mahu. Ejen akan menyertakan frontmatter dari setiap kemahiran bersama permintaan pengguna untuk mengenal pasti kemahiran yang sesuai.

Bagi selebihnya kandungan markdown, tiada keperluan khusus untuk arahan. Cuba ikuti amalan terbaik dalam memberikan arahan dan pastikan arahan jelas untuk diikuti oleh LLM. Baki kandungan akan ditanya selepas agen menentukan Kemahiran yang akan digunakan.

Kemudian, sama ada gunakan skrip parser PDF percuma ini atau buat fail parse_pdf.py dengan fungsi extract_text() yang mempunyai fungsi parsing PDF. Pastikan anda memasang sebarang kebergantungan setiap kali anda menambah Kemahiran. Untuk skrip yang dilampirkan, anda akan memerlukan PyPDF2.

pip3 install PyPDF2

Ini akan memasang pakej Python PyPDF2.

Langkah 2 — Mengintegrasikan Kemahiran

Untuk Kemahiran digunakan oleh ejen, ejen perlu mengikuti beberapa langkah. Ia perlu menemui Kemahiran di semua direktori dengan fail SKILL.md, memuatkan metadata (nama dan keterangan) setiap fail markdown semasa permulaan, memadankan permintaan pengguna dengan Kemahiran yang relevan, mengaktifkan Kemahiran dengan memuatkan arahan penuh dari fail markdown, dan melaksanakan kemahiran dengan memuatkan fail yang dirujuk, mengikuti arahan, dan menjalankan kod jika perlu.

Sesetengah ejen, seperti Claude Code dan Codex, secara automatik mengintegrasikan Kemahiran ke dalam aliran kerja mereka, dan semakin ramai penyedia ejen sedang mengintegrasikan langkah-langkah ini ke dalam aliran kerja ejen mereka.

Jika anda ingin mengintegrasikan kemahiran anda ke dalam ejen tersuai anda sendiri, terdapat dua cara utama untuk melakukannya. Anda boleh menggunakan corak berasaskan sistem fail atau corak berasaskan alat. Dengan corak berasaskan sistem fail, aliran kerja LLM beroperasi dalam persekitaran komputer dan mengeluarkan arahan shell seperti cat /path/to/my-skill/skill.md yang kemudiannya dijalankan. Sebagai alternatif, pendekatan berasaskan alat secara berkesan menjadikan Kemahiran tersebut sebagai alat yang boleh dipanggil oleh LLM.

Membina ejen berkemahiran dari awal adalah di luar skop tutorial ini, tetapi anda boleh menggunakan skrip ejen ini. Skrip ini menggunakan Llama 3.3 70B melalui alat Serverless Inference Platform AI Gradient Linux-Console.net. Anda perlu mendapatkan kunci akses model untuk menggunakan Serverless Inference pada Platform AI Gradient Linux-Console.net. Tambahkan kunci akses model anda dalam fungsi main() skrip tersebut.

Setelah anda mempunyai skrip dalam folder yang sama dengan folder skills anda, jalankan skrip tersebut.

python3 agent_example.py

Dalam kotak teks yang dibukanya untuk anda, masukkan: Sila parse teks daripada PDF di /path/to/your/document.pdf. Anda sepatutnya melihat output dengan teks yang telah diparse daripada PDF tersebut.

============================================================
SIMPLE TOOL-BASED SKILLS EXAMPLE
============================================================

✅ Found 1 skills:
   - pdf-processing: Extracts text from PDF files using PyPDF2.

============================================================
CHAT (type 'quit' to exit)
============================================================

You: Please extract the text from: /Desktop/document.pdf

[Turn 1]
💭 LLM: {"function_call": {"name": "activate_skill", "arguments": {"skill_name": "pdf-processing"}}}
..........
The cost of an RV is 30,000

Ejen telah berjaya menemui Kemahiran, mengekstrak metadata, melaksanakan Kemahiran, dan memulangkan teks dari PDF.

Langkah 3 — Menambah Fungsi dan Kemahiran

Tambah sebarang skrip atau folder lain yang anda ingin LLM akses. Kemudian tambah arahan dan penerangan tentang fungsi untuk setiap folder dan skrip dalam fail SKILL.md. Sebagai contoh, anda boleh menambah skrip yang boleh menjana atau mengedit PDF. Pastikan anda menambah fail tambahan ini dalam folder kemahiran tertentu yang anda ingin kaitkan dengannya.

Adalah mungkin untuk menambah seberapa banyak Kemahiran yang anda mahu, tetapi setiap folder Kemahiran mesti mempunyai fail SKILL.md dalam folder tersebut agar ia dikenali oleh ejen. Selain itu, ia boleh menjadi sukar bagi ejen untuk memadankan niat pengguna dengan metadata bagi banyak Kemahiran, jadi apabila bilangan Kemahiran meningkat, mungkin perlu untuk menambah fungsi carian tambahan atau menggunakan embedding vektor untuk memadankan permintaan pengguna dengan kemahiran yang betul.

Soalan Lazim

Adakah Kemahiran boleh berkomunikasi antara satu sama lain atau memanggil Kemahiran lain, dan bagaimana anda akan melaksanakan pengaitan kemahiran?

Ya, Kemahiran boleh memanggil Kemahiran lain. Ejen sepatutnya dapat mengenal pasti bila beberapa Kemahiran mungkin diperlukan dan menyusunnya bersama-sama. Adalah mungkin untuk merujuk Kemahiran lain dalam arahan kemahiran juga.

Bagaimana saya mengendalikan pengesahan dan kunci API dalam Skills apabila ia perlu mengakses perkhidmatan luaran?

Jangan pernah menetapkan kelayakan secara langsung dalam fail kemahiran. Gunakan pembolehubah persekitaran atau pengurus rahsia yang selamat.

Apakah implikasi prestasi memuatkan banyak Kemahiran semasa permulaan, dan adakah terdapat strategi pemuatan malas yang tersedia?

Memuat metadata untuk beratus-ratus Kemahiran boleh menjadi perlahan. Pertimbangkan untuk menyimpan sementara Kemahiran yang dimuat dan menggunakan pengindeksan untuk carian yang lebih pantas di kalangan banyak Kemahiran. Anda boleh memisahkan langkah penemuan dan pengaktifan supaya hanya memuat metadata sehingga kemahiran penuh diperlukan.

Bagaimana saya menguji dan membetulkan Skills?

Pastikan anda menguji Kemahiran individu sebelum menggabungkannya, dan tambahkan log terperinci pada Kemahiran anda untuk melihat kemahiran mana yang dipilih dan mengapa.

Kesimpulan

Kemahiran Ejen adalah cara yang sangat baik untuk menstandarkan fungsi ejen LLM. Ia membolehkan pengguna menambah dan meningkatkan keupayaan ejen secara teratur. Cara anda melaksanakannya bergantung pada aliran kerja ejen khusus anda, tetapi bilangan perkhidmatan ejen yang boleh menggunakan Kemahiran secara terus meningkat, dengan Claude Code, Codex, dan VSCode hanyalah beberapa penyedia ejen yang telah mengguna pakai standard ini.

Seterusnya, tambahkan lebih banyak Kemahiran dan sesuaikannya dengan fungsi tambahan yang sesuai untuk projek anda. Kemudian, tingkatkan keupayaan pemadanan kemahiran aliran kerja ejen anda melalui pengekod vektor atau fungsi carian lain.

Terima kasih kerana belajar bersama Komuniti Linux-Console.net.