Plugin Development for Claude Code & OpenCode

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.

Extension Types

Type	Claude Code	OpenCode	Shared Format
Commands	✅ YAML frontmatter	✅ Table format	YAML frontmatter
Agents	✅ YAML frontmatter	✅ Table format	YAML frontmatter
Skills	✅ Same format	✅ Same format	SKILL.md
Hooks	✅ hooks.json	✅ Plugin events	Platform-specific
Custom Tools	❌ (use MCP)	✅ tool() helper	OpenCode only
MCP Servers	✅ .mcp.json	✅ Same format	Same format

Development Approaches

1. Canonical Development (Recommended)

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/

2. Platform-Specific Development

Create directly in platform directories:

• Claude Code: .claude/commands/, .claude-plugin/
• OpenCode: .opencode/command/, .opencode/agent/

3. Global vs Project-Local

Location	Claude Code	OpenCode
Project	.claude/	.opencode/
Global	~/.claude/	~/.config/opencode/

Quick Reference

Command Frontmatter

Canonical (content/):

---
name: my-command
description: What this command does
agent: build           # Optional: which agent handles this
subtask: true          # Optional: run as subtask
model: sonnet         # Optional: override model
temperature: 0.3      # Optional: temperature
tools:                 # Optional: tool restrictions
  read: true
  write: true
---

Claude Code Output: Same format (YAML frontmatter)

OpenCode Output: Table format

| description | agent |
|---|---|
| Description here | build |

Agent Frontmatter

Canonical (content/):

---
name: my-agent
description: Use this agent when... <example>...</example>
mode: subagent
model: sonnet
color: cyan
temperature: 0.3
tools:
  read: true
  write: true
---

Claude Code Output: Same format (YAML frontmatter)

OpenCode Output: Table format

| description | mode |
|---|---|
| Description here | subagent |

Skill Structure

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

OpenCode Custom Tools

Use TypeScript with tool() helper:

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/
├── content/
│   ├── commands/              # Add new commands here
│   └── agents/                # Add new agents here
├── skills/
│   └── plugin-dev/           # This skill
└── build.ts                   # Transforms to both platforms

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/

Platform-Specific Features

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

{
  "name": "plugin-name",
  "version": "1.0.0",
  "description": "Brief description",
  "commands": ["./commands/*"],
  "mcpServers": "./.mcp.json"
}

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

import { Plugin } from "@opencode-ai/plugin"

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

Development Workflow

1. Create Component

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

2. Build

cd ai-eng-system
bun run build              # Build all platforms
bun run build --watch        # Watch mode
bun run build --validate      # Validate content

3. Test

Claude Code:

claude plugin add https://github.com/v1truv1us/ai-eng-system

OpenCode:

# Project-local
./setup.sh

# Global
./setup-global.sh

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

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

Security

• No hardcoded credentials
• Use HTTPS/WSS for external connections
• Validate user inputs
• Follow principle of least privilege

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

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

Troubleshooting

Build Issues

• Run bun run build --validate to check content
• Check file permissions in output directories
• Verify YAML frontmatter syntax

Platform Testing

• Test commands in both Claude Code and OpenCode
• Verify agents trigger correctly
• Check skills load via opencode-skills plugin

Common Errors

• Missing required frontmatter fields
• Incorrect directory structure
• Invalid YAML syntax
• Wrong file permissions

Integration with Ferg Engineering

The plugin-dev system integrates seamlessly with existing ai-eng-system components:

Existing Commands

• /ai-eng/plan - Implementation planning
• /ai-eng/review - Code review
• /ai-eng/work - Task execution

Existing Agents

• ai-eng/architect-advisor - Architecture guidance
• ai-eng/frontend-reviewer - Frontend review
• ai-eng/seo-specialist - SEO optimization

Plugin-Dev Commands

• /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.