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

> Discover how OpenCode integrates with the jakubkrehel/skills repository. Learn to automatically load skill modules via a simple opencode.json configuration. No compilation needed.

- Repository: [Jakub Krehel/skills](https://github.com/jakubkrehel/skills)
- Tags: how-to-guide
- Published: 2026-09-12

---

**OpenCode integrates with the jakubkrehel/skills repository through a declarative configuration file named [`opencode.json`](https://github.com/jakubkrehel/skills/blob/main/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`](https://github.com/jakubkrehel/skills/blob/main/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:

```json
{
  "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`](https://github.com/jakubkrehel/skills/blob/main/opencode.json) and parsing specific files within each folder.

Every skill folder must contain:

- **[`SKILL.md`](https://github.com/jakubkrehel/skills/blob/main/SKILL.md)** — The human-readable entry point containing the skill description, usage instructions, and implementation details
- **[`agents/openai.yaml`](https://github.com/jakubkrehel/skills/blob/main/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`](https://github.com/jakubkrehel/skills/blob/main/skills/better-typography/SKILL.md) for documentation and [`skills/better-typography/agents/openai.yaml`](https://github.com/jakubkrehel/skills/blob/main/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`](https://github.com/jakubkrehel/skills/blob/main/.claude-plugin/plugin.json)** manifest. This file declares the plugin as **`interfaces`** and references the same skill collection registered in [`opencode.json`](https://github.com/jakubkrehel/skills/blob/main/opencode.json).

When users install the plugin, OpenCode utilizes the identical registration mechanism defined in [`opencode.json`](https://github.com/jakubkrehel/skills/blob/main/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`](https://github.com/jakubkrehel/skills/blob/main/SKILL.md) to update descriptions or instructions
- Modify [`agents/openai.yaml`](https://github.com/jakubkrehel/skills/blob/main/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:

```bash

# 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:

```javascript
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`](https://github.com/jakubkrehel/skills/blob/main/opencode.json) configuration to instantiate the skill set, allowing direct programmatic access to the repository's capabilities without CLI abstraction layers.

## Summary

- **[`opencode.json`](https://github.com/jakubkrehel/skills/blob/main/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`](https://github.com/jakubkrehel/skills/blob/main/SKILL.md) for descriptions and [`agents/openai.yaml`](https://github.com/jakubkrehel/skills/blob/main/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`](https://github.com/jakubkrehel/skills/blob/main/.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`](https://github.com/jakubkrehel/skills/blob/main/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`](https://github.com/jakubkrehel/skills/blob/main/opencode.json). For each subfolder under `skills/`, OpenCode looks for a [`SKILL.md`](https://github.com/jakubkrehel/skills/blob/main/SKILL.md) file containing the skill description and an [`agents/openai.yaml`](https://github.com/jakubkrehel/skills/blob/main/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`](https://github.com/jakubkrehel/skills/blob/main/opencode.json) will register the skills automatically. The [`.claude-plugin/plugin.json`](https://github.com/jakubkrehel/skills/blob/main/.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`](https://github.com/jakubkrehel/skills/blob/main/SKILL.md) (the entry point documenting the skill's purpose and usage) and [`agents/openai.yaml`](https://github.com/jakubkrehel/skills/blob/main/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.