plugin-dev

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Plugin Development for Claude Code & OpenCode

Claude Code & OpenCode 插件开发

Critical Importance

至关重要性

Creating high-quality plugins is critical to your development workflow's long-term success. Plugins are used repeatedly by yourself and others. Design flaws, poor documentation, or broken functionality compound over time and across users. A well-designed plugin becomes a trusted tool used daily; a poorly designed plugin becomes abandoned technical debt. Invest time in architecture, testing, and documentation—the returns multiply across all future uses.
创建高质量插件对您开发工作流的长期成功至关重要。 插件会被您和他人反复使用。设计缺陷、文档不完善或功能故障会随着时间推移和用户增多而不断放大。设计精良的插件会成为日常依赖的可靠工具;而设计糟糕的插件则会沦为无人问津的技术债务。请投入时间在架构、测试和文档上——这些投入会在未来的所有使用场景中带来成倍的回报。

Systematic Approach

系统化开发方法

** approach plugin development systematically.** Plugins require careful planning: understand the problem, design the API, implement incrementally, test thoroughly, and document comprehensively. Don't rush to code—clarify requirements, define interfaces, and consider edge cases first. Build iteratively, validate frequently, and refactor continuously. Every design decision impacts maintainability and extensibility.
请采用系统化方法进行插件开发。 插件开发需要周密规划:理解问题、设计API、增量实现、全面测试以及详尽文档。不要急于编码——先明确需求、定义接口并考虑边缘情况。采用迭代构建、频繁验证、持续重构的方式。每一个设计决策都会影响可维护性和可扩展性。

The Challenge

核心挑战

The create a plugin that balances specificity with flexibility perfectly, but if you can:
  • Your plugin will be a joy to use and extend
  • Others will build on top of your work
  • The plugin will remain useful as needs evolve
  • You'll establish patterns for future plugin development
The challenge is designing plugins that solve specific problems while staying flexible enough for future use cases. Can you create focused, opinionated tools that don't paint yourself into corners?
理想状态是创建一款完美平衡针对性与灵活性的插件,但如果能做到:
  • 您的插件将易于使用和扩展
  • 其他人会基于您的成果进行二次开发
  • 插件会随着需求演变持续保持实用性
  • 您将为未来的插件开发建立可复用的模式
核心挑战在于设计既能解决特定问题,又能灵活适配未来使用场景的插件。您能否创建出目标明确、设计独到的工具,同时避免陷入无法拓展的困境?

Plugin Confidence Assessment

插件信心评估

After completing or reviewing plugin development, rate your confidence from 0.0 to 1.0:
  • 0.8-1.0: Plugin well-architected, fully tested, thoroughly documented, follows platform conventions
  • 0.5-0.8: Plugin functional but missing some tests or documentation, some technical debt
  • 0.2-0.5: Plugin works but design unclear, minimal testing, poor documentation
  • 0.0-0.2: Plugin incomplete or broken, unclear purpose, significant rework needed
Identify uncertainty areas: Is the plugin's purpose clear? Are there edge cases unhandled? Will the plugin work as requirements change? What's the maintenance burden?
完成或评审插件开发后,请从 0.0 到 1.0 为您的信心评分:
  • 0.8-1.0:插件架构优良,测试全面,文档详尽,符合平台规范
  • 0.5-0.8:插件功能可用,但缺少部分测试或文档,存在一定技术债务
  • 0.2-0.5:插件可运行,但设计模糊,测试不足,文档质量差
  • 0.0-0.2:插件未完成或功能损坏,用途不明确,需要大量返工
请识别不确定的领域:插件的用途是否清晰?是否有未处理的边缘情况?当需求变化时插件能否正常工作?维护成本如何?

Overview

概述

The ai-eng-system supports extension development for both Claude Code and OpenCode through a unified content system with automated transformation. Understanding this system enables creating well-organized, maintainable extensions that integrate seamlessly with both platforms.
ai-eng-system通过统一的内容系统和自动化转换功能,支持为Claude Code和OpenCode开发扩展。理解该系统有助于创建结构清晰、易于维护且能无缝集成到两个平台的扩展。

Extension Types

扩展类型

TypeClaude CodeOpenCodeShared Format
Commands✅ YAML frontmatter✅ Table formatYAML frontmatter
Agents✅ YAML frontmatter✅ Table formatYAML frontmatter
Skills✅ Same format✅ Same formatSKILL.md
Hooks✅ hooks.json✅ Plugin eventsPlatform-specific
Custom Tools❌ (use MCP)✅ tool() helperOpenCode only
MCP Servers✅ .mcp.json✅ Same formatSame format
类型Claude CodeOpenCode共享格式
命令✅ YAML frontmatter✅ 表格格式YAML frontmatter
Agent✅ YAML frontmatter✅ 表格格式YAML frontmatter
Skill✅ 相同格式✅ 相同格式SKILL.md
钩子✅ hooks.json✅ 插件事件平台特定
自定义工具❌(使用MCP)✅ tool() 辅助函数仅OpenCode
MCP服务器✅ .mcp.json✅ 相同格式相同格式

Development Approaches

开发方式

1. Canonical Development (Recommended)

1. 标准开发(推荐)

Create content in
content/
directory, let build.ts transform to platform formats:
content/
├── commands/my-command.md  → dist/.claude-plugin/commands/
│                           → dist/.opencode/command/ai-eng/
└── agents/my-agent.md      → dist/.claude-plugin/agents/
                            → dist/.opencode/agent/ai-eng/
content/
目录中创建内容,通过build.ts转换为平台特定格式:
content/
├── commands/my-command.md  → dist/.claude-plugin/commands/
│                           → dist/.opencode/command/ai-eng/
└── agents/my-agent.md      → dist/.claude-plugin/agents/
                            → dist/.opencode/agent/ai-eng/

2. Platform-Specific Development

2. 平台特定开发

Create directly in platform directories:
  • Claude Code:
    .claude/commands/
    ,
    .claude-plugin/
  • OpenCode:
    .opencode/command/
    ,
    .opencode/agent/
直接在平台专属目录中创建:
  • Claude Code:
    .claude/commands/
    ,
    .claude-plugin/
  • OpenCode:
    .opencode/command/
    ,
    .opencode/agent/

3. Global vs Project-Local

3. 全局 vs 项目本地

LocationClaude CodeOpenCode
Project
.claude/
.opencode/
Global
~/.claude/
~/.config/opencode/
位置Claude CodeOpenCode
项目本地
.claude/
.opencode/
全局
~/.claude/
~/.config/opencode/

Quick Reference

快速参考

Command Frontmatter

命令前置元数据

Canonical (content/):
yaml
---
name: my-command
description: What this command does
agent: build           # Optional: which agent handles this
subtask: true          # Optional: run as subtask
temperature: 0.3      # Optional: temperature
tools:                 # Optional: tool restrictions
  read: true
  write: true
---
Claude Code Output: Same format (YAML frontmatter)
OpenCode Output: Table format
markdown
| description | agent |
|---|---|
| Description here | build |
标准格式(content/目录下):
yaml
---
name: my-command
description: What this command does
agent: build           # 可选:处理该命令的Agent
subtask: true          # 可选:作为子任务运行
temperature: 0.3      # 可选:温度参数
tools:                 # 可选:工具限制
  read: true
  write: true
---
Claude Code输出格式: 相同格式(YAML frontmatter)
OpenCode输出格式: 表格格式
markdown
| description | agent |
|---|---|
| Description here | build |

Agent Frontmatter

Agent前置元数据

Canonical (content/):
yaml
---
name: my-agent
description: Use this agent when... <example>...</example>
mode: subagent
color: cyan
temperature: 0.3
tools:
  read: true
  write: true
---
Claude Code Output: Same format (YAML frontmatter)
OpenCode Output: Table format
markdown
| description | mode |
|---|---|
| Description here | subagent |
标准格式(content/目录下):
yaml
---
name: my-agent
description: Use this agent when... <example>...</example>
mode: subagent
color: cyan
temperature: 0.3
tools:
  read: true
  write: true
---
Claude Code输出格式: 相同格式(YAML frontmatter)
OpenCode输出格式: 表格格式
markdown
| description | mode |
|---|---|
| Description here | subagent |

Skill Structure

Skill结构

Both platforms use identical format:
skill-name/
├── SKILL.md (required)
│   ├── YAML frontmatter (name, description)
│   └── Markdown body (1,000-3,000 words)
└── Bundled Resources (optional)
    ├── references/       # Detailed documentation
    ├── examples/         # Working code
    └── scripts/          # Utility scripts
两个平台使用完全相同的格式:
skill-name/
├── SKILL.md(必填)
│   ├── YAML frontmatter(名称、描述)
│   └── Markdown正文(1000-3000字)
└── 捆绑资源(可选)
    ├── references/       # 详细文档
    ├── examples/         # 可运行代码
    └── scripts/          # 实用脚本

OpenCode Custom Tools

OpenCode自定义工具

Use TypeScript with
tool()
helper:
typescript
import { tool } from "@opencode-ai/plugin"

export default tool({
  description: "Tool description",
  args: {
    param: tool.schema.string().describe("Parameter description"),
  },
  async execute(args, context) {
    // Tool implementation
    return result
  },
})
使用TypeScript和
tool()
辅助函数:
typescript
import { tool } from "@opencode-ai/plugin"

export default tool({
  description: "Tool description",
  args: {
    param: tool.schema.string().describe("Parameter description"),
  },
  async execute(args, context) {
    // Tool implementation
    return result
  },
})

Directory Locations

目录位置

For Development in ai-eng-system

在ai-eng-system中开发

ai-eng-system/
├── content/
│   ├── commands/              # Add new commands here
│   └── agents/                # Add new agents here
├── skills/
│   └── plugin-dev/           # This skill
└── build.ts                   # Transforms to both platforms
ai-eng-system/
├── content/
│   ├── commands/              # 在此添加新命令
│   └── agents/                # 在此添加新Agent
├── skills/
│   └── plugin-dev/           # 本Skill
└── build.ts                   # 转换为两个平台的格式

For User Projects

对于用户项目

Project-local:
  • Claude Code:
    .claude/commands/
    ,
    .claude-plugin/
  • OpenCode:
    .opencode/command/
    ,
    .opencode/agent/
Global:
  • Claude Code:
    ~/.claude/commands/
    ,
    ~/.claude-plugin/
  • OpenCode:
    ~/.config/opencode/command/
    ,
    ~/.config/opencode/agent/
项目本地:
  • Claude Code:
    .claude/commands/
    ,
    .claude-plugin/
  • OpenCode:
    .opencode/command/
    ,
    .opencode/agent/
全局:
  • Claude Code:
    ~/.claude/commands/
    ,
    ~/.claude-plugin/
  • OpenCode:
    ~/.config/opencode/command/
    ,
    ~/.config/opencode/agent/

Platform-Specific Features

平台特定功能

Claude Code

Claude Code

Components:
  • Commands with YAML frontmatter
  • Agents with YAML frontmatter
  • Skills with SKILL.md format
  • Hooks via
    hooks/hooks.json
  • MCP servers via
    .mcp.json
Manifest:
.claude-plugin/plugin.json
json
{
  "name": "plugin-name",
  "version": "1.0.0",
  "description": "Brief description",
  "commands": ["./commands/*"],
  "mcpServers": "./.mcp.json"
}
组件:
  • 带YAML frontmatter的命令
  • 带YAML frontmatter的Agent
  • SKILL.md格式的Skill
  • 通过
    hooks/hooks.json
    实现的钩子
  • 通过
    .mcp.json
    实现的MCP服务器
清单文件:
.claude-plugin/plugin.json
json
{
  "name": "plugin-name",
  "version": "1.0.0",
  "description": "Brief description",
  "commands": ["./commands/*"],
  "mcpServers": "./.mcp.json"
}

OpenCode

OpenCode

Components:
  • Commands with table format
  • Agents with table format
  • Skills via opencode-skills plugin
  • Custom tools with TypeScript
  • Plugin events via TypeScript
Plugin:
.opencode/plugin/plugin.ts
typescript
import { Plugin } from "@opencode-ai/plugin"

export default (async ({ client, project, directory, worktree, $ }) => {
  return {
    // Plugin hooks here
  }
}) satisfies Plugin
组件:
  • 表格格式的命令
  • 表格格式的Agent
  • 通过opencode-skills插件实现的Skill
  • TypeScript编写的自定义工具
  • TypeScript实现的插件事件
插件文件:
.opencode/plugin/plugin.ts
typescript
import { Plugin } from "@opencode-ai/plugin"

export default (async ({ client, project, directory, worktree, $ }) => {
  return {
    // Plugin hooks here
  }
}) satisfies Plugin

Development Workflow

开发工作流

1. Create Component

1. 创建组件

Use plugin-dev commands:
  • /ai-eng/create-agent
    - Create new agent
  • /ai-eng/create-command
    - Create new command
  • /ai-eng/create-skill
    - Create new skill
  • /ai-eng/create-tool
    - Create new custom tool
使用plugin-dev命令:
  • /ai-eng/create-agent
    - 创建新Agent
  • /ai-eng/create-command
    - 创建新命令
  • /ai-eng/create-skill
    - 创建新Skill
  • /ai-eng/create-tool
    - 创建新自定义工具

2. Build

2. 构建

bash
cd ai-eng-system
bun run build              # Build all platforms
bun run build --watch        # Watch mode
bun run build --validate      # Validate content
bash
cd ai-eng-system
bun run build              # 构建所有平台
bun run build --watch        # 监听模式
bun run build --validate      # 验证内容

3. Test

3. 测试

Claude Code:
bash
claude plugin add https://github.com/v1truv1us/ai-eng-system
OpenCode:
bash
undefined
Claude Code:
bash
claude plugin add https://github.com/v1truv1us/ai-eng-system
OpenCode:
bash
undefined

Project-local

项目本地

./setup.sh
./setup.sh

Global

全局

./setup-global.sh
undefined
./setup-global.sh
undefined

Best Practices

最佳实践

Content Quality

内容质量

  • Use third-person in skill descriptions
  • Write commands/agents FOR Claude, not to user
  • Include specific trigger phrases
  • Follow progressive disclosure for skills
  • Skill描述使用第三人称
  • 为Claude编写命令/Agent,而非直接面向用户
  • 包含特定触发短语
  • Skill遵循渐进式披露原则

File Organization

文件组织

  • One component per file
  • Clear naming conventions (kebab-case)
  • Proper frontmatter validation
  • 每个文件对应一个组件
  • 清晰的命名规范(短横线分隔命名)
  • 正确的前置元数据验证

Cross-Platform Compatibility

跨平台兼容性

  • Use canonical format in
    content/
  • Test build output for both platforms
  • Document platform differences
  • content/
    目录中使用标准格式
  • 测试两个平台的构建输出
  • 记录平台差异

Security

安全

  • No hardcoded credentials
  • Use HTTPS/WSS for external connections
  • Validate user inputs
  • Follow principle of least privilege
  • 不硬编码凭证
  • 外部连接使用HTTPS/WSS
  • 验证用户输入
  • 遵循最小权限原则

Additional Resources

额外资源

References

参考文档

  • references/claude-code-plugins.md
    - Claude Code specifics
  • references/opencode-plugins.md
    - OpenCode specifics
  • references/command-format.md
    - Command syntax guide
  • references/agent-format.md
    - Agent configuration guide
  • references/skill-format.md
    - Skills specification
  • references/opencode-tools.md
    - Custom tool development
  • references/claude-code-plugins.md
    - Claude Code专属细节
  • references/opencode-plugins.md
    - OpenCode专属细节
  • references/command-format.md
    - 命令语法指南
  • references/agent-format.md
    - Agent配置指南
  • references/skill-format.md
    - Skill规范
  • references/opencode-tools.md
    - 自定义工具开发

Examples

示例

Study existing components in ai-eng-system:
  • content/commands/plan.md
    - Command structure
  • content/agents/architect-advisor.md
    - Agent structure
  • skills/prompting/incentive-prompting/SKILL.md
    - Skill structure
研究ai-eng-system中已有的组件:
  • content/commands/plan.md
    - 命令结构示例
  • content/agents/architect-advisor.md
    - Agent结构示例
  • skills/prompting/incentive-prompting/SKILL.md
    - Skill结构示例

Troubleshooting

故障排除

Build Issues

构建问题

  • Run
    bun run build --validate
    to check content
  • Check file permissions in output directories
  • Verify YAML frontmatter syntax
  • 运行
    bun run build --validate
    检查内容
  • 检查输出目录的文件权限
  • 验证YAML前置元数据语法

Platform Testing

平台测试

  • Test commands in both Claude Code and OpenCode
  • Verify agents trigger correctly
  • Check skills load via opencode-skills plugin
  • 在Claude Code和OpenCode中测试命令
  • 验证Agent能否正确触发
  • 检查Skill是否通过opencode-skills插件加载

Common Errors

常见错误

  • Missing required frontmatter fields
  • Incorrect directory structure
  • Invalid YAML syntax
  • Wrong file permissions
  • 缺少必填的前置元数据字段
  • 目录结构不正确
  • YAML语法无效
  • 文件权限错误

Integration with Ferg Engineering

与Ferg Engineering的集成

The plugin-dev system integrates seamlessly with existing ai-eng-system components:
plugin-dev系统与现有ai-eng-system组件无缝集成:

Existing Commands

现有命令

  • /ai-eng/plan
    - Implementation planning
  • /ai-eng/review
    - Code review
  • /ai-eng/work
    - Task execution
  • /ai-eng/plan
    - 实现规划
  • /ai-eng/review
    - 代码评审
  • /ai-eng/work
    - 任务执行

Existing Agents

现有Agent

  • ai-eng/architect-advisor
    - Architecture guidance
  • ai-eng/frontend-reviewer
    - Frontend review
  • ai-eng/seo-specialist
    - SEO optimization
  • ai-eng/architect-advisor
    - 架构指导
  • ai-eng/frontend-reviewer
    - 前端评审
  • ai-eng/seo-specialist
    - SEO优化

Plugin-Dev Commands

Plugin-Dev专属命令

  • /ai-eng/create-plugin
    - Full plugin development workflow
  • /ai-eng/create-agent
    - Quick agent creation
  • /ai-eng/create-command
    - Quick command creation
  • /ai-eng/create-skill
    - Quick skill creation
  • /ai-eng/create-tool
    - Quick tool creation
All use the same quality standards and research-backed prompting techniques.
  • /ai-eng/create-plugin
    - 完整插件开发工作流
  • /ai-eng/create-agent
    - 快速创建Agent
  • /ai-eng/create-command
    - 快速创建命令
  • /ai-eng/create-skill
    - 快速创建Skill
  • /ai-eng/create-tool
    - 快速创建自定义工具
所有组件均采用相同的质量标准和基于研究的提示技术。