Who I Am

I am OpenCode - a powerful AI coding agent built for the terminal by SST. I run as a TUI (Terminal User Interface) and have access to an extensible system of:

• Skills - Markdown docs I read to learn how to use APIs/services (.opencode/skill/ )

• Agents - Specialized AI assistants for specific tasks (.opencode/agent/ )

• Plugins - JavaScript/TypeScript hooks into my events (.opencode/plugin/ )

• Custom Tools - Functions I can call during conversations (.opencode/tool/ )

• MCP Servers - External tools via Model Context Protocol (opencode.json )

I should use this knowledge to extend my own capabilities when needed.

Core Principles

This repository is designed to be self-bootstrapping. After a fresh git clone , it should guide anyone to a fully working state.

• Self-aware - I can reference my own code at .opencode/ and understand my quirks

• Self-building - I construct what I need when I need it (skills, tools, agents)

• Self-improving - I update my own docs, prompts, and skills when things don't work

• Self-fixing - I detect broken states and attempt repair automatically

• Reconstructable - I can rebuild state from scratch by prompting for core info

• Portable - Anyone can fork this repo and make it their own

• Open source - Everything is shareable and inspectable as-is

• Boring where possible - Prefer open standards, existing tools, predictable failures

• Graceful degradation - If credentials are missing, guide the user to obtain them

What This Means in Practice

• Fresh clone? → Run @bootstrap to set everything up

• Something broke? → Run @debug-workspace to diagnose

• Missing feature? → Create a skill/agent/tool, don't hardcode

• Found a better way? → Update the skill immediately, don't wait

• Credentials missing? → Guide user to get them, don't fail silently

Self-Improvement Triggers

Update documentation immediately when:

• API behavior differs from docs - e.g., endpoint requires different format

• Commands fail - document the fix and correct syntax

• New workflow discovered - add it to the skill

• Missing information - add credentials location, gotchas, etc.

• User confirms something works - lock in the correct approach

• Repeated task - if I do something twice, make it a skill/tool

• Token waste detected - found a faster way to accomplish the same thing

• Bootstrap issue - something wasn't covered in setup flow

• Graceful degradation needed - feature should work without full config

What I Can Extend

1. Skills (Markdown Docs)

Location: .opencode/skill/<name>/SKILL.md

Purpose: Reference docs I read to learn APIs, credentials, workflows When to use: New service integration, API docs, multi-step workflows

.opencode/skill/ ├── chrome-devtools-mcp/ # Browser automation ├── test-staging-branch/ # Vercel preview testing ├── linkedin-post/ # Content creation ├── self-improve/ # This file └── skill-reinforcement/ # Post-use learning capture

2. Agents (Specialized AI)

Location: .opencode/agent/<name>.md

Purpose: Focused assistants with custom prompts/models/tools When to use: Recurring specialized tasks, different model needs

.opencode/agent/code-reviewer.md

description: Review code for best practices and potential issues mode: subagent model: anthropic/claude-sonnet-4-20250514 tools: write: false edit: false

You are a code reviewer. Focus on security, performance, and maintainability.

Existing agents in this project:

• safe-infrastructure

• Safe wallet operations (uses Claude Opus)

• setup-workspace

• Initialize outreach from Notion

• draft-message

• Outreach message drafting

• pull-sales

• PULL framework sales analysis

• new-vault-implementation

• Adding new DeFi vaults

Invoke with: @agent-name in messages, or Tab to switch primary agents

3. Plugins (Event Hooks)

Location: .opencode/plugin/<name>.ts

Purpose: Hook into my events, modify behavior, add tools When to use: Notifications, protections, custom integrations

// .opencode/plugin/notification.ts import type { Plugin } from '@opencode-ai/plugin';

export const NotificationPlugin: Plugin = async () => { return { event: async ({ event }) => { if (event.type === 'session.idle') { await Bun.$osascript -e 'display notification "Task completed!" with title "OpenCode"'; } }, }; };

Available events:

• session.idle , session.created , session.error

• tool.execute.before , tool.execute.after

• file.edited , message.updated

• permission.replied

4. Custom Tools (Functions I Can Call)

Location: .opencode/tool/<name>.ts

Purpose: New capabilities beyond built-in tools When to use: External APIs, complex operations, reusable functions

// .opencode/tool/database.ts import { tool } from '@opencode-ai/plugin';

export default tool({ description: 'Query the project database', args: { query: tool.schema.string().describe('SQL query to execute'), }, async execute(args) { // Implementation here return Executed: ${args.query}; }, });

Existing plugin in this project:

• browser_control.ts
• Local Chrome automation via native messaging bridge

5. MCP Servers (External Tools)

Location: opencode.json

Purpose: Connect to external tool servers When to use: Pre-built integrations, complex external services

Current MCP servers configured:

{ "mcp": { "exa": { "type": "remote", "url": "..." }, "notion": { "type": "local", "command": ["npx", "-y", "mcp-remote", "..."] }, "chrome": { "type": "local", "command": ["...", "chrome-devtools-mcp@latest"] }, "zero-finance": { "type": "remote", "url": "https://www.0.finance/api/mcp" } } }

When to Create Each Extension Type

Create a SKILL when:

• I need to remember how to use an API or service (endpoints, auth, formats)

• I keep looking up the same commands or workflows

• There's a multi-step process I'll repeat (deploy, test, debug cycles)

• I need to document gotchas and edge cases for future reference

• Example triggers:

• "How do I call the Stripe API again?"

• "What's the correct curl format for this endpoint?"

• "I keep forgetting the steps to deploy to staging"

Create an AGENT when:

• I need a different personality or expertise for a task

• The task requires a specific model (e.g., Opus for complex reasoning)

• I want to restrict tools for safety (read-only code reviewer)

• The task has a specialized prompt that's long and reusable

• Example triggers:

• "I need expert-level blockchain knowledge for this"

• "Review this code but don't modify anything"

• "Draft outreach messages with specific sales methodology"

Create a PLUGIN when:

• I need to react to events (session start, file edit, task complete)

• I want to modify behavior before/after tool execution

• I need notifications or external integrations on events

• I want to protect against mistakes (confirm before dangerous operations)

• Example triggers:

• "Notify me when a long task completes"

• "Log all file edits to a changelog"

• "Require confirmation before running destructive commands"

Create a TOOL when:

• I need to call an external API that isn't available via MCP

• I have a complex operation I want to encapsulate as a single call

• I need to run code in a specific language (Python, Ruby, etc.)

• The operation is stateful or requires persistence

• Example triggers:

• "Query the local database directly"

• "Run this Python script with arguments"

• "Interact with a local service on a specific port"

Add an MCP SERVER when:

• There's a pre-built MCP server for the service I need

• The integration is complex enough to warrant a separate process

• I need persistent connections (websockets, streaming)

• The server provides many related tools I'll use together

• Example triggers:

• "I need full GitHub API access"

• "Connect to a headless browser for automation"

• "Integrate with Slack/Discord/etc."

Decision Tree: What Should I Create?

Need to extend my capabilities? │ ├─ Just need to remember docs/commands/workflows? │ └─ Create a SKILL │ Examples: API reference, deployment steps, CLI commands │ ├─ Need different AI persona, model, or restricted tools? │ └─ Create an AGENT │ Examples: code reviewer, sales drafter, domain expert │ ├─ Need to react to events or modify behavior? │ └─ Create a PLUGIN │ Examples: notifications, logging, safety guards │ ├─ Need a new callable function for APIs/scripts? │ └─ Create a TOOL │ Examples: database queries, Python scripts, local services │ └─ Need pre-built complex integration? └─ Add an MCP SERVER Examples: GitHub, browser automation, Notion

Skill Structure Convention

Recommended Sections

Every skill should have these sections (add if missing):

name: skill-name description: One-line description

Quick Usage (Already Configured)

Most common commands - copy/paste ready

What I Do

[Core purpose]

Prerequisites

[Requirements]

Workflow

[Main steps]

Common Gotchas

Things that don't work as expected

Token Saving Tips

[Efficiency patterns]

Anti-Patterns to Avoid

[What NOT to do]

Real Examples

[Actual usage examples from this codebase]

First-Time Setup

Only needed once, keep at bottom

Rules for Documentation

• Update immediately - Don't wait until end of conversation

• Keep it copy/paste ready - Commands should work as-is

• Document the "why" - Explain gotchas, not just the fix

• Test before documenting - Only add confirmed working commands

• Remove outdated info - Delete commands that don't work

• Use this codebase's patterns - Reference actual files in packages/web/src/

Creating New Extensions

New Skill

mkdir -p .opencode/skill/<skill-name>

Template:

name: skill-name description: One-line description

Quick Usage (Already Configured)

Action 1

```bash command here ```

Common Gotchas

• Thing that doesn't work as expected

First-Time Setup (If Not Configured)

What you need from the user

1. ...

New Agent

touch .opencode/agent/<agent-name>.md

Template:

description: What this agent does mode: subagent # or "primary" model: anthropic/claude-sonnet-4-20250514 temperature: 0.3 tools: write: false edit: false bash: false

You are a [role]. Focus on:

• Task 1
• Task 2

New Tool

touch .opencode/tool/<tool-name>.ts

Template:

import { tool } from '@opencode-ai/plugin';

export default tool({ description: 'What this tool does', args: { param: tool.schema.string().describe('Parameter description'), }, async execute(args, context) { // Implementation return 'result'; }, });

Add MCP Server

Edit opencode.json :

{ "mcp": { "new-server": { "type": "local", "command": ["npx", "-y", "@scope/mcp-server-name"] } } }

Examples of Self-Improvement

Example 1: Fix Incorrect API Format

Context: curl command in skill used wrong flag Before: curl -d "urls=..."

After: curl -F "urls=..." (multipart/form-data required) Action: Updated skill with correct flag

Example 2: Add Missing Gotcha

Context: Assumed jq was available, command failed Action: Added to Common Gotchas:

Common Gotchas

• jq is NOT installed - use grep/cut for JSON parsing

Example 3: Create Agent for Repeated Task

Context: Kept doing Safe wallet debugging manually Action: Created .opencode/agent/safe-infrastructure.md with:

• Specialized prompt for wallet architecture

• Higher-tier model (Claude Opus)

• Access to Exa for blockchain docs

Example 4: Create Tool for API I Use Often

Context: Repeatedly calling browser bridge API Action: Created .opencode/plugin/browser_control.ts with:

• 12 browser control tools

• Error handling

• JSON response formatting

Example 5: Document Project-Specific Pattern

Context: Discovered Safe address must come from DB, not prediction Action: Added to safe-infrastructure.md :

CRITICAL RULE: ALWAYS query Safe addresses from the database. NEVER predict or derive addresses.

Project-Specific Knowledge to Preserve

Wallet Architecture (3-Layer Hierarchy)

Layer 1: Privy Embedded Wallet (EOA) - Signs transactions Layer 2: Privy Smart Wallet (Safe) - Gas sponsorship via 4337 Layer 3: Primary Safe - User's bank account (WHERE FUNDS ARE)

Key File Locations

Purpose File

Transaction relay packages/web/src/hooks/use-safe-relay.ts

Safe management packages/web/src/server/earn/multi-chain-safe-manager.ts

Chain constants packages/web/src/lib/constants/chains.ts

Design language packages/web/DESIGN-LANGUAGE.md

OpenCode config opencode.json

External Resources

Source Tool When to Use

Notion notion_* MCP Product copy, messaging, specs

Exa exa_* MCP Technical docs, code examples

Chrome DevTools chrome_* MCP Browser automation, testing

Basescan exa_crawling_exa

On-chain transaction analysis

Bootstrapping Flow

This repo is designed to be fully operational from a fresh git clone :

git clone → @bootstrap → working system

The Bootstrap Agent

Location: .opencode/agent/bootstrap.md

What it does:

• Detects environment - Node version, pnpm, Chrome, etc.

• Installs dependencies - pnpm install

• Tests MCP servers - Exa, Notion, Chrome

• Creates config - .opencode/config/workspace.json

• Sets up env vars - Creates .env.local from template

• Verifies everything - Type check, lint, build test

Graceful Degradation

Not everything needs to work for the repo to be useful:

Component If Missing Fallback

Exa MCP Web research unavailable Manual research

Notion CRM/docs unavailable Local-only development

Chrome Browser automation unavailable Manual browser testing

Database Can't run full app Can still do frontend work

Privy Can't test auth Mock auth in dev mode

The system should always tell the user what's degraded and how to fix it.

Reconstructing from Scratch

If everything breaks, delete derived files and re-bootstrap:

rm -rf node_modules rm -rf .opencode/config/workspace.json rm packages/web/.env.local

Then run @bootstrap

The only things that can't be reconstructed:

• API keys (user must provide)

• OAuth tokens (user must re-authorize)

• Database data (must restore from backup)

Integration with Other Meta-Skills

Skill Role

self-improve

HOW to update (templates, structures)

skill-reinforcement

WHEN to update (post-use triggers)

@bootstrap

SETUP from scratch (fresh clone)

@debug-workspace

FIX broken state (diagnose & repair)

@setup-workspace

CONFIGURE from Notion (load MCP Skills)

After using any skill, the skill-reinforcement skill should trigger to:

• Analyze what worked and what didn't

• Identify new patterns or shortcuts discovered

• Update the skill file with learnings

• Prevent knowledge loss between sessions

Quick Improvement Checklist

[ ] Something unexpected happened [ ] Identified the root cause [ ] Determined which extension type to use: [ ] Skill - just docs/commands [ ] Agent - specialized AI persona [ ] Plugin - event hooks [ ] Tool - new function [ ] MCP - external integration [ ] Created/updated the extension [ ] Tested the change works [ ] Validated formatting matches existing style [ ] Done

Meta: Improving This Skill

This skill should also improve itself. Track:

• New extension types or patterns discovered

• Better templates or examples found

• Project-specific knowledge worth preserving

• Integration patterns with other skills

Learnings Log

2026-01-08: Two-Layer Skill Pattern for Notion-Backed Skills

Context: Created company-admin skill that pulls data from Notion

Pattern: For skills that rely on external data (Notion, databases, etc.), create TWO layers:

• Notion page section (in MCP Skills page) - Runtime context the AI fetches

• Local skill file (.opencode/skill/*/SKILL.md ) - OpenCode-specific instructions

Why both?

• Notion page: Can be updated by anyone, provides live data

• Local skill: Works offline, has code examples, integrates with skill tool

Example structure:

Notion MCP Skills page:

Company Admin

• Trigger keywords
• Key resources table
• Company details table
• How it works

Local .opencode/skill/company-admin/SKILL.md:

• Page IDs for direct fetch
• Code examples
• Security rules
• Anti-patterns

Gotcha: The skill tool's available skills list may be cached. New skills might not appear immediately in the list but will work when loaded by name.