|

Pahami 5 Perbedaan Inti Folder .agents dan .claude: Di Mana Menempatkan Skill Pengembangan AI Agent?

ByAPIYI - Stable and affordable AI API

Penulis: Penjelasan mendalam tentang perbedaan lokasi folder konfigurasi .agents dan .claude dalam pengembangan AI Agent, spesifikasi penyimpanan Skills, perbandingan struktur direktori, serta skenario penggunaan AGENTS.md dan CLAUDE.md.

Pengembangan AI Agent semakin populer, dan di direktori root proyek mulai bermunculan berbagai folder konfigurasi—.agents, .claude, .cursor, dan lain-lain. Di antara ini, .agents dan .claude keduanya dapat digunakan untuk menyimpan Skills, namun keduanya memiliki positioning, filosofi desain, dan cakupan aplikasi yang sangat berbeda. Memilih lokasi penyimpanan yang salah dapat menyebabkan Skills tidak berfungsi, atau bahkan konflik konfigurasi saat kolaborasi tim. Artikel ini akan membahas perbedaan inti antara keduanya dari perspektif desain fundamental, serta praktik terbaiknya.

Nilai Inti: Setelah membaca artikel ini, Anda akan memahami apakah Skills harus disimpan di .agents atau .claude, dan bagaimana mengelola konfigurasi Agent secara efisien dalam tim multi-alat.

agents-vs-claude-folder-skills-ai-agent-development-guide-id 图示

Poin Inti Folder .agents dan .claude

Mari kita jawab pertanyaan paling inti terlebih dahulu: kedua folder ini bukan dalam hubungan persaingan, melainkan sistem konfigurasi dengan tingkatan yang berbeda.

Dimensi Perbandingan Folder .claude/ Folder .agents/
Pihak Pemilik Anthropic (Eksklusif untuk Claude Code) Yayasan Agentic AI / Linux Foundation
Posisi Direktori konfigurasi proyek untuk Claude Code Standar konfigurasi Agent yang independen dari alat
Format Skills SKILL.md (Metadata depan Markdown + YAML) SKILL.yaml (YAML murni)
Kematangan Siap produksi, didukung secara resmi oleh Claude Code Spesifikasi sedang dalam proses (Work In Progress)
Dukungan Lintas Alat Hanya Claude Code Bertujuan untuk semua alat AI Agent

Perbedaan Filosofi Desain Folder .agents dan .claude

Perbedaan mendasar kedua folder ini terletak pada filosofi desainnya:

Folder .claude/ mengadopsi pendekatan "integrasi mendalam eksklusif". Folder ini dibuat khusus untuk Claude Code, menyediakan kemampuan lengkap seperti Skills, Subagents, Hooks, Permissions, dan terikat erat dengan rantai alat Claude Code. Kelebihannya adalah fungsionalitas yang lengkap dan siap pakai; konsekuensinya adalah terkunci dalam ekosistem Claude Code.

Folder .agents/ mengadopsi pendekatan "standar universal lintas alat". Folder ini mencoba mendefinisikan spesifikasi konfigurasi yang dapat dibaca oleh semua alat AI Agent, mirip dengan .editorconfig untuk editor. Kelebihannya adalah satu konfigurasi dapat digunakan di banyak alat; konsekuensinya adalah spesifikasi masih dalam pengembangan, dan tingkat dukungan alat bervariasi.

Keduanya dapat hidup berdampingan dalam satu proyek—konfigurasi mendalam yang eksklusif untuk Claude Code ditempatkan di .claude/, sementara konfigurasi umum yang dapat digunakan di berbagai alat ditempatkan di .agents/.

Struktur Direktori Lengkap Folder .claude

Mari kita lihat dulu folder .claude/ asli dari Claude Code, yang saat ini merupakan implementasi paling matang.

Penjelasan Struktur Direktori Folder .claude

.claude/
├── CLAUDE.md              # Instruksi proyek (menggantikan CLAUDE.md di direktori root)
├── settings.json          # Pengaturan proyek (disimpan ke git, dibagikan tim)
├── settings.local.json    # Pengaturan lokal (gitignore, konfigurasi pribadi)
├── skills/                # Direktori skill
│   └── <nama-skill>/
│       ├── SKILL.md       # File definisi skill (wajib)
│       ├── scripts/       # Skrip pendukung
│       ├── references/    # Materi referensi
│       └── templates/     # File template
├── agents/                # Definisi sub-agen
│   └── <nama-agen>.md     # File definisi sub-agen
├── commands/              # Perintah slash versi lama (digabung ke skills)
│   └── <nama-perintah>.md
└── agent-memory/          # Memori persisten sub-agen
    └── <nama-agen>/
        └── MEMORY.md

Selain itu, ada juga direktori tingkat pengguna ~/.claude/. Skill pribadi dapat ditempatkan di sini agar berlaku di semua proyek:

~/.claude/
├── CLAUDE.md              # Instruksi tingkat pengguna (lintas proyek)
├── settings.json          # Pengaturan tingkat pengguna
├── skills/                # Skill pribadi (tersedia di semua proyek)
├── agents/                # Sub-agen pribadi
└── projects/              # Catatan dan data sesi

Format SKILL.md untuk Skill Folder .claude

Skill Claude Code didefinisikan menggunakan file Markdown dengan metadata YAML di bagian depan:

---
name: my-skill
description: Deskripsi skill, membantu Claude memutuskan kapan harus memicu
user-invocable: true        # Pengguna dapat memanggil melalui /my-skill
allowed-tools: Read, Grep   # Membatasi alat yang dapat digunakan
context: fork               # Berjalan dalam sub-agen terpisah
model: sonnet               # Cakupan model
---

Anda adalah asisten peninjau kode profesional...
(Instruksi skill dalam format Markdown)

Penjelasan bidang utama:

  • Skill dengan user-invocable: true akan terdaftar sebagai /slash-command.
  • context: fork berarti berjalan dalam konteks terpisah, tidak mencemari percakapan utama.
  • allowed-tools dapat membatasi kumpulan alat yang dapat digunakan oleh Skill.
  • Dukungan untuk $ARGUMENTS, $0, $1 untuk penggantian argumen.

🎯 Saran Pengembangan: Sistem Skill Claude Code mengikuti standar terbuka Agent Skills (agentskills.io), sintaksnya universal di Claude Code, Claude API, dan VS Code Copilot.
Jika Anda mengembangkan aplikasi AI menggunakan Claude Code, disarankan untuk mendapatkan kunci API melalui APIYI apiyi.com untuk mengelola pemanggilan multi-model secara terpadu.

agents-vs-claude-folder-skills-ai-agent-development-guide-id 图示

Struktur Direktori Folder .agents Lengkap

Spesifikasi folder .agents (AGENTS-1 Spec) dikelola oleh Agentic AI Foundation, yang berada di bawah Linux Foundation. Tujuannya adalah untuk mendefinisikan standar konfigurasi universal yang dapat dipahami oleh semua alat pengkodean AI.

Detail Struktur Direktori Folder .agents

.agents/
├── manifest.yaml          # Wajib: Mendaftarkan konfigurasi, mendeklarasikan semua konfigurasi yang tersedia
├── prompts/               # Wajib: Petunjuk instruksi
│   ├── base.md            # Petunjuk Agen Umum
│   ├── project.md         # Petunjuk Khusus Proyek
│   └── snippets/          # Cuplikan Petunjuk Modular
├── modes/                 # Wajib: Mode Perilaku (mirip dengan .claude/agents/)
│   ├── plan.md            # Mode Perencanaan
│   ├── code.md            # Mode Pengkodean
│   └── review.md          # Mode Tinjauan
├── policies/              # Wajib: Kebijakan Keamanan dan Batasan Kemampuan
├── skills/                # Wajib: Definisi Keterampilan (mengikuti Spesifikasi Keterampilan Agen)
│   └── <name>/
│       └── SKILL.yaml     # Definisi Keterampilan dalam format YAML
├── scopes/                # Wajib: Penimpaan Tingkat Jalur (Dukungan Monorepo)
├── profiles/              # Wajib: Penimpaan Konfigurasi Bernama (dev/ci/staging)
├── schemas/               # Wajib: Validasi Skema JSON
└── state/                 # Status Lokal (tidak di-commit ke git)
    ├── .gitignore
    └── state.yaml

Berbeda dengan .claude/ yang menggunakan SKILL.md (Markdown) untuk Skills, .agents/ menggunakan format SKILL.yaml (YAML murni).

Desain Unik Folder .agents

Spesifikasi .agents memiliki beberapa konsep yang tidak ada di .claude/:

  • Scopes（Lingkup）: Mendefinisikan konfigurasi berbeda untuk subdirektori yang berbeda dalam Monorepo, jalur yang paling spesifik dicocokkan terlebih dahulu.
  • Profiles（Profil）: Mendukung penimpaan konfigurasi bernama seperti dev, ci, prod, mirip dengan variabel lingkungan.
  • Policies（Kebijakan）: Direktori batasan keamanan independen, aturan deny selalu menimpa aturan allow.
  • Determinism（Determinisme）: Input yang sama harus menghasilkan output yang sama, tidak bergantung pada status eksternal.

Perbandingan Aturan Penyimpanan Skills Folder .agents dan .claude

Ini adalah pertanyaan praktis yang paling diperhatikan oleh pengembang: Di mana tepatnya saya harus menyimpan Skills saya?

Perbandingan Skills Folder .agents dan .claude

Dimensi Perbandingan .claude/skills/ .agents/skills/
File Definisi SKILL.md (Markdown + YAML frontmatter) SKILL.yaml (YAML murni)
Dukungan Claude Code Dukungan asli, penemuan otomatis Memerlukan konfigurasi manual atau menunggu dukungan resmi
Perintah Slash user-invocable: true secara otomatis mendaftarkan /command Bergantung pada implementasi alat tertentu
Eksekusi Sub-Agen context: fork berjalan dalam konteks independen Dikonfigurasi melalui modes/
Penimpaan Model model: sonnet ditentukan secara langsung Dikonfigurasi melalui profiles/
Batasan Alat allowed-tools: Read, Grep Melalui policies/
File Pendukung Subdirektori scripts/, references/, templates/ Bergantung pada implementasi
Penerusan Argumen Penggantian variabel $ARGUMENTS, $0, $1 Spesifikasi tidak mendefinisikan secara eksplisit

Bagaimana Folder .agents dan .claude Dapat Hidup Berdampingan

Dalam proyek nyata, kedua folder dapat hidup berdampingan dan saling melengkapi. Ambil contoh proyek ini:

.claude/skills/ menyimpan keterampilan khusus Claude Code:

  • apiyi-article-generator — Pembuatan artikel, integrasi mendalam dengan templat dan spesifikasi proyek
  • apiyi-svg-generator — Pembuatan ilustrasi SVG, bergantung pada templat SVG proyek
  • apiyi-content-reviewer — Tinjauan konten, menggunakan standar kualitas proyek

.agents/skills/ menyimpan keterampilan umum yang portabel:

  • markdown-proxy — Pengambilan URL ke Markdown, menggunakan skrip Python
  • nano-banana-pro-image-gen — Pembuatan gambar, memanggil API eksternal

Prinsip pemisahannya jelas: Keterampilan yang terintegrasi erat dengan Claude Code ditempatkan di .claude/, sedangkan keterampilan yang dapat digunakan kembali di alat AI lain ditempatkan di .agents/.

🎯 Saran Pemilihan: Jika tim Anda hanya menggunakan Claude Code, Anda dapat menempatkan semuanya di .claude/skills/ untuk fungsionalitas terlengkap.
Jika anggota tim menggunakan berbagai alat AI (Cursor, Windsurf, Codex, dll.), menempatkan keterampilan umum di .agents/skills/ akan memfasilitasi kolaborasi.
Untuk panggilan API dalam pengembangan Agen AI, disarankan untuk mengelolanya secara terpusat melalui APIYI apiyi.com, dengan satu Kunci API yang mencakup berbagai model.

Perbandingan Instruksi .agents dan .claude

Selain folder Skills, kedua sistem juga memiliki file instruksi proyek masing-masing.

Perbedaan CLAUDE.md dan AGENTS.md

Dimensi Perbandingan CLAUDE.md AGENTS.md
Alat yang Didukung Claude Code Claude Code, OpenAI Codex, Google Jules, Cursor, GitHub Copilot, dll.
Tingkat File Tingkat Pengguna (~/.claude/) → Tingkat Proyek (./) → Tingkat Subdirektori Tingkat Proyek (./) → Tingkat Subdirektori
Tumpang Tindih Lokal CLAUDE.local.md (gitignore) Tidak ada
Standar Formal Tidak ada (Dokumentasi Produk Anthropic) Ada (Agentic AI Foundation di bawah Linux Foundation)
Skala Ekosistem Berkembang (Digunakan oleh Next.js, LangChain, Deno, dll.) Skala Besar (n8n 178K bintang, llama.cpp 97K bintang, Bun 82K bintang)
Inisialisasi Perintah /init di dalam Claude Code Dibuat secara manual

Saran Praktis: Kedua file dapat hidup berdampingan. CLAUDE.md dapat berisi instruksi khusus Claude Code (seperti konfigurasi Hooks, aturan izin), sementara AGENTS.md dapat berisi konteks proyek umum untuk semua alat AI (seperti perintah build, konvensi pengkodean, deskripsi arsitektur).

Tinjauan Ekosistem File Pendukung .agents dan .claude

File/Direktori Sistem Terkait Kegunaan Dikirim ke Git
CLAUDE.md .claude Instruksi Proyek Claude Code Ya
CLAUDE.local.md .claude Instruksi Lokal Pribadi Tidak
.claude/settings.json .claude Izin, Hooks, MCP Ya
.claude/settings.local.json .claude Pengaturan Lokal Pribadi Tidak
AGENTS.md .agents Instruksi Proyek Agen Umum Ya
.agents/manifest.yaml .agents Registri Konfigurasi Ya
.agents/state/state.yaml .agents Status Eksekusi Lokal Tidak
.cursorrules Cursor Aturan Khusus Cursor Ya

Petunjuk: Sebuah penelitian dari ETH Zurich pada tahun 2026 menunjukkan bahwa file konteks yang dihasilkan AI terkadang dapat menurunkan kinerja Agen. Disarankan untuk menuliskannya secara manual dan membatasinya pada informasi non-eksplisit yang tidak dapat disimpulkan dari kode (rantai alat kustom, pola tidak konvensional, dll.).

agents-vs-claude-folder-skills-ai-agent-development-guide-id 图示

Pertanyaan Umum

P1: Bisakah Claude Code membaca Skill dari direktori .agents/skills/?

Saat ini, Claude Code secara native hanya mendeteksi dan memuat Skill dari direktori .claude/skills/. Konten di .agents/skills/ tidak dikenali secara otomatis. Komunitas telah mengajukan Isu di GitHub (#31005) yang meminta Claude Code untuk mendukung direktori .agents/. Jika Skill Anda perlu berfungsi di Claude Code, saat ini Anda harus meletakkannya di .claude/skills/.

P2: Apakah spesifikasi folder .agents sudah matang? Bisakah digunakan untuk proyek produksi?

Spesifikasi folder .agents/ (AGENTS-1 Spec) saat ini masih dalam proses pengembangan (Work In Progress), namun file AGENTS.md sudah banyak diadopsi – proyek open-source besar seperti n8n (178K stars), llama.cpp (97K stars), Bun (82K stars) menggunakannya. Disarankan untuk mengadopsi AGENTS.md terlebih dahulu sebagai file instruksi umum, dan menggunakan struktur direktori lengkap .agents/ setelah spesifikasi stabil.

P3: Bagaimana mengelola konfigurasi jika anggota tim menggunakan alat AI yang berbeda (Claude Code + Cursor)?

Disarankan untuk mengelola secara berlapis: 1) AGENTS.md berisi informasi proyek umum (perintah build, standar pengkodean), dibaca oleh semua alat; 2) CLAUDE.md berisi instruksi khusus Claude Code; 3) .cursorrules berisi aturan khusus Cursor. Skill umum diletakkan di .agents/skills/, dan Skill khusus alat diletakkan di direktori masing-masing. Kelola pemanggilan API AI tim secara terpadu melalui APIYI apiyi.com, satu platform mencakup semua model.

P4: Apa perbedaan format antara SKILL.md dan SKILL.yaml?

SKILL.md adalah format untuk Claude Code, menggunakan file Markdown dengan metadata YAML di bagian depan (frontmatter). Bagian instruksi ditulis dalam Markdown, sehingga lebih mudah dibaca manusia. SKILL.yaml adalah format untuk spesifikasi .agents/, yang sepenuhnya menggunakan struktur YAML, sehingga lebih mudah diurai oleh mesin. Informasi inti (nama, deskripsi, kondisi pemicu) sama, hanya formatnya yang berbeda.

Ringkasan

Perbedaan inti antara folder .agents dan .claude:

  1. Tujuan Berbeda: .claude/ adalah direktori konfigurasi proyek khusus untuk Claude Code, terintegrasi mendalam dengan semua fitur Claude Code; .agents/ adalah standar lintas alat umum di bawah Linux Foundation.
  2. Format Skill Berbeda: .claude/skills/ menggunakan SKILL.md (Markdown), dimuat secara native oleh Claude Code; .agents/skills/ menggunakan SKILL.yaml (YAML), dirancang agar independen dari alat.
  3. Dapat Hidup Berdampingan dan Saling Melengkapi: Fitur mendalam Claude Code (Hooks, sub-agen, izin) ditempatkan di .claude/, skill portabel umum ditempatkan di .agents/, dan instruksi dasar proyek menggunakan AGENTS.md.

Faktor kunci dalam memilih folder mana yang akan digunakan adalah komposisi rantai alat tim Anda dan kebutuhan portabilitas skill.

Disarankan untuk mengelola pemanggilan model dalam pengembangan AI Agent secara terpadu melalui APIYI apiyi.com. Platform ini menyediakan kuota gratis dan antarmuka terpadu untuk berbagai model, mendukung akses satu atap ke model-model utama seperti Claude, GPT, dan Gemini.

📚 Referensi

  1. Dokumentasi Resmi Claude Code Skills: Definisi, format, dan cara penggunaan Skills secara lengkap

    • Tautan: code.claude.com/docs/en/skills
    • Penjelasan: Pahami format SKILL.md, aturan pemicu, dan penerusan parameter

  2. Dokumentasi Claude Code Sub-agent: Definisi dan cara konfigurasi Sub-agent

    • Tautan: code.claude.com/docs/en/sub-agents
    • Penjelasan: Pahami format file di direktori .claude/agents/

  3. Situs Resmi AGENTS.md: Standar file instruksi Agent lintas alat

    • Tautan: agents.md
    • Penjelasan: Pahami spesifikasi penulisan AGENTS.md dan daftar alat yang didukung

  4. Spesifikasi Folder .agents/: Definisi struktur direktori lengkap AGENTS-1 Spec

    • Tautan: github.com/agentsfolder/spec
    • Penjelasan: Pahami desain manifest.yaml, modes, policies, dan scopes

  5. Pusat Dokumentasi APIYI: Manajemen pemanggilan API terpadu dalam pengembangan AI Agent

    • Tautan: docs.apiyi.com
    • Penjelasan: Mendukung antarmuka terpadu multi-model, cocok untuk skenario pengembangan Agent

Penulis: Tim Teknis APIYI
Diskusi Teknis: Silakan berdiskusi di kolom komentar, informasi lebih lanjut dapat diakses di pusat dokumentasi APIYI docs.apiyi.com

Try AI Large Model https://api.apiyi.com for free
Stable and reliable AI LM API aggregation service, Get 300 Millions Tokens for Free~

Similar Posts