# jakubkrehel/skills Repository Structure: A Complete Guide to Agent Skill Organization

> Discover the flat architecture of the jakubkrehel/skills repository. Learn how each agent skill is organized with standardized files and discoverability without a build step.

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

---

**The jakubkrehel/skills repository follows a flat, documentation-only architecture where each UI skill occupies a dedicated subdirectory under `skills/`, governed by standardized files ([`SKILL.md`](https://github.com/jakubkrehel/skills/blob/main/SKILL.md), [`agents/openai.yaml`](https://github.com/jakubkrehel/skills/blob/main/agents/openai.yaml)) and top-level configuration that enables CLI discovery without any build step.**

The **jakubkrehel/skills** repository is a pure-documentation collection that defines agent skills for building and reviewing user interfaces. It contains no runtime code or compiled artifacts—only structured markdown and YAML configurations that coding agents consume. According to the source code, this design separates metadata, skill definitions, and plugin configuration into a self-contained hierarchy that both human developers and automated tools can navigate effortlessly.

## Top-Level Configuration Files

The root directory serves as the control plane for the entire skill collection. These files provide discovery metadata and agent behavioral guidelines:

- **[`README.md`](https://github.com/jakubkrehel/skills/blob/main/README.md)**: The central entry point that catalogs all available skills and provides installation instructions via `npx skills add`.
- **[`AGENTS.md`](https://github.com/jakubkrehel/skills/blob/main/AGENTS.md)**: Core behavioral guidelines dictating how coding agents should operate within the repository context.
- **[`CLAUDE.md`](https://github.com/jakubkrehel/skills/blob/main/CLAUDE.md)**: A thin wrapper that imports [`AGENTS.md`](https://github.com/jakubkrehel/skills/blob/main/AGENTS.md) for Claude-Code integration.
- **[`opencode.json`](https://github.com/jakubkrehel/skills/blob/main/opencode.json)**: Registers the `skills/` folder as a searchable namespace for the Opencode CLI.
- **`.claude-plugin/`**: Contains [`plugin.json`](https://github.com/jakubkrehel/skills/blob/main/plugin.json) and [`marketplace.json`](https://github.com/jakubkrehel/skills/blob/main/marketplace.json), declaring the repository as a Claude-Code plugin named "interfaces".

## The skills/ Directory Namespace

The `skills/` directory contains individual skill subdirectories, each representing a discrete capability for UI development. Every skill follows a consistent internal structure:

```text
skills/<skill-name>/
    SKILL.md              # Human-readable entry point and specification

    agents/
        openai.yaml       # Model invocation settings (temperature, prompts, policies)

    *.md                  # Optional supplemental articles and reference tables

```

This flat namespace allows tools to discover skills by scanning directory names and loading the standardized [`SKILL.md`](https://github.com/jakubkrehel/skills/blob/main/SKILL.md) entry point.

### Domain-Oriented Skills (better-*)

The repository includes a family of "better-*" skills that specialize in specific UI domains:

- **`better-interface`**: An orchestrator skill that aggregates findings from all `better-*` subskills, located in [`skills/better-interface/SKILL.md`](https://github.com/jakubkrehel/skills/blob/main/skills/better-interface/SKILL.md).
- **`better-ui`**: Covers iconography, animations, and touch target sizing.
- **`better-typography`**: Manages variable fonts, line spacing, and text hierarchy.
- **`better-colors`**: Defines color tokens, contrast ratios, and palette structure.
- **`better-accessibility`**: Enforces semantic HTML, keyboard navigation, and motion preferences.
- **`better-layout`**: Handles component grouping, alignment, and responsive adaptivity.
- **`better-writing`**: Governs product copy, terminology consistency, and microcopy.

### User-Invoked Skills

Several skills require explicit user interaction rather than autonomous agent invocation:

- **`interface-review`**: Performs diff-based code reviews by aggregating all `better-*` skill findings, configured in `skills/interface-review/`.
- **`explain-interface`**: Analyzes UI elements from images or code snippets to explain construction methods.
- **`break`**: Stress-tests components across edge-case scenarios.
- **`variant`**: Generates alternative design implementations for existing components.

The [`agents/openai.yaml`](https://github.com/jakubkrehel/skills/blob/main/agents/openai.yaml) file within these directories typically disables autonomous model invocation, requiring explicit CLI triggers.

## Model Configuration and Agent Behavior

Each skill's [`agents/openai.yaml`](https://github.com/jakubkrehel/skills/blob/main/agents/openai.yaml) file specifies how the OpenAI model processes requests. These YAML configurations define model selection, temperature settings, and invocation policies—distinguishing between autonomous execution and user-triggered operations.

For example, domain skills like `better-typography` may run automatically when an agent detects relevant code changes, while user-invoked skills like `interface-review` disable automatic execution to require explicit human oversight before processing diffs.

## Installation and Usage Patterns

The repository integrates with the Opencode CLI and supports programmatic invocation.

Install the entire skill collection:

```bash
npx skills add jakubkrehel/skills

```

This command registers all skill definitions locally by scanning the `skills/` directory structure.

Invoke a specific skill on the current project:

```bash
npx skills invoke better-typography

```

The CLI locates [`skills/better-typography/SKILL.md`](https://github.com/jakubkrehel/skills/blob/main/skills/better-typography/SKILL.md) and executes the associated OpenAI model using parameters from [`agents/openai.yaml`](https://github.com/jakubkrehel/skills/blob/main/agents/openai.yaml).

For user-invoked skills, programmatic access requires explicit execution:

```javascript
const { execSync } = require('child_process');

// Trigger interface-review with user prompting for diff input
execSync('npx skills invoke interface-review', { stdio: 'inherit' });

```

The `interface-review` skill checks its [`agents/openai.yaml`](https://github.com/jakubkrehel/skills/blob/main/agents/openai.yaml) configuration to determine that it requires user interaction before processing.

## Summary

- The **jakubkrehel/skills** repository contains zero runtime code—only documentation and configuration files.
- **Top-level files** ([`README.md`](https://github.com/jakubkrehel/skills/blob/main/README.md), [`opencode.json`](https://github.com/jakubkrehel/skills/blob/main/opencode.json), `.claude-plugin/`) provide discovery metadata and plugin manifests.
- The **`skills/`** directory uses a flat namespace where each subdirectory represents one skill.
- **Standard conventions** ([`SKILL.md`](https://github.com/jakubkrehel/skills/blob/main/SKILL.md) + [`agents/openai.yaml`](https://github.com/jakubkrehel/skills/blob/main/agents/openai.yaml)) enable automated tool discovery without build steps.
- **Two skill types** exist: autonomous domain skills (`better-*`) and user-invoked review tools (`interface-review`, `break`, etc.).

## Frequently Asked Questions

### What is the purpose of the agents/openai.yaml file?

The [`agents/openai.yaml`](https://github.com/jakubkrehel/skills/blob/main/agents/openai.yaml) file located in each skill's `agents/` subdirectory configures how the OpenAI model processes that specific skill. It defines model parameters, system prompts, and invocation policies—such as whether the skill runs autonomously or requires explicit user confirmation. This file separates model behavior from the human-readable documentation in [`SKILL.md`](https://github.com/jakubkrehel/skills/blob/main/SKILL.md).

### How do I add skills from the jakubkrehel/skills repository to my project?

Use the Opencode CLI command `npx skills add jakubkrehel/skills` to fetch the repository and register all skill definitions locally. This command scans the `skills/` directory and makes each skill available for invocation via `npx skills invoke <skill-name>`, without requiring you to clone the repository manually or run any build scripts.

### What distinguishes user-invoked skills from domain-oriented skills?

**Domain-oriented skills** (the `better-*` family) typically run automatically when an agent detects relevant UI code, focusing on specific aspects like typography or color. **User-invoked skills** like `interface-review` and `break` require explicit triggering via CLI commands because they perform intensive operations like full codebase diffs or stress-testing that need human oversight. The distinction is controlled by settings in each skill's [`agents/openai.yaml`](https://github.com/jakubkrehel/skills/blob/main/agents/openai.yaml) file.

### Where is the Claude-Code plugin configuration stored?

The Claude-Code plugin metadata resides in the `.claude-plugin/` directory at the repository root. The [`plugin.json`](https://github.com/jakubkrehel/skills/blob/main/plugin.json) file declares the repository as a plugin named "interfaces", while [`marketplace.json`](https://github.com/jakubkrehel/skills/blob/main/marketplace.json) contains publishing metadata. This configuration allows Claude-Code to recognize and load the skill collection when users install the plugin, importing behavior guidelines from the adjacent [`CLAUDE.md`](https://github.com/jakubkrehel/skills/blob/main/CLAUDE.md) and [`AGENTS.md`](https://github.com/jakubkrehel/skills/blob/main/AGENTS.md) files.