OpenCodeSystem

Customization

Before executing, check for user customizations at: ~/.opencode/PAI/USER/SKILLCUSTOMIZATIONS/OpenCodeSystem/

If this directory exists, load and apply any PREFERENCES.md, configurations, or resources found there. These override default behavior. If the directory does not exist, proceed with skill defaults.

OpenCodeSystem — System Self-Awareness

System self-awareness for PAI-OpenCode. Enables the Algorithm to answer questions about its own operating environment without asking the user or hallucinating.

Visibility

This skill runs in the foreground. All lookups and diagnostic output should be visible to maintain transparency.

MANDATORY — Quick Reference

MANDATORY — Key Facts (Inline — No File Read Needed)

Runtime Identity

• Platform: OpenCode (NOT Claude Code — never use ~/.claude/)
• Correct path: ~/.opencode/
• Project config: opencode.json (root) + settings.json (~/.opencode/)
• Plugin entry: .opencode/plugins/pai-unified.ts

Custom Tools Always Available

Model Tiers

• quick → fast, cheap (exploration, simple tasks)
• standard → balanced (default for most agents)
• advanced → complex reasoning (Algorithm agent)
• Actual model names resolved from opencode.json — never hardcode

The 2-Second Rule

If Grep, Glob, or Read can answer in <2 seconds → use them directly. Never spawn an agent for what a direct tool call can do instantly.

Critical Path Rules

bash workdir parameter → ALWAYS (never cd &&)
imports             → ALWAYS include .ts extension
package manager     → ALWAYS bun (never npm/yarn/pnpm)
memory paths        → ALWAYS ~/.opencode/ (never ~/.claude/)

MANDATORY — When Something Doesn't Work

Walk docs/architecture/Troubleshooting.md top-to-bottom. The checklist covers:

1. Plugin not loading
2. Custom tools missing
3. Post-compaction recovery
4. Model routing issues
5. Path errors
6. Skill not triggering
7. Runtime/bun errors
8. Agent spawn issues

OPTIONAL — Architecture in 30 Seconds

opencode.json          → model routing, permissions, agent definitions
pai-unified.ts         → single plugin, all event hooks registered
handlers/              → 20+ modular handlers (session, security, capture, etc.)
AGENTS.md              → Algorithm's runtime operating instructions
skills/skill-index.json → skill discovery registry for CAPABILITY AUDIT
~/.opencode/MEMORY/    → PRDs, session data, reflections

Full details: docs/architecture/SystemArchitecture.md

OPTIONAL — USE WHEN Triggers

• "What tools do I have?"
• "What custom tools are available?"
• "How is model routing configured?"
• "What MCP servers are connected?"
• "Why isn't the plugin firing?"
• "What's the difference between opencode.json and settings.json?"
• "How do I troubleshoot X not working?"
• "What agents can I spawn?"
• "Where is the memory stored?"
• "What hooks does the plugin register?"
• Any question about the operating environment, directory structure, or system configuration

Tools

Workflows

No dedicated workflow files. Operational procedures for the tools above are documented inline in each tool's source header and in docs/DB-MAINTENANCE.md (archival) and docs/MIGRATION.md (v2→v3 migration).

Related Skills

• PAI — Algorithm core, ISC creation, verification
• System — System maintenance, integrity check, documentation