fetch-opencode-docs

name	fetch-opencode-docs
description	Fetches and reads the latest OpenCode documentation from the official repository to stay current with features, best practices, and configuration options. Use this skill when creating new agents, sub-agents, skills, commands, or any other OpenCode configuration.

Fetch OpenCode Documentation

Overview

This skill provides a systematic approach to fetching and reading the latest OpenCode documentation from the official repository. Use this to stay current with OpenCode features, understand new capabilities, and ensure configurations follow the latest best practices.

Core principle: Always reference the latest official documentation when working with OpenCode configurations.

Announce at start: "I'm using the fetch-opencode-docs skill to get the latest OpenCode documentation."

When to Use

Load this skill when:

• Creating or updating OpenCode configurations (agents, skills, commands)
• Answering questions about OpenCode capabilities
• Troubleshooting configuration issues
• Learning about new OpenCode features
• Validating configuration syntax or options
• Understanding tool permissions and settings

Documentation Sources

Primary Documentation URLs

All OpenCode documentation source files are in the production branch at: https://raw.githubusercontent.com/sst/opencode/production/packages/web/src/content/docs/

Why use raw MDX files instead of rendered HTML?

• ✅ Cleaner content without navigation/UI elements
• ✅ 50% smaller payload (faster fetching, less tokens)
• ✅ Easier to parse (pure markdown with minimal MDX syntax)
• ✅ Always up-to-date from production branch

Core Documentation Files

1. Introduction: index.mdx

   • Getting started guide
   • Installation instructions
   • Basic usage and workflow
   • Prerequisites and setup
   • URL: https://raw.githubusercontent.com/sst/opencode/production/packages/web/src/content/docs/index.mdx

2. Configuration Guide: config.mdx

   • Global and project-specific config
   • Config file locations and merging
   • Schema and all available options
   • Variable substitution (env vars, files)
   • URL: https://raw.githubusercontent.com/sst/opencode/production/packages/web/src/content/docs/config.mdx

3. Agents Guide: agents.mdx

   • Primary agents vs subagents
   • Built-in agents (Build, Plan, General, Explore)
   • Agent modes and configuration
   • Tool and permission configuration
   • Temperature and model settings
   • Creating custom agents
   • URL: https://raw.githubusercontent.com/sst/opencode/production/packages/web/src/content/docs/agents.mdx

4. Skills Guide: skills.mdx

   • Skill file structure (SKILL.md)
   • Frontmatter requirements
   • Naming conventions and validation
   • Discovery and loading behavior
   • Permission configuration
   • URL: https://raw.githubusercontent.com/sst/opencode/production/packages/web/src/content/docs/skills.mdx

5. Commands Guide: commands.mdx

   • Command creation and configuration
   • Template syntax and variables
   • Arguments ($ARGUMENTS, $1, $2, etc.)
   • Shell output interpolation (!command)
   • File references (@filename)
   • URL: https://raw.githubusercontent.com/sst/opencode/production/packages/web/src/content/docs/commands.mdx

6. Tools Guide: tools.mdx

   • Built-in tools (bash, edit, write, read, grep, glob, etc.)
   • Tool configuration and permissions
   • Custom tools and MCP servers
   • Ignore patterns and internals
   • URL: https://raw.githubusercontent.com/sst/opencode/production/packages/web/src/content/docs/tools.mdx

7. Permissions Guide: permissions.mdx

   • Permission levels (allow, ask, deny)
   • Global and per-agent permissions
   • Pattern-based permissions
   • Bash command permissions
   • URL: https://raw.githubusercontent.com/sst/opencode/production/packages/web/src/content/docs/permissions.mdx

8. Models Guide: models.mdx

   • Provider configuration
   • Model selection and overrides
   • OpenCode Zen models
   • Local model support
   • URL: https://raw.githubusercontent.com/sst/opencode/production/packages/web/src/content/docs/models.mdx

Additional Resources

• TUI: tui.mdx
• CLI: cli.mdx
• Providers: providers.mdx
• Themes: themes.mdx
• Keybinds: keybinds.mdx
• Formatters: formatters.mdx
• MCP Servers: mcp-servers.mdx
• Custom Tools: custom-tools.mdx
• LSP Servers: lsp.mdx
• Rules: rules.mdx

All additional resources follow the same URL pattern: https://raw.githubusercontent.com/sst/opencode/production/packages/web/src/content/docs/<filename>.mdx

Fetching Process

1. Identify Documentation Need

Determine what information you need:

• Configuration syntax: Fetch configuration guide
• Specific feature: Fetch relevant guide (agents/skills/commands)
• Examples: Fetch examples directory
• General overview: Fetch main README

2. Fetch Documentation

Use the webfetch tool to retrieve raw MDX files from the production branch:

# Fetch as text (recommended - clean MDX format)
webfetch url="https://raw.githubusercontent.com/sst/opencode/production/packages/web/src/content/docs/agents.mdx" format="text"

# Fetch config guide
webfetch url="https://raw.githubusercontent.com/sst/opencode/production/packages/web/src/content/docs/config.mdx" format="text"

# Fetch skills guide
webfetch url="https://raw.githubusercontent.com/sst/opencode/production/packages/web/src/content/docs/skills.mdx" format="text"

Note on MDX syntax: The files contain minimal MDX-specific syntax:

• :::tip, :::note, :::caution - Treat as informational callouts
• Code blocks with title="filename" - Standard markdown with metadata
• Everything else is standard markdown

3. Extract Relevant Information

Focus on the specific sections needed:

• Read the entire document if it's short
• Search for specific keywords or sections
• Extract code examples
• Note version-specific information

4. Apply to Current Task

Use the documentation to:

• Validate your configuration approach
• Correct syntax errors
• Discover new features or options
• Ensure best practices are followed

Common Documentation Queries

Agent Configuration

Question: What tools are available for agents?

Fetch: https://raw.githubusercontent.com/sst/opencode/production/packages/web/src/content/docs/tools.mdx

Key info: Built-in tools include bash, edit, write, read, grep, glob, list, lsp, patch, skill, todowrite, todoread, webfetch, plus custom tools and MCP server tools

Permission System

Question: How do I configure tool permissions?

Fetch: https://raw.githubusercontent.com/sst/opencode/production/packages/web/src/content/docs/permissions.mdx

Key info: Three levels (allow, ask, deny), pattern matching for bash commands, global and per-agent configuration

Skill Structure

Question: What's the required structure for a skill?

Fetch: https://raw.githubusercontent.com/sst/opencode/production/packages/web/src/content/docs/skills.mdx

Key info:

• Directory structure: skill/<name>/SKILL.md
• Required frontmatter: name and description
• Name must be 1-64 chars, lowercase alphanumeric with single hyphens
• Description must be 1-1024 characters
• Directory name must match skill name

Command Templates

Question: What template variables are available?

Fetch: https://raw.githubusercontent.com/sst/opencode/production/packages/web/src/content/docs/commands.mdx

Key info:

• $ARGUMENTS - All arguments as string
• $1, $2, etc. - Individual positional arguments
• !command`` - Shell command output interpolation
• @filename - File content references

Model Configuration

Question: How do I specify a different model?

Fetch:

• https://raw.githubusercontent.com/sst/opencode/production/packages/web/src/content/docs/models.mdx
• https://raw.githubusercontent.com/sst/opencode/production/packages/web/src/content/docs/config.mdx

Key info:

• Format: provider/model-id (e.g., anthropic/claude-sonnet-4-5)
• Configure via model and small_model in config
• Can override per agent
• OpenCode Zen provides curated models

Documentation Caching Strategy

When to Re-fetch

• Always: When creating new configurations
• Daily: For active development work
• Weekly: For maintenance tasks
• On error: When configurations fail validation

When to Use Cached Knowledge

• Never: OpenCode is actively developed, always fetch latest
• Exception: If webfetch fails, use cached knowledge with disclaimer

Integration with Other Skills

With opencode-config-validation

1. Fetch latest documentation
2. Extract validation rules
3. Apply to configuration being validated
4. Report any discrepancies

With Otto Agents

1. otto-analyzer: Fetch docs to understand latest abstraction options
2. otto-generator: Fetch docs to ensure generated configs use latest syntax

Quick Reference

Base URL: https://raw.githubusercontent.com/sst/opencode/production/packages/web/src/content/docs/

Need	File	Key Sections
Getting started	index.mdx	Install, Configure, Usage
Agent setup	agents.mdx	Types, Built-in, Options, Examples
Skill creation	skills.mdx	Structure, Frontmatter, Permissions
Command syntax	commands.mdx	Templates, Variables, Interpolation
Tool configuration	tools.mdx	Built-in tools, Custom, MCP
Permissions	permissions.mdx	Levels, Patterns, Configuration
Config file	config.mdx	Schema, Locations, All options
Models & providers	models.mdx	Provider setup, Model selection
Custom tools	custom-tools.mdx	Creating custom tools
MCP servers	mcp-servers.mdx	Integration with MCP
TUI usage	tui.mdx	Terminal interface, Commands
CLI usage	cli.mdx	Command-line interface
Formatters	formatters.mdx	Code formatting configuration
Keybinds	keybinds.mdx	Keyboard shortcuts
Themes	themes.mdx	Theme configuration

Error Handling

Fetch Failures

If webfetch fails:

1. Check internet connectivity
2. Try fetching a different documentation page
3. Use cached knowledge with clear disclaimer
4. Suggest user check documentation manually

Example:

⚠️ Unable to fetch latest documentation. Using cached knowledge.
Please verify at: https://opencode.ai/docs/ or
https://github.com/sst/opencode/tree/production/packages/web/src/content/docs

Documentation Not Found

If specific doc doesn't exist:

1. Try main README
2. Search examples directory
3. Check if feature is deprecated
4. Suggest filing issue if feature should exist

Best Practices

1. Always Fetch Before Creating

Never create configurations from memory alone:

✓ Fetch docs → Review syntax → Create config
✗ Create config → Hope it works

2. Verify Examples

When using examples from docs:

• Adapt to specific use case
• Don't copy blindly
• Understand each configuration option
• Test thoroughly

3. Stay Current

OpenCode evolves rapidly:

• Fetch docs at start of session
• Re-fetch if encountering unexpected behavior
• Note version-specific features
• Update local configurations periodically

4. Cross-Reference

Validate information across multiple sources:

• Main docs for concepts
• Examples for patterns
• Configuration guide for syntax
• Validation skill for rules

Example Workflow

User: "Create an agent for code review"

You: I'm using the fetch-opencode-docs skill to get the latest OpenCode documentation.

[Fetch agents.mdx from production branch]
[Fetch config.mdx for configuration options]
[Review examples in agents.mdx for code-review patterns]

Based on the latest documentation:
- Agents require 'description' in frontmatter (mode defaults to 'all')
- Code review agents typically use: read, grep, bash tools
- Permission level 'ask' recommended for edit operations
- Temperature 0.1-0.3 recommended for analytical tasks
- Example security-auditor agent shows best practices

[Proceed with configuration creation using validated information]

Red Flags

Never:

• Create configurations without checking latest docs
• Assume syntax from memory
• Use deprecated features without noting them
• Ignore version-specific warnings

Always:

• Fetch documentation before creating configs
• Verify syntax against official sources
• Note when using experimental features
• Provide documentation links to users

Documentation Structure Understanding

Agent Frontmatter Format

---
description: Brief description (required)
mode: primary|subagent|all (defaults to 'all')
model: provider/model-id
temperature: 0.0-1.0
maxSteps: positive integer
tools:
  read: true
  write: false
  bash: true
permission:
  edit: allow|ask|deny
  bash:
    "git *": allow
    "*": ask
  webfetch: deny
---

Skill Format

---
name: skill-name (required, must match directory)
description: What this skill does (required, 1-1024 chars)
license: MIT (optional)
compatibility: opencode (optional)
metadata: (optional, string-to-string map)
  key: value
---

# Skill Title

## Overview
## When to Use
## Instructions
## Examples

Command Format

---
template: Command template with $ARGUMENTS (required)
description: What this command does (optional)
agent: which-agent-handles-it (optional)
subtask: true|false (optional)
model: provider/model-id (optional)
---

Version Awareness

Checking OpenCode Version

If version-specific features are mentioned:

1. Note the minimum version required
2. Warn user if using older version
3. Provide fallback for older versions
4. Link to upgrade instructions

Feature Availability

Track when features were introduced:

• Note "Added in vX.X" markers
• Check if feature is stable or experimental
• Warn about breaking changes
• Suggest alternatives for older versions

Summary

This skill ensures you always work with the latest, most accurate OpenCode documentation. By systematically fetching and applying official documentation, you create reliable, standards-compliant configurations that leverage the full power of OpenCode.

Remember: OpenCode is actively developed. Always fetch the latest documentation rather than relying on cached knowledge.