Skip to content

cianfhoghlaim/cianchosaint / .agents/skills/opencode

opencode

Unverified


name: opencode description: OpenCode AI agent configuration for the cianfhoghlaim monorepo. Use when adding/modifying agents, writing agent prompts as markdown files in .opencode/agents/, migrating from the deprecated tools field to the current permission field, configuring MCP servers, wiring AGENTS.md + guides.yml into the instructions array, or setting up subagent dispatch with permission.task gating. Covers opencode 1.18+ schema (primary/subagent modes, watcher.ignore, compaction, disabled_providers). when_to_use: "opencode agent author | MCP server configurer | permissions designer | agent dispatcher"

OpenCode — agent + MCP configuration

OpenCode is the AI coding agent that drives this repo. The config at opencode.json + .opencode/agents/*.md defines the 4 primary agents (build, plan, research, orchestrator) + 9 domain-specific subagents. Local install: opencode 1.18.16.

API notice (2026-08-19): The tools field is deprecated. Use the permission field for all access control. The permission.task sub-field controls which subagents each agent can invoke via the Task tool. See ## Permission API migration below.

Quick start — the 13 agents

AgentModeLocationPurpose
buildprimaryopencode.jsonDefault — full read/write/exec; M3 direct coding plan
planprimaryopencode.jsonRead-only — design specs + proposals; denies edit
researchprimaryopencode.jsonBrowser-driven investigation via firecrawl + browserbase
orchestratorprimary (hidden)opencode.jsonE2E BIEP + Túatha + Croílár pipeline orchestration
data-platformsubagent.opencode/agents/data-platform.mdDLT + Dagster + BAML + DuckLake + MotherDuck + marimo
infrastructuresubagent.opencode/agents/infrastructure.mdKomodo + Pangolin + Locket + Infisical + Pulumi + Dagger
agent-platformsubagent.opencode/agents/agent-platform.md12-agent fleet + OCR models + Celtic languages + Langfuse
frontend-appssubagent.opencode/agents/frontend-apps.mdTanStack Start + Convex + Hono + CopilotKit + Babylon.js
notebookssubagent.opencode/agents/notebooks.mdmarimo notebook authoring + debugging
bamlsubagent.opencode/agents/baml.mdBAML schema authoring (320 .baml files)
dagstersubagent.opencode/agents/dagster.mdDagster asset + component + job authoring
misesubagent.opencode/agents/mise.mdmise.toml task authoring
proposal-authorsubagent.opencode/agents/proposal-author.mdOpenSpec change author

Plus the hidden internal ones (dev-env-demo, deep-cuts) used only via programmatic invocation.

Config file schema (opencode.json)

{
  "$schema": "https://opencode.ai/config.json",
  "snapshot": false,
  "subagent_depth": 2,
  "default_agent": "build",
  "watcher": {
    "ignore": ["node_modules/**", ".venv/**", "stedding/**"]
  },
  "compaction": {
    "auto": true,
    "prune": true,
    "reserved": 16000
  },
  "instructions": [
    "AGENTS.md",
    "openspec/AGENTS.md",
    ".agents/skills/INDEXING_AND_COGNITION.md",
    ".cocoindex_code/guides.yml"
  ],
  "provider": {
    "qwen": {
      "name": "Qwen Token Plan",
      "api": "openai",
      "options": {
        "apiKey": "{env:DASHSCOPE_API_KEY}",
        "baseURL": "{env:DASHSCOPE_BASE_URL}"
      },
      "models": { ... }
    }
  },
  "mcp": {
    "firecrawl": {
      "type": "local",
      "command": ["bunx", "-y", "firecrawl-mcp"],
      "environment": { "FIRECRAWL_API_KEY": "{env:FIRECRAWL_API_KEY}" },
      "enabled": true
    }
  },
  "agent": {
    "build": {
      "prompt": "{file:./.opencode/agents/build.md}",
      "model": "minimax-coding-plan/MiniMax-M3"
    }
  }
}

Precedence order (highest wins)

  1. Remote config (.well-known/opencode)
  2. Global config (~/.config/opencode/opencode.json)
  3. Custom config (OPENCODE_CONFIG env var)
  4. Project config (opencode.json) ← this repo
  5. .opencode/ directory (agents, commands, plugins)
  6. Inline config (OPENCODE_CONFIG_CONTENT env var)
  7. Managed config (/Library/Application Support/opencode/ on macOS)
  8. macOS managed preferences (.mobileconfig via MDM)

Agent modes

ModeUseTab-cyclable@mention
primaryMain conversation agents (build, plan, research)yesno
subagentSpecialized helpers invoked via Task toolnoyes
allDefault if mode not specifiedbothboth

For internal-only subagents (orchestrator, dev-env-demo, deep-cuts), set hidden: true to remove from the @ autocomplete menu.

Permission API (current, replaces deprecated tools)

{
  "agent": {
    "plan": {
      "permission": {
        "edit": "deny",
        "bash": {
          "*": "ask",
          "git status": "allow",
          "git log*": "allow",
          "git diff": "allow",
          "openspec *": "allow",
          "mise tasks": "allow",
          "mise run lint*": "allow"
        },
        "webfetch": "ask",
        "external_directory": "deny",
        "task": {
          "*": "deny",
          "research": "allow",
          "deep-cuts": "allow"
        }
      }
    }
  }
}

Permission keys (per opencode 1.18+):

KeyTools it gates
readread
editwrite, edit, apply_patch
globglob
grepgrep
listlist
bashbash (with glob/pattern → action support)
tasktask (with glob/pattern → action for subagent invocation)
external_directoryAny tool that reads/writes outside the project worktree
todowritetodowrite, todoread
webfetchwebfetch
websearchwebsearch
lsplsp
skillskill
questionquestion
doom_loopRecovery prompts when an agent appears stuck

Values: "allow" | "ask" | "deny" | {} for fine-grained per-pattern.

Migration from tools to permission

Old (tools)New (permission)
tools: { write: true, edit: true }permission: { "*": "allow" }
tools: { write: false, edit: false }permission: { edit: "deny" }
tools: { bash: false }permission: { bash: "deny" }
tools: { mymcp_*: false }permission: { "mcp__mymcp__*": "deny" }

Markdown agent files (.opencode/agents/<name>.md)

---
description: Functional subagent for the data plane (DLT + Dagster + BAML + DuckLake + MotherDuck + marimo notebooks). Routes to dlt_sources/, orchestration/, baml_src/, notebooks/. Owns the 5-layer Dagster defs/ tree, the 928 DLT sources, the 320 .baml files, and the 109 marimo notebooks.
mode: subagent
model: minimax-coding-plan/MiniMax-M3
temperature: 0.1
permission:
  edit: allow
  bash: { "*": "ask", "uv run *": "allow", "mise run *": "allow", "git status": "allow", "git diff": "allow" }
  webfetch: ask
  external_directory: deny
  task: { "research": "allow", "deep-cuts": "ask" }
skill_filter: [dlt, dagster, baml, motherduck, duckdb, ducklake, cocoindex, lancedb, cognee, ibis, marimo, dlthub, langfuse, mlflow, apple-photos, centralized-registry]
color: "#3a5f3a"
hidden: false
---

You are the data-platform functional subagent...

# Direct references (mirrors guides.yml)
- dlt_sources/AGENTS.md
- baml_src/AGENTS.md
- orchestration/AGENTS.md
- notebooks/_shared/db.py
- .cocoindex_code/guides.yml#data-platform
- .agents/skills/dlt/SKILL.md
...

The frontmatter fields: description (required), mode, model, temperature, permission, tools (deprecated), skill_filter, color, top_p, steps, hidden, disable.

Variables in config files

{
  "model": "{env:OPENCODE_MODEL}",
  "provider": {
    "anthropic": {
      "options": { "apiKey": "{env:ANTHROPIC_API_KEY}" }
    }
  },
  "instructions": ["{file:./custom-instructions.md}"],
  "agent": {
    "review": { "prompt": "{file:./prompts/review.txt}" }
  }
}
SyntaxMeaning
{env:VAR}Substitute environment variable (empty if unset)
{file:path}Substitute file contents (relative or absolute)

Providers + allowlists

{
  "provider": {
    "anthropic": {
      "options": {
        "apiKey": "{env:ANTHROPIC_API_KEY}",
        "timeout": 600000,
        "chunkTimeout": 30000,
        "setCacheKey": true
      },
      "models": { ... }
    }
  },
  "disabled_providers": ["gemini"],
  "enabled_providers": ["anthropic", "openai"]
}

If a provider appears in both lists, disabled_providers wins.

MCP servers

{
  "mcp": {
    "firecrawl": {
      "type": "local",
      "command": ["bunx", "-y", "firecrawl-mcp"],
      "environment": {
        "FIRECRAWL_API_KEY": "{env:FIRECRAWL_API_KEY}"
      },
      "enabled": true
    },
    "browserbase": {
      "type": "remote",
      "url": "https://mcp.browserbase.com/mcp",
      "headers": { "Authorization": "Bearer {env:BROWSERBASE_API_KEY}" },
      "enabled": false,
      "timeout": 60000
    }
  }
}

13 MCP servers are registered in this repo (3 enabled by default; 10 disabled — toggle via enabled: true/false).

Custom commands (.opencode/commands/*.md)

---
description: Run tests with coverage
agent: build
model: minimax-coding-plan/MiniMax-M3
subtask: true
---

Run the full test suite with coverage report.

Test results:
!`bun run test`

Based on these results, suggest fixes.

Then /test in the TUI invokes it.

Special placeholders: $ARGUMENTS, $1-$9, !`command` (shell output), @path/to/file (file inclusion).

Plugins

.opencode/plugins/<name>.ts extends OpenCode with custom tools + hooks + integrations. Also loadable from npm:

{
  "plugin": ["opencode-helicone-session", "@my-org/custom-plugin"]
}

Routing: when to use what

QuestionTool
"Where do I add a new domain agent?".opencode/agents/<name>.md
"How do I change agent permissions?"permission field in markdown frontmatter
"What agents are available?"Tab key in TUI, or opencode agent list
"How do I invoke a subagent manually?"@<agent-name> in the message
"How do I disable a noisy MCP server?"mcp.<name>.enabled = false

Anti-patterns

  • NEVER use the deprecated tools field — use permission.
  • NEVER inline a >2 KB prompt in opencode.json — use {file:./.opencode/agents/<name>.md}.
  • NEVER leave a subagent un-hidden if it's internal-only (orchestrator, dev-env-demo, deep-cuts).
  • NEVER grant external_directory: allow to a domain subagent — it can read/write outside the project worktree.
  • NEVER set subagent_depth > 2 — recursion gets expensive fast.

Skill pointers

  • opencode.json — canonical config (provider + MCP + 4 primary agents)
  • .opencode/agents/<name>.md — domain-specific subagents
  • .opencode/commands/<name>.md — slash commands (TUI)
  • .opencode/plugins/<name>.ts — custom tool extensions
  • .cocoindex_code/guides.yml#opencode-agent-search — CCC concept guide
  • .cocoindex_code/guides.yml#opencode-agent-search — agent search

References

slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack."Stars: 196kUpdated Claude CodeCodexVerifiedInstall
ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read.Stars: 192kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report.Stars: 192kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt.Stars: 192kUpdated Claude CodeCodexVerifiedInstall