What Good Looks Like

What does a “good” OpenCode plugin look like? Instead of an abstract checklist, this guide walks through concrete design decisions in Systematic and explains why they exist.

Installation Should Be One Line

Zero friction is the goal. You shouldn’t need to download scripts or manually copy files to get started. Systematic achieves this by hooking directly into the OpenCode plugin system.

Adding a single line to your global configuration is all it takes:

{
  "plugins": ["@fro.bot/systematic@latest"]
}

This registers the plugin globally, making all bundled assets available in every project. For users who prefer granular control, the OCX registry provides an alternative for component-level installation.

See the Installation Guide for details.

Zero Configuration by Default

A well-structured plugin works immediately. Systematic uses the config hook to auto-register all bundled skills and agents during the OpenCode startup sequence.

Convention over configuration. Sensible defaults should satisfy 90% of use cases.

Manual file copying is an anti-pattern that leads to stale definitions. By bundling assets within the npm package and registering them programmatically, Systematic ensures you always have the latest workflows without touching your .opencode directory. If you do need to override something, project-level configuration always takes precedence.

Read more about the Architecture.

Teach the Agent How to Use You

The biggest challenge with AI plugins is discoverability. If the agent doesn’t know a tool exists, it won’t use it. Systematic solves this via “Bootstrap Injection” using the system.transform hook.

Every conversation starts with the using-systematic skill injected into the system prompt. This teaches the AI:

1. That Systematic is installed.
2. What skills are available.
3. How to use the systematic_skill tool to load them.

This makes the plugin self-documenting for the AI. You don’t have to remind the agent to use Systematic; the plugin teaches the agent how to be a better collaborator.

Make Everything Discoverable

Structure should be predictable. Systematic uses consistent naming conventions and categories to help both humans and agents find what they need.

• Tools: The systematic_skill tool description contains an XML list of all available skills.
• Namespacing: All bundled skills use the systematic: prefix to avoid collisions with native or project-specific skills.
• Agents: Categorized by function (Design, Research, Review, Workflow) for clear mental models.
• Slash Invocation: Bundled skills are invocable directly as slash commands (for example, /ce:plan).

Generate Docs from Source

Documentation should never be out of sync with the code. Systematic treats Markdown assets (skills and agents) as the source of truth for its documentation site.

Reference pages are generated at build time using transform-content.ts. This script parses the YAML frontmatter and body of every bundled asset to produce the Reference Section. When a developer adds a new skill to the repo, the documentation updates automatically.

Design for Extension

Plugins should be additive, never destructive. Systematic follows a hierarchy that respects your project’s specific needs:

1. Project Level: .opencode/skills/ and .opencode/agents/
2. User Level: ~/.config/opencode/
3. Plugin Level: Bundled assets

If you create a skill named brainstorming in your project, Systematic will step aside and let yours take priority. You can also disable any bundled asset via the disabled_skills or disabled_agents configuration options.

Current Gaps

While Systematic aims to be a benchmark, it isn’t finished. We’re honest about where we’re still falling short:

• Missing Changelog: There is no automated release notes page in the documentation yet.
• Community Contributions: We lack a formal contributing guide for authors who want to submit their own skills or agents.
• Interactive Demos: The docs need more visual evidence, such as video walkthroughs or an interactive playground.
• Testing Coverage: Integration tests don’t yet cover the full plugin lifecycle within the actual OpenCode binary environment.

---

Understand the Philosophy behind these decisions or see the Main Loop in action.