> your AI agent picks dependencies from memory; give it dated facts — try starlog.dev ↗ vet your agent's deps ↗ vibe-coding is fine. vibe-importing isn’t. — try starlog.dev ↗ vibe-importing isn’t fine ↗ your agent has never seen your private packages — try starlog.dev ↗ facts for private packages ↗ a linter for the dependencies your AI agent picks — try starlog.dev ↗ a linter for agent deps ↗ whois is redacted, cdns mask the rest — get the real operator — try whoisgeni.us ↗ who really runs that domain ↗ domain attribution that shows its work — full evidence chain — try whoisgeni.us ↗ domain intel w/ evidence ↗

← Back to Articles

Building a Universal Plugin System for AI Coding Assistants: Inside wshobson/agents

[ View on GitHub ]

Building a Universal Plugin System for AI Coding Assistants: Inside wshobson/agents

Hook

With 40,000+ GitHub stars, wshobson/agents has more visibility than LangChain's official tools repository—yet it solves a problem most developers don't know exists: writing AI coding plugins once instead of seven times.

Context

If you've used AI coding assistants in the past year, you've experienced the fragmentation problem firsthand. Claude Code uses Markdown-based plugin manifests. Cursor expects .cursorrules files. GitHub Copilot wants JSON configurations through GPT Actions. OpenCode requires TOML. Google Antigravity has its own format. Each tool speaks a different configuration language, uses different model identifiers (claude-3-5-sonnet vs. sonnet-3.5 vs. claude-sonnet), and imposes different size limits on plugin content.

This fragmentation creates a maintenance nightmare for teams using multiple AI assistants or open-source authors wanting broad distribution. You're not just writing the plugin logic seven times—you're tracking seven different update cycles, seven sets of breaking changes, and seven incompatible permission models. The industry lacks a universal plugin standard, and with venture-backed companies competing for developer mindshare, one isn't coming. wshobson/agents takes a different approach: treat the fragmentation as a compilation target problem, not a standardization problem. Write plugins once in a canonical format, then transpile them to whatever each platform needs.

Technical Insight

The architecture centers on a single source of truth: Markdown files in Claude Code's plugin format, stored in plugins/*/agents/, plugins/*/skills/, and plugins/*/commands/. These aren't just documentation—they're executable specifications that adapters parse and transform. Here's what a minimal agent definition looks like:

# Django Debug Agent

**Model:** sonnet
**Tools:** read_file, write_file, execute_command
**Description:** Analyzes Django errors and suggests fixes

## Instructions

When the user shares a Django traceback:
1. Read the failing view file
2. Check for common issues (missing migrations, incorrect imports)
3. Suggest specific code changes

The Python adapters in tools/adapters/ parse this Markdown and handle three critical translation layers. First, model aliasing: the sonnet identifier maps to claude-3-5-sonnet-20241022 for Claude Code, gpt-4o for Copilot (which doesn't support Claude), and sonnet-3.5 for OpenCode. The adapter maintains a capability matrix—if a platform doesn't support a requested model, it falls back to inherit (use the harness's default) or the closest equivalent.

Second, permission mapping: different platforms have wildly different tool access models. Claude Code uses granular permissions (read_file, write_file, execute_command). Cursor bundles them into filesystem_full. Copilot requires OAuth scopes. The adapter translates the abstract tool list into platform-specific permissions:

# Simplified adapter logic from tools/adapters/codex_adapter.py
def map_tools_to_codex(tools: list[str]) -> dict:
    permissions = {}
    if 'read_file' in tools or 'write_file' in tools:
        permissions['filesystem'] = 'read_write'
    if 'execute_command' in tools:
        permissions['shell'] = 'interactive'
    return permissions

Third, size budget enforcement: Codex CLI has an 8KB limit per plugin file. When the Markdown source exceeds this (common for agents with detailed instructions), the adapter splits content into a main manifest and reference files. The agent description stays in the TOML manifest, while instruction details go into separate files that Codex loads on-demand.

The build system uses a Makefile that orchestrates platform-specific generation:

generate-all: generate-opencode generate-antigravity generate-copilot generate-pi

generate-opencode:
	@uv run tools/adapters/opencode_adapter.py \
		--source plugins/ \
		--output .opencode/ \
		--validate

Running make generate-all produces seven platform-specific artifact directories. For native platforms (Claude Code, Cursor), the system generates marketplace metadata but relies on the original Markdown for runtime. For others, it produces complete installation packages—TOML configs for OpenCode, JSON for Copilot, platform-specific manifests for Antigravity and Pi.

The validation pipeline (make validate) combines structural checks (required fields, valid model aliases, tool references) with experimental LLM-based scoring through the plugin-eval component. This runs agents against synthetic tasks and uses GPT-4 to score output quality—not ground truth validation, but useful for catching regressions when updating the 202 agents in the library.

What makes this architecture genuinely clever is the model alias abstraction. Instead of hardcoding claude-3-5-sonnet and creating vendor lock-in, agents specify capability tiers: opus (most capable), sonnet (balanced), haiku (fast), fable (experimental). The adapters map these to whatever models each platform actually supports. When Claude releases a new model, you update one mapping table instead of 202 agent files. When using Copilot (which doesn't support Claude), the adapter transparently substitutes GPT-4 variants without breaking the agent.

Gotcha

The experimental LLM evaluation in plugin-eval sounds useful but isn't validated against human judgments or real-world task completion. It simulates plugin execution and uses GPT-4 to score outputs, which means you're getting one AI's opinion about another AI's work. The README acknowledges this explicitly: "Does not prove the task actually works in a real project." It's fine for smoke testing whether a plugin generates syntactically valid code, but don't treat the scores as quality metrics. You still need manual testing for anything shipping to users.

The platform capability gap creates unpredictable user experiences. Pi requires installing a separate subagent extension for multi-step workflows. Codex's 8KB limit means complex agents get split across files, adding latency. Some platforms don't support command execution at all. If you're building agents for broad distribution, you're essentially targeting the lowest common denominator of features—which defeats the purpose of using advanced AI assistants. The abstraction helps with distribution but can't paper over fundamental platform differences.

With 40,000+ stars but only 94 plugins (mostly from the original author), this isn't a thriving marketplace—it's a well-executed personal catalog with great visibility. Community contribution appears minimal, which means maintenance sustainability is uncertain and use case diversity is limited. If your workflow doesn't align with the existing 202 agents, you're writing custom plugins anyway, and the multi-platform complexity may not be worth it.

Verdict

Use if: You're managing AI coding plugins across multiple tools (contractors using both Cursor and Claude Code, teams evaluating different assistants, organizations wanting centralized plugin governance) and need the single-source-of-truth benefits. The adapter architecture is solid, the validation tooling shows production thinking, and for multi-platform plugin distribution, this is the only serious option available. Also use if you want a substantial library of working agents (Django, FastAPI, security scanning) and don't want to write them from scratch. Skip if: You're committed to a single AI assistant—the multi-platform abstraction adds complexity without benefit, and you'll get better results from native plugin ecosystems with platform-specific features. Also skip if you need a community-driven marketplace with diverse contributions; this is essentially a single-author catalog despite the star count. The experimental evaluation layer and defunct Pensyve integration are distractions from the core value proposition.