How OpenCode Integrates with the jakubkrehel/skills Repository: Complete Integration Guide

OpenCode integrates with the jakubkrehel/skills repository through a declarative configuration file named opencode.json that registers the skills/ directory, enabling automatic discovery and loading of markdown-based skill modules without requiring compilation or build steps.

The jakubkrehel/skills repository is a pure-documentation collection of Claude Code skills designed for design reviews, accessibility audits, and UI polish workflows. This repository contains no compiled code—only markdown and YAML files—making the OpenCode integration entirely declarative. When OpenCode loads this repository, it reads the configuration at the root and dynamically imports every skill defined in the subdirectory structure.

The opencode.json Configuration File

The integration begins with opencode.json located at the repository root. This single file acts as the manifest that tells OpenCode where to locate skill definitions.

The configuration structure declares a paths array pointing to the skills/ directory:

{
  "skills": {
    "paths": ["skills/"]
  }
}

When OpenCode initializes, it scans the paths listed in this configuration, treating every sub-folder under skills/ as an individual skill module. This registration mechanism eliminates the need for manual imports or build-time bundling, allowing the repository to function as a drop-in skill collection.

Automatic Skill Discovery Mechanism

Each skill resides in its own folder following the pattern skills/<skill-name>/. OpenCode discovers these skills by reading the directory structure referenced in opencode.json and parsing specific files within each folder.

Every skill folder must contain:

• SKILL.md — The human-readable entry point containing the skill description, usage instructions, and implementation details
• agents/openai.yaml — The model-invocation configuration defining how the skill interacts with OpenAI models via the OpenCode agent system

For example, the better-typography skill includes skills/better-typography/SKILL.md for documentation and skills/better-typography/agents/openai.yaml for runtime configuration. When OpenCode boots, it automatically registers these skills without additional build steps, reading the markdown descriptions and YAML configurations to make the skills callable via CLI or API.

Claude Code Plugin Architecture

The repository doubles as a Claude Code plugin through the .claude-plugin/plugin.json manifest. This file declares the plugin as interfaces and references the same skill collection registered in opencode.json.

When users install the plugin, OpenCode utilizes the identical registration mechanism defined in opencode.json, ensuring the plugin and standalone OpenCode loader share the exact same skill definitions. This architecture allows the repository to serve both as a direct OpenCode skill source and as a packaged plugin for the Claude Code ecosystem, with both entry points using the underlying skills/ directory structure.

Declarative Updates Without Compilation

Because jakubkrehel/skills contains only markdown and YAML files, OpenCode’s integration requires zero compilation. Adding, removing, or modifying a skill involves only editing files in the skills/ directory:

• Create a new folder under skills/ to add a skill
• Edit SKILL.md to update descriptions or instructions
• Modify agents/openai.yaml to change model behavior

The next time OpenCode loads the repository, changes reflect immediately. This zero-build approach enables rapid iteration on skill definitions and ensures the repository remains lightweight and version-control friendly.

Practical Usage Examples

Command Line Interface

Install and run skills using the Skills CLI, which leverages OpenCode under the hood:

# Install the skill collection

npx skills add jakubkrehel/skills

# List all available skills

skills list

# Execute a specific skill against your project

skills run better-typography --target ./my-project

Programmatic API Integration

Use the OpenCode SDK directly to load and invoke skills programmatically:

import { loadSkills } from '@opencode/sdk';

// Point to the local clone of the repository
const repoPath = '/path/to/jakubkrehel/skills';
const skillSet = await loadSkills(repoPath);   // Reads opencode.json automatically

// Run a specific skill with file targeting
const result = await skillSet.run('better-accessibility', {
  files: ['./src/**/*.html']
});

console.log(result);

This JavaScript example demonstrates how loadSkills() processes the opencode.json configuration to instantiate the skill set, allowing direct programmatic access to the repository's capabilities without CLI abstraction layers.

Summary

• opencode.json at the repository root registers the skills/ directory, serving as the single integration point between OpenCode and the jakubkrehel/skills repository.
• OpenCode automatically discovers skills by scanning subdirectories, reading SKILL.md for descriptions and agents/openai.yaml for model configuration.
• The repository functions as both a standalone OpenCode skill source and a Claude Code plugin via .claude-plugin/plugin.json, with both using the same underlying skill definitions.
• The integration requires no compiled code—changes to markdown or YAML files reflect immediately upon the next OpenCode initialization.
• Skills are accessible via CLI tools, the Skills-CLI wrapper, or direct JavaScript API calls using the @opencode/sdk package.

Frequently Asked Questions

What is the purpose of the opencode.json file in the jakubkrehel/skills repository?

The opencode.json file acts as the registration manifest that enables OpenCode to integrate with the repository. It contains a JSON object declaring the skills.paths array, which points OpenCode to the skills/ directory. Without this file, OpenCode would not know where to locate or how to load the skill modules contained in the repository.

How does OpenCode discover individual skills within the repository?

OpenCode discovers skills by reading the directory structure specified in opencode.json. For each subfolder under skills/, OpenCode looks for a SKILL.md file containing the skill description and an agents/openai.yaml file containing model invocation parameters. Each subfolder name becomes the skill identifier used when calling the skill via CLI or API.

Can I use the jakubkrehel/skills repository without the Claude Code plugin?

Yes. The repository works as a standalone OpenCode skill collection independent of the Claude Code plugin system. You can load the repository directly using the OpenCode SDK or CLI by pointing to the repository path, and opencode.json will register the skills automatically. The .claude-plugin/plugin.json file only adds a packaging layer for Claude Code distribution but does not affect the core OpenCode integration.

What files are required to create a new skill in this repository?

To create a valid skill, you need a folder under skills/<skill-name>/ containing at least two files: SKILL.md (the entry point documenting the skill's purpose and usage) and agents/openai.yaml (defining the OpenAI model configuration and invocation parameters). Once these files exist in a subdirectory of skills/, OpenCode will automatically register the new skill the next time it loads the repository, with no additional configuration changes required.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}