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

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, 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: The central entry point that catalogs all available skills and provides installation instructions via npx skills add.
• AGENTS.md: Core behavioral guidelines dictating how coding agents should operate within the repository context.
• CLAUDE.md: A thin wrapper that imports AGENTS.md for Claude-Code integration.
• opencode.json: Registers the skills/ folder as a searchable namespace for the Opencode CLI.
• .claude-plugin/: Contains plugin.json and 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:

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 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.
• 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 file within these directories typically disables autonomous model invocation, requiring explicit CLI triggers.

Model Configuration and Agent Behavior

Each skill's 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:

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:

npx skills invoke better-typography

The CLI locates skills/better-typography/SKILL.md and executes the associated OpenAI model using parameters from agents/openai.yaml.

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

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 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, 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 + 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 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.

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 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 file declares the repository as a plugin named "interfaces", while 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 and AGENTS.md files.

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