Skilllibrary opencode-primitives

Reference for OpenCode's file paths, naming conventions, and configuration primitives that other MCP skills depend on. Use when needing exact paths for OpenCode config files, understanding OpenCode's agent/skill/tool directory structure, or setting up an OpenCode project with MCP support.

install

source · Clone the upstream repo

git clone https://github.com/merceralex397-collab/skilllibrary

Claude Code · Install into ~/.claude/skills/

T=$(mktemp -d) && git clone --depth=1 https://github.com/merceralex397-collab/skilllibrary "$T" && mkdir -p ~/.claude/skills && cp -r "$T/07-mcp/opencode-primitives" ~/.claude/skills/merceralex397-collab-skilllibrary-opencode-primitives && rm -rf "$T"

manifest: 07-mcp/opencode-primitives/SKILL.md

source content

Purpose

Authoritative reference for OpenCode's directory structure, configuration file locations, naming conventions, and the primitives that other MCP skills assume when referencing OpenCode. This is a lookup skill — it provides exact paths and formats rather than procedures.

When to use this skill

Need exact paths for OpenCode configuration files
Setting up a project directory for OpenCode with MCP support
Need to understand OpenCode's agent/skill/command/tool directory structure
Other skills reference "OpenCode conventions" and you need the specifics

Do not use this skill when

Connecting an MCP server to OpenCode → use
```
opencode-bridge
```
Building an MCP server → use
```
mcp-development
```
General MCP onboarding → use
```
get-started
```

OpenCode directory structure

project-root/
├── .opencode/
│   ├── config.json          # Project-level OpenCode configuration
│   ├── agents/              # Custom agent definitions
│   │   └── my-agent.md
│   ├── commands/            # Custom slash commands
│   │   └── my-command.md
│   ├── skills/              # Project-local skills
│   │   └── my-skill/
│   │       └── SKILL.md
│   └── tools/               # Custom tool definitions
│       └── my-tool.md

Configuration file:

.opencode/config.json

Primary project configuration for OpenCode:

{
  "mcpServers": {
    "server-name": {
      "command": "node",
      "args": ["/absolute/path/to/server.js"],
      "env": {
        "API_KEY": "value"
      }
    }
  }
}

MCP server config fields:

```
command
```
— executable to launch (e.g.,
```
node
```
,
```
python
```
,
```
uv
```
)
```
args
```
— array of arguments (use absolute paths)
```
env
```
— environment variables passed to the server process
```
url
```
— for remote Streamable HTTP servers (alternative to
```
command
```
/
```
args
```
)
```
headers
```
— HTTP headers for remote servers

Naming conventions

Entity	Convention	Example
Agent files	`kebab-case.md`	`code-reviewer.md`
Skill directories	`kebab-case/`	`my-skill/`
Skill entry point	`SKILL.md`	`my-skill/SKILL.md`
Command files	`kebab-case.md`	`deploy-staging.md`
Tool files	`kebab-case.md`	`run-tests.md`
MCP server names	`kebab-case`	`my-mcp-server`
Config key	`camelCase`	`mcpServers`

Key paths

Path	Purpose
`.opencode/config.json`	Project MCP server config and settings
`.opencode/agents/`	Custom agent definitions
`.opencode/skills/`	Project-local skill packages
`.opencode/commands/`	Custom slash commands
`.opencode/tools/`	Custom tool definitions
`AGENTS.md`	Top-level agent instructions (project root)

MCP integration points

OpenCode connects to MCP servers at startup based on

.opencode/config.json

. The integration follows standard MCP protocol:

Launch: OpenCode starts each configured server as a subprocess (stdio) or connects via URL (HTTP)
Initialize: Standard MCP
```
initialize
```
handshake with capability negotiation
Discover:
```
tools/list
```
to discover available tools
Use: Agent calls tools during task execution via
```
tools/call
```
Shutdown: Clean disconnect when OpenCode exits

Decision rules

All paths in
```
config.json
```
should be absolute to avoid working-directory issues
MCP server names in config should be unique kebab-case identifiers
Skills that reference OpenCode should use the exact paths listed here
Prefer stdio transport for local MCP servers with OpenCode

Output requirements

This is a reference skill. It produces no artifacts directly — it provides lookup information for other skills and procedures.

Related skills

```
opencode-bridge
```
— connecting MCP servers to OpenCode
```
mcp-host-integration
```
— general host configuration patterns
```
get-started
```
— initial MCP setup including OpenCode

Failure handling

If config file is not found, OpenCode runs without MCP servers — no error, just no tools
If a server fails to start, OpenCode logs the error and continues with other servers
If paths are relative, they resolve from OpenCode's working directory (usually project root) — but absolute is safer