Design Principles and Practical Tips for Skills and Agents in OpenCode

Abstract

Extensible LLM programming environments now mix reusable capabilities, agent orchestration, and external tools in a single working loop. OpenCode is a typical example, but its documentation and community examples sometimes leave the boundaries among Skills, Agents, Subagents, Tools, MCP servers, and Commands unclear. The result is usually not a single catastrophic error, but smaller engineering problems: brittle configuration, permissions that grow too broad, and notes that are hard to reuse outside the author's own setup. This paper turns OpenCode practice into a set of engineering conventions. It defines the main concepts, separates responsibilities, records file-layout rules, describes a threat model, and reviews Skill and Agent examples with the same template. This paper is an \emph{experience report}: its contribution is a practical set of design rules, distilled from hands-on use of OpenCode, for building extensions that are easier to reuse, inspect, and maintain, while still acknowledging the limits of any safety claim in an open tool environment.

Keywords