Referensi manifest plugin

• Sebuah field: tabel Fields memberikan tipe setiap field, apakah diperlukan, defaultnya, dan apa yang diterima. Path rules mencakup awalan ./ dan containment untuk setiap path komponen
• Opsi userConfig atau entri channels: skema User configuration dan Channels
• ${CLAUDE_PLUGIN_ROOT} atau variabel lain yang dapat direferensikan plugin: Environment variables
• Di mana file setiap komponen berada: Standard layout
• Pesan dari claude plugin validate: halaman troubleshooting mencantumkan setiap pesan dengan perbaikannya dan tautan ke bagian relevan di halaman ini

​

Manifest file

{
  "name": "deploy-tools",
  "displayName": "Deploy Tools",
  "version": "1.2.0",
  "description": "Deployment commands, a review agent, and a status monitor",
  "author": {
    "name": "Example Team",
    "email": "dev@example.com",
    "url": "https://example.com"
  },
  "homepage": "https://example.com/docs/deploy-tools",
  "repository": "https://github.com/example/deploy-tools",
  "license": "MIT",
  "keywords": ["deployment", "ci"],
  "defaultEnabled": true,
  "dependencies": ["secrets-vault"],
  "metadata": { "catalogId": "cat-123" },
  "skills": ["./extra-skills/"],
  "commands": {
    "status": {
      "source": "./commands/status.md",
      "description": "Show the current deployment status"
    },
    "about": {
      "content": "Explain what the deploy-tools plugin provides.",
      "description": "Describe this plugin"
    }
  },
  "agents": ["./agents/reviewer.md"],
  "hooks": "./config/extra-hooks.json",
  "mcpServers": {
    "deploy-api": {
      "command": "node",
      "args": ["${CLAUDE_PLUGIN_ROOT}/server.js"]
    }
  },
  "lspServers": "./.lsp.json",
  "outputStyles": "./styles/",
  "experimental": {
    "themes": "./themes/",
    "monitors": "./config/monitors.json"
  },
  "userConfig": {
    "api_token": {
      "type": "string",
      "title": "API token",
      "description": "Token for the deployment API",
      "sensitive": true
    }
  }
}

​

Unrecognized fields

• Top-level fields: field dihapus dan plugin dimuat. claude plugin validate melaporkan setiap field tingkat atas yang tidak dikenali sebagai peringatan
• Strict objects: opsi userConfig, entri channels, config lspServers, dan entri monitors bersifat ketat. Kunci yang tidak diketahui di dalamnya adalah kesalahan, dan plugin tidak dimuat

​

Validate the manifest

claude plugin validate ./my-plugin

• Validation passed: manifest dimuat
• Validation passed with warnings: manifest dimuat, tetapi validator menemukan sesuatu untuk diperbaiki, seperti field tingkat atas yang tidak diketahui yang Claude Code hapus, name yang bukan kebab-case, atau version, description, atau author yang hilang. Lewatkan --strict untuk mengubah peringatan menjadi kegagalan di CI
• Validation failed: manifest memiliki ketidakcocokan tipe, path yang hilang atau keluar dari root plugin, atau kunci yang tidak diketahui di dalam opsi userConfig, entri channels, config lspServers, atau entri monitors. Claude Code melaporkan masalah yang sama saat memuat plugin

​

Fields

​

name

​

displayName

​

version

​

metadata

​

defaultEnabled

​

dependencies

​

settings

​

Component path forms

​

Path-only fields

{
  "agents": ["./custom-agents/reviewer.md", "./custom-agents/tester.md"],
  "skills": ["./extra-skills/", "."],
  "outputStyles": "./styles/"
}

​

commands

{
  "commands": {
    "status": { "source": "./commands/status.md", "argumentHint": "[env]" },
    "about": { "content": "Explain what this plugin provides." }
  }
}

​

hooks

{
  "hooks": [
    "./config/extra-hooks.json",
    {
      "PostToolUse": [
        {
          "matcher": "Write|Edit",
          "hooks": [
            { "type": "command", "command": "\"${CLAUDE_PLUGIN_ROOT}\"/scripts/format.sh" }
          ]
        }
      ]
    }
  ]
}

​

mcpServers

​

lspServers

{
  "lspServers": {
    "go": {
      "command": "gopls",
      "args": ["serve"],
      "extensionToLanguage": { ".go": "go" }
    }
  }
}

​

monitors

{
  "experimental": {
    "monitors": [
      {
        "name": "deploy-status",
        "command": "\"${CLAUDE_PLUGIN_ROOT}\"/scripts/poll-deploy.sh",
        "description": "Deployment status changes",
        "when": "on-skill-invoke:deploy"
      }
    ]
  }
}

​

Path rules

• skills: juga menerima ".". Baik "." maupun "./" menunjukkan root plugin. Sebelum v2.1.221, "." gagal validasi manifest, jadi gunakan "./" saat plugin harus dimuat di versi sebelumnya
• mcpServers: juga menerima URL bundle https://

​

Containment and existence

• Containment: path yang diselesaikan di luar root plugin tidak dimuat, dan tab Errors /plugin menampilkan <component> path escapes plugin directory: <path>. Path yang berisi .. adalah kasus biasa, dan claude plugin validate melaporkannya sebagai Path contains ".." which could be a path traversal attempt
• Existence: path yang tidak ada tidak dimuat, dan tab Errors /plugin menampilkan <component> path not found: <path>. claude plugin validate melaporkannya sebagai Path not found

​

How each key combines with its default location

• Menggantikan default: commands, agents, outputStyles, workflows, experimental.themes, experimental.monitors. Saat Anda menetapkan commands, direktori default commands/ tidak dipindai. Untuk menyimpan default dan menambah lebih banyak, daftarkan secara eksplisit: "commands": ["./commands/", "./extras/"]
• Menambah default: skills. Direktori skills/ masih dipindai, dan direktori yang terdaftar dimuat bersama dengannya
• Menggabungkan: hooks, mcpServers, lspServers. File default dimuat terlebih dahulu, dan apa yang manifest deklarasikan digabungkan ke dalamnya, seperti dijelaskan di bawah Component path forms

​

User configuration

{
  "userConfig": {
    "api_endpoint": {
      "type": "string",
      "title": "API endpoint",
      "description": "Your team's API endpoint"
    },
    "api_token": {
      "type": "string",
      "title": "API token",
      "description": "API authentication token",
      "sensitive": true
    }
  }
}

​

Limit a field to fixed options

{
  "userConfig": {
    "tone": {
      "type": "string",
      "title": "Tone",
      "description": "Voice for generated replies",
      "options": ["neutral", "warm", "formal"],
      "default": "neutral"
    }
  }
}

​

Where values are stored

​

Reference a saved value

• ${user_config.KEY}: disubstitusi dalam config server MCP, config server LSP, exec-form hook args, dan konten skill dan agent. Dalam konten skill dan agent, hanya nilai non-sensitif yang disubstitusi, dan nilai sensitif di sana menjadi placeholder
• CLAUDE_PLUGIN_OPTION_<KEY>: diekspor ke proses hook untuk setiap opsi, dengan <KEY> huruf besar. Hook bentuk shell membaca $CLAUDE_PLUGIN_OPTION_API_TOKEN untuk api_token

​

Fields that run through a shell

​

Channels

{
  "mcpServers": {
    "telegram": {
      "command": "node",
      "args": ["${CLAUDE_PLUGIN_ROOT}/server.js"],
      "env": { "BOT_TOKEN": "${user_config.bot_token}" }
    }
  },
  "channels": [
    {
      "server": "telegram",
      "displayName": "Telegram",
      "userConfig": {
        "bot_token": {
          "type": "string",
          "title": "Bot token",
          "description": "Telegram bot token",
          "sensitive": true
        }
      }
    }
  ]
}

​

Environment variables

​

Where each variable resolves

​

Quoting and path separators

• Hook commands: gunakan exec form dengan args sehingga setiap path adalah satu argumen tanpa quoting
• Shell-form hooks dan monitor commands: bungkus variabel dalam tanda kutip ganda sehingga path dengan spasi tetap satu kata

{
  "hooks": {
    "PostToolUse": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "\"${CLAUDE_PLUGIN_ROOT}\"/scripts/process.sh"
          }
        ]
      }
    ]
  }
}

​

Standard layout

deploy-tools/
├── .claude-plugin/
│   └── plugin.json
├── skills/
│   └── deploy/
│       └── SKILL.md
├── commands/
│   └── status.md
├── agents/
│   └── reviewer.md
├── hooks/
│   └── hooks.json
├── monitors/
│   └── monitors.json
├── output-styles/
│   └── terse.md
├── themes/
│   └── dracula.json
├── workflows/
│   └── release-audit.js
├── bin/
│   └── deploy-tool
├── scripts/
│   └── format.sh
├── settings.json
├── .mcp.json
└── .lsp.json

​

Marketplace entries and the manifest

​

How entry fields combine with plugin.json

• Tidak ada plugin.json: entri adalah manifest, terlepas dari strict. Entry hooks dimuat hanya dalam bentuk objek inline. Untuk path file atau array di sana, tab Errors /plugin menampilkan error not yet supported in a marketplace entry
• plugin.json ada, strict tidak diatur atau true: Claude Code memuat manifest dan menambahkan commands, agents, skills, outputStyles, dan themes entri ke dalamnya. Untuk hooks, matcher entri untuk event menggantikan matcher manifest untuk event yang sama, dan event hanya manifest yang mendeklarasikan tetap miliknya
• plugin.json ada, strict: false: entri yang mendeklarasikan salah satu dari commands, agents, skills, hooks, outputStyles, atau themes adalah konflik, dan plugin gagal dimuat dengan Plugin <name> has conflicting manifests

​

Metadata precedence

• defaultEnabled dan display fields: defaultEnabled entri dan display fields-nya seperti displayName menimpakan manifest
• version: version manifest menimpakan entri
• name: saat entri mencantumkan plugin di bawah name berbeda dari manifest, enabledPlugins menggunakan nama entri, dan komponen di-namespace di bawah nama manifest

​

Next steps

• Tambahkan komponen ke plugin: apa yang dilakukan setiap komponen saat runtime, dengan contoh yang divalidasi
• Referensi marketplace: field entri yang dapat ditetapkan marketplace untuk plugin Anda
• Referensi perintah plugin: flag dan output claude plugin validate
• Troubleshoot plugins: setiap pesan validasi dengan perbaikannya