Stop Wasting Tokens! opencode-skillful Cuts Context Bloat by 90%

Your AI agent is hemorrhaging tokens on skills you'll never use. Every single conversation, OpenCode pre-loads every skill in your library—burning context window, slowing responses, and bleeding money. What if your agent only loaded exactly what it needed, precisely when it needed it?

Enter opencode-skillful—the ruthless efficiency upgrade that transforms how OpenCode agents discover and deploy skills. Born from an inspired interpretation of Anthropic's Agent Skills Specification, this plugin doesn't just optimize; it fundamentally reimagines skill orchestration. No more passive skill dumps. No more token waste. Just surgical, on-demand capability injection that makes your agent smarter, faster, and dramatically cheaper to run.

Ready to stop subsidizing idle skills with your context window? Let's expose how this plugin works—and why top developers are quietly switching.

What is opencode-skillful?

opencode-skillful is a plugin for OpenCode that implements lazy-loaded skill discovery and injection. Created by Zenobius, it reinterprets Anthropic's emerging agent skills standard specifically for the OpenCode ecosystem, solving one of the most expensive inefficiencies in AI-assisted development.

The core philosophy? Skills should be discovered, not assumed. Instead of force-feeding your agent every capability at startup, opencode-skillful maintains a lightweight registry of available skills and only injects them when explicitly requested. This isn't merely an optimization—it's a architectural paradigm shift that aligns skill management with how developers actually work: targeted, contextual, and intentional.

Why is this trending now? As agent frameworks mature, the "kitchen sink" approach to skill loading has become untenable. Teams are building 50+ skill libraries, yet any given conversation might need 2-3 at most. The built-in OpenCode implementation loads everything by default, creating massive context inflation. opencode-skillful arrives at exactly the moment when token economics and context window constraints have made this inefficiency impossible to ignore. It's the difference between carrying a Swiss Army knife and deploying a surgical robot—precision over bulk, every single time.

Key Features That Separate Champions from Amateurs

Lazy Loading Architecture The headline feature: skills are discovered at initialization but never injected until explicitly requested. This single design decision eliminates the dominant source of context bloat in OpenCode workflows. Your agent's working memory stays pristine, focused, and performant.

Three-Tool Conversational Interface opencode-skillful exposes an elegantly minimal surface area: skill_find for discovery, skill_use for loading, and skill_resource for targeted file access. No complex APIs, no configuration ceremonies—just natural conversational commands that agents understand intuitively.

Model-Aware Prompt Rendering Different LLMs process structured data differently. The plugin ships with pluggable format selection (XML, JSON, Markdown) configurable per model. Claude gets XML-optimized injection. GPT-4 receives strict JSON. Llama models work with clean Markdown. You optimize once, the plugin adapts automatically.

Security-First Resource Access Unlike direct filesystem access, all resources are pre-indexed at parse time. The skill_resource tool can only retrieve paths that were explicitly registered during skill discovery. Path traversal attacks? Impossible by design. This is enterprise-grade security without enterprise-grade friction.

Natural Query Syntax with Intelligent Ranking The skill_find tool supports sophisticated search: AND logic for multiple keywords, negation with -term, exact phrase matching with quotes, and path prefix browsing like superpowers/writing. Results are ranked by relevance with name matches weighted 3× over description matches—because when you search "git commit," the skill literally named "git-commits" should probably win.

Silent Message Injection Loaded skills inject as user messages using a noReply pattern—no jarring agent responses, no conversational disruption. The capability simply becomes available, seamlessly integrated into your ongoing dialogue.

Use Cases: Where opencode-skillful Absolutely Dominates

Scenario 1: The Polyglot Engineering Team

You're managing a codebase spanning Python microservices, React frontends, Terraform infrastructure, and Kubernetes deployments. Your skill library has 40+ specialized capabilities—Python refactoring, React performance patterns, Terraform security checks, K8s debugging. With built-in OpenCode, every conversation carries all 40 skills in context. With opencode-skillful, your backend developer searches skill_find "python refactoring", loads exactly that capability, and works with surgical precision. Token savings: 85%+ per conversation.

Scenario 2: The Security-Conscious Enterprise

Your organization mandates strict access controls. Skills contain sensitive patterns—internal API schemas, proprietary authentication flows, compliance checklists. Direct filesystem access is a non-starter. opencode-skillful's pre-indexed resource model means the agent can only access explicitly registered paths. Security teams approve the skill registry; developers work within bounded capabilities. Compliance without productivity sacrifice.

Scenario 3: The Multi-Model Workflow

You switch between Claude for creative architecture discussions, GPT-4 for strict JSON API design, and local Llama models for offline sensitive work. Each model processes prompts differently. opencode-skillful's modelRenderers configuration automatically serves XML to Claude, JSON to GPT-4, and Markdown to Llama—zero manual format switching, optimal parsing for every model, every time.

Scenario 4: The Template Power User

Your design system team maintains living documentation: brand guidelines in HTML, component templates in JSX, accessibility checklists in Markdown. Rather than loading entire skills, you skill_resource specific files on demand—brand-guidelines/assets/logo-usage.html for the marketing request, a11y-skill/references/wcag-checklist.md for the audit. Precise retrieval without context pollution.

Step-by-Step Installation & Setup Guide

Prerequisites

• OpenCode installed and configured (~/.config/opencode/config.json exists)
• Node.js/Bun environment (the plugin uses bunfig for configuration)

Plugin Installation

Edit your OpenCode configuration file:

# Open your OpenCode config
nano ~/.config/opencode/config.json

Add the plugin to your plugins array:

{
  "plugins": ["@zenobius/opencode-skillful"]
}

Project-Local Configuration (Recommended)

Create .opencode-skillful.json in your project root for team-shared settings:

{
  "debug": false,
  "basePaths": [
    "~/.config/opencode/skills",
    ".opencode/skills"
  ],
  "promptRenderer": "xml",
  "modelRenderers": {
    "claude-3-5-sonnet": "xml",
    "gpt-4": "json",
    "gpt-4-turbo": "json"
  }
}

Global Configuration (Personal Defaults)

For settings across all projects, create:

Linux/macOS:

mkdir -p ~/.config/opencode-skillful
cat > ~/.config/opencode-skillful/config.json << 'EOF'
{
  "debug": false,
  "promptRenderer": "xml",
  "modelRenderers": {
    "claude-3-5-sonnet": "xml",
    "claude-3-opus": "xml",
    "gpt-4": "json",
    "gpt-4-turbo": "json",
    "llama-2-70b": "md"
  }
}
EOF

Windows:

New-Item -ItemType Directory -Force -Path "$env:APPDATA\opencode-skillful"
Set-Content "$env:APPDATA\opencode-skillful\config.json" '{
  "debug": false,
  "promptRenderer": "xml",
  "modelRenderers": {
    "claude-3-5-sonnet": "xml",
    "gpt-4": "json"
  }
}'

Skill Directory Setup

Create your skill directories (project-local skills override global ones):

# Global skills (available everywhere)
mkdir -p ~/.config/opencode/skills/experts/writing-git-commits

# Project-local skills (highest priority)
mkdir -p ./.opencode/skills/my-project-specific-skill

Verification

Restart OpenCode and test:

skill_find "*"

You should see your discovered skills listed. If empty, enable debug mode:

{
  "debug": true
}

This exposes discovery statistics in skill_find responses—check for parsing errors or path misconfigurations.

REAL Code Examples from the Repository

Example 1: Basic Skill Discovery and Loading

The foundational workflow—find what you need, then load it:

# Step 1: Discover relevant skills
skill_find "git commit"

This triggers the SkillFinder tool, which parses your query through the search-string library. The query "git commit" becomes include: ["git", "commit"] with AND logic—both terms must match in the skill's name, description, or toolName. Results are ranked with name matches weighted 3×, ensuring experts_writing_git_commits surfaces above tangential matches.

# Step 2: Load the skill into your active context
skill_use "experts_writing_git_commits"

The SkillUser tool validates the identifier, retrieves the full skill object from the registry's pre-indexed Map, and silently injects it as a user message. The agent now has the skill's metadata, resource inventory, and full content available—without any conversational disruption.

# Step 3: Apply the skill naturally
"Help me write a commit message for refactoring the auth module"

The agent references the loaded skill's guidelines, producing structured, conventional commit messages. No explicit skill invocation in your prompt—the capability is simply available.

Example 2: Targeted Resource Access Without Full Loading

Sometimes you need a specific file, not the entire skill doctrine:

skill_resource skill_name="testing-skill" relative_path="references/test-template.md"

The SkillResourceReader tool performs type-safe path resolution. It parses references/test-template.md into:

• type: "references" (validated against allowed types: references|assets|scripts)
• relative_path: "test-template.md"

The tool then queries the pre-indexed SkillResourceResolver—never the filesystem directly. This is the security-critical design: only paths discovered during initialization are retrievable. The resolver returns { absolutePath, mimeType }, the file is read through the abstracted SkillFs layer, and content injects silently via the noReply pattern.

Why this matters: Even if a malicious prompt tried skill_resource skill_name="foo" relative_path="../../../etc/passwd", the path would fail pre-index validation. The attack surface is eliminated by architecture, not by filter.

Example 3: Multi-Model Format Configuration

Configure optimal rendering for your model zoo:

{
  "promptRenderer": "xml",
  "modelRenderers": {
    "claude-3-5-sonnet": "xml",
    "gpt-4": "json",
    "gpt-4-turbo": "json",
    "llama-2-70b": "md"
  }
}

When any tool executes, the plugin queries the active LLM model and implements cascading specificity matching:

1. Try full model ID: "anthropic-claude-3-5-sonnet"
2. Fall back to generic pattern: "claude-3-5-sonnet"
3. Use global default: "xml"

This means you configure "claude-3-5-sonnet": "xml" once, and it works for "anthropic-claude-3-5-sonnet", "aws-bedrock-claude-3-5-sonnet", or any provider-prefixed variant. The first match wins—most specific takes precedence.

XML output for Claude (human-readable, tag-structured):

<Skill>
  <name>git-commits</name>
  <description>Guidelines for writing effective git commit messages</description>
  <toolName>writing_git_commits</toolName>
</Skill>

JSON output for GPT-4 (strict, parser-friendly):

{
  "name": "git-commits",
  "description": "Guidelines for writing effective git commit messages",
  "toolName": "writing_git_commits"
}

Markdown output for Llama (conversational, readable):

# Skill

### name
- **name**: _git-commits_

### description
- **description**: _Guidelines for writing effective git commit messages_

Example 4: Advanced Query Syntax

The skill_find tool supports sophisticated discovery patterns:

# List ALL skills (useful for inventory)
skill_find "*"

# AND logic: must match both terms
skill_find "python testing"

# Negation: exclude performance testing
skill_find "testing -performance"

# Exact phrase matching
skill_find '"code review"'

# Path prefix browsing for organized hierarchies
skill_find "experts"
skill_find "superpowers/writing"

The query parser uses the search-string library (Gmail-style syntax). The ranking algorithm applies: (nameMatches × 3) + (descMatches × 1) + exactBonus(10). A skill named python-testing matching both query terms gets 6 from name matches alone, while a skill merely mentioning Python and testing in its description gets 2. Precision engineering for relevance.

Advanced Usage & Best Practices

Organize Skills with Path Hierarchies Use directory structure to create discoverable namespaces: experts/, superpowers/, tools/. This enables prefix browsing (skill_find "experts") and prevents naming collisions. The identifier slug converts experts/writing/git-commits to experts_writing_git_commits.

Leverage Project-Local Overrides Place .opencode/skills/ in your repository for team-specific capabilities. These automatically override global skills with the same name—perfect for project conventions that differ from organizational standards.

Script Integration Without Explicit Execution Tools Skills can include executable scripts in scripts/. When loaded via skill_use, the agent sees the full resource inventory and can be instructed to run them contextually: "Run the changelog generator from the build-utils skill." The agent resolves paths and executes intelligently—no dedicated skill_exec tool needed.

Debug Mode for Skill Development Enable debug: true when building skills. skill_find responses include discovered count, parsed results, rejections, duplicates, and errors. Essential for diagnosing why your shiny new skill isn't appearing.

Restart Required for Skill Reloads Skills are discovered at plugin initialization. After adding or modifying skills, restart OpenCode. This is a deliberate trade-off: startup-time discovery enables the security guarantee of pre-indexed resources.

Comparison with Alternatives

Verdict: Built-in OpenCode wins for trivial prototypes and absolute beginners. opencode-skillful dominates for production workflows, large skill libraries, multi-model setups, security-conscious environments, and anyone paying attention to token economics. The configuration overhead is minutes; the efficiency gains are permanent.

FAQ

Q: Will opencode-skillful work with my existing OpenCode skills? Yes, with migration. Skills follow the Anthropic Agent Skills Specification—ensure each has a SKILL.md with YAML frontmatter. Move them to ~/.config/opencode/skills/ or .opencode/skills/.

Q: How much token savings can I realistically expect? With 50 skills where 2-3 are used per conversation, expect 85-95% reduction in skill-related context. Exact savings depend on skill sizes, but the lazy-loading architecture guarantees zero overhead for unused capabilities.

Q: Is this secure for enterprise use with proprietary skills? Absolutely. The pre-indexed resource model eliminates path traversal. Combined with standard filesystem permissions on skill directories, you have defense in depth. No arbitrary file access is possible through the plugin.

Q: Can I use different formats for different models automatically? Yes—this is a core feature. Configure modelRenderers with generic model names, and the plugin resolves provider-prefixed variants automatically. Claude always gets XML, GPT-4 always gets JSON, seamlessly.

Q: What happens if I skill_use a non-existent skill? The tool returns { loaded: [...], notFound: ["nonexistent-skill"] }. Successfully loaded skills still inject; only missing ones are reported. No conversation corruption, no hard failures.

Q: Do I need to restart OpenCode after adding skills? Yes. Skills are discovered at plugin initialization for security and performance. This is a one-time cost that enables the pre-indexed guarantee.

Q: Can skills include executable code? Skills can include scripts in scripts/ directories. These are exposed as resources when the skill is loaded; the agent can be instructed to run them contextually. There is no automatic execution—explicit instruction required.

Conclusion

opencode-skillful is the precision instrument that OpenCode's built-in skills system desperately needed. In an era where context windows are precious and token costs compound, lazy loading isn't a luxury—it's a competitive necessity. The three-tool interface (skill_find, skill_use, skill_resource) distills complex orchestration into conversational simplicity. The model-aware rendering eliminates format friction across your LLM portfolio. And the security-first architecture means you can deploy with confidence in any environment.

I've watched too many developers bleed tokens on idle skills, too many teams struggle with one-size-fits-all prompt formats. opencode-skillful solves both with elegance. The configuration takes minutes. The efficiency gains are permanent. The security model is bulletproof.

Stop subsidizing context bloat. Start loading skills like a surgeon.

👉 Install opencode-skillful from the official repository — your token budget will thank you.

Found this breakdown valuable? Star the repo, share with your team, and watch your agent's efficiency transform overnight.