plugin-architecture

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Plugin Architecture

插件架构

Quick Start

快速入门

A well-structured plugin follows this minimal layout:

my-plugin/
├── .claude-plugin/
│   └── plugin.json              # Required manifest
├── agents/
│   └── agent.md                 # Agent definition
├── skills/
│   └── skill-name/SKILL.md      # Skill definition
├── commands/
│   └── command.md               # Command definition
├── hooks/
│   └── hooks.json               # Automation hooks
└── README.md

结构清晰的插件遵循以下最简布局：

my-plugin/
├── .claude-plugin/
│   └── plugin.json              # Required manifest
├── agents/
│   └── agent.md                 # Agent definition
├── skills/
│   └── skill-name/SKILL.md      # Skill definition
├── commands/
│   └── command.md               # Command definition
├── hooks/
│   └── hooks.json               # Automation hooks
└── README.md

Plugin Manifest (plugin.json)

插件清单（plugin.json）

The manifest defines what your plugin does and what it contains.

json

{
  "name": "my-plugin",
  "version": "1.0.0",
  "description": "What my plugin does",
  "author": "Your Name",
  "license": "MIT",
  "repository": "https://github.com/user/repo",
  "agents": [
    {
      "name": "agent-id",
      "description": "What it does",
      "file": "agents/agent.md"
    }
  ],
  "commands": [
    {
      "name": "command",
      "file": "commands/command.md",
      "description": "What it does"
    }
  ],
  "skills": [
    {
      "name": "skill-id",
      "file": "skills/skill-id/SKILL.md"
    }
  ],
  "hooks": {
    "file": "hooks/hooks.json"
  }
}

清单用于定义插件的功能和包含的内容。

json

{
  "name": "my-plugin",
  "version": "1.0.0",
  "description": "What my plugin does",
  "author": "Your Name",
  "license": "MIT",
  "repository": "https://github.com/user/repo",
  "agents": [
    {
      "name": "agent-id",
      "description": "What it does",
      "file": "agents/agent.md"
    }
  ],
  "commands": [
    {
      "name": "command",
      "file": "commands/command.md",
      "description": "What it does"
    }
  ],
  "skills": [
    {
      "name": "skill-id",
      "file": "skills/skill-id/SKILL.md"
    }
  ],
  "hooks": {
    "file": "hooks/hooks.json"
  }
}

Manifest Rules

清单规则

name: lowercase-hyphens, 10-50 chars
version: semantic (MAJOR.MINOR.PATCH)
description: 50-256 characters
agents: array of agent definitions
commands: array of command definitions
skills: array of skill definitions
hooks: optional, points to hooks.json

name：小写连字符格式，长度10-50个字符
version：语义化版本号（主版本.次版本.修订版本）
description：长度50-256个字符
agents：Agent定义数组
commands：命令定义数组
skills：Skill定义数组
hooks：可选字段，指向hooks.json

Agent Structure

Agent结构

Each agent is a markdown file with YAML frontmatter:

markdown

---
description: What this agent does (max 1024 chars)
capabilities:
  - "Capability 1"
  - "Capability 2"
  - "Capability 3"
---

每个Agent都是带有YAML前置元数据的Markdown文件：

markdown

---
description: What this agent does (max 1024 chars)
capabilities:
  - "Capability 1"
  - "Capability 2"
  - "Capability 3"
---

Agent Name

[Detailed content about what agent does]

When to Use

Use this agent when:

Need 1
Need 2
Need 3

undefined

Use this agent when:

Need 1
Need 2
Need 3

undefined

Naming Convention

命名规范

01-primary-agent.md
02-secondary-agent.md
03-tertiary-agent.md

01-primary-agent.md
02-secondary-agent.md
03-tertiary-agent.md

Skill Structure

Skill结构

Skills provide reusable knowledge and examples.

skills/
├── skill-one/
│   ├── SKILL.md              # Always named SKILL.md
│   └── resources/            # Optional: additional files
│       ├── example.py
│       └── reference.md
└── skill-two/
    └── SKILL.md

Skills提供可复用的知识和示例。

skills/
├── skill-one/
│   ├── SKILL.md              # Always named SKILL.md
│   └── resources/            # Optional: additional files
│       ├── example.py
│       └── reference.md
└── skill-two/
    └── SKILL.md

SKILL.md Format

SKILL.md格式

markdown

---
name: skill-unique-id
description: "What skill teaches (max 1024 chars)"
---

markdown

---
name: skill-unique-id
description: "What skill teaches (max 1024 chars)"
---

Skill Name

Quick Start

[Working code - copy-paste ready]

Core Concepts

Concept 1

[Explanation with code]

Concept 2

[More examples]

Advanced Topics

[Expert-level content]

Real-World Projects

[Practical applications]

undefined

[Practical applications]

undefined

Command Structure

命令结构

Commands are entry points for users:

commands/
├── create.md
├── design.md
├── test.md
└── deploy.md

命令是用户的入口点：

commands/
├── create.md
├── design.md
├── test.md
└── deploy.md

Command Format

命令格式

markdown

undefined

markdown

undefined

/command-name - Brief Description

What This Does

[Clear explanation]

Usage

/command-name [options]

/command-name [options]

Options

Option	Description
`--flag`	What it does

Option	Description
`--flag`	What it does

Example

[Sample output]

Next Steps

[What to do next]

undefined

[What to do next]

undefined

Hook Configuration

钩子配置

Hooks automate plugin behavior:

json

{
  "hooks": [
    {
      "id": "hook-id",
      "name": "Hook Name",
      "event": "event-type",
      "condition": "condition",
      "action": "action-name",
      "enabled": true
    }
  ]
}

钩子用于自动化插件行为：

json

{
  "hooks": [
    {
      "id": "hook-id",
      "name": "Hook Name",
      "event": "event-type",
      "condition": "condition",
      "action": "action-name",
      "enabled": true
    }
  ]
}

Architectural Patterns

架构模式

Single Responsibility

单一职责原则

Agent 1: Domain A only
Agent 2: Domain B only
Agent 3: Domain C only

Agent 1: Domain A only
Agent 2: Domain B only
Agent 3: Domain C only

Layered Architecture

分层架构

Commands (User interface)
    ↓
Agents (Logic & guidance)
    ↓
Skills (Knowledge & examples)
    ↓
Hooks (Automation)

Commands (User interface)
    ↓
Agents (Logic & guidance)
    ↓
Skills (Knowledge & examples)
    ↓
Hooks (Automation)

Agent Collaboration

Agent协作模式

Agent A → asks → Agent B
  ↓
Links to shared skills
  ↓
Agent C for final review

Agent A → asks → Agent B
  ↓
Links to shared skills
  ↓
Agent C for final review

File Organization Best Practices

文件组织最佳实践

✅ Logical grouping
├─ All agents together
├─ All skills organized
├─ All commands grouped
└─ Config centralized

✅ Clear naming
├─ agents/01-primary.md
├─ agents/02-secondary.md
├─ skills/skill-one/SKILL.md
└─ commands/action.md

✅ Scalable structure
├─ Easy to add agents
├─ Simple to extend skills
├─ Clear command naming
└─ Organized hooks

✅ Logical grouping
├─ All agents together
├─ All skills organized
├─ All commands grouped
└─ Config centralized

✅ Clear naming
├─ agents/01-primary.md
├─ agents/02-secondary.md
├─ skills/skill-one/SKILL.md
└─ commands/action.md

✅ Scalable structure
├─ Easy to add agents
├─ Simple to extend skills
├─ Clear command naming
└─ Organized hooks

Scaling Your Plugin

插件扩展指南

From Simple to Complex

从简单到复杂

Stage 1: 1 agent, 2 skills, 1 command

Minimal viable plugin

Stage 2: 3 agents, 5 skills, 3 commands

Feature-rich plugin

Stage 3: 5-7 agents, 10+ skills, 5+ commands

Enterprise plugin

阶段1：1个Agent，2个Skill，1个命令

Minimal viable plugin

阶段2：3个Agent，5个Skill，3个命令

Feature-rich plugin

阶段3：5-7个Agent，10+个Skill，5+个命令

Enterprise plugin

Common Mistakes

常见错误

❌ Unclear structure → Use recommended layout ❌ Mixed concerns → One agent = one domain ❌ Missing manifest → Always include plugin.json ❌ Bad naming → Use lowercase-hyphens ❌ No documentation → Document everything

Use this skill when:

Designing plugin structure
Creating plugin.json
Organizing agents and skills
Planning plugin growth

Status: ✅ Production Ready | SASMP: v1.3.0 | Bonded Agent: 01-plugin-architect

❌ 结构不清晰 → 使用推荐的布局 ❌ 职责混合 → 一个Agent只负责一个领域 ❌ 缺少清单文件 → 务必包含plugin.json ❌ 命名不规范 → 使用小写连字符格式 ❌ 无文档说明 → 所有内容都需要文档化

适用场景：

设计插件结构
创建plugin.json
组织Agent和Skill
规划插件的扩展

状态：✅ 生产就绪 | SASMP：v1.3.0 | 绑定Agent：01-plugin-architect