# How to Add a New Skill to the jakubkrehel/skills Repository: A Complete Guide

> Learn to add a new skill to the jakubkrehel/skills repository with our complete guide. Follow simple steps to create directories, configure files, and update your README.

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

---

**To add a new skill to the jakubkrehel/skills repository, create a kebab-case directory under `skills/`, add a [`SKILL.md`](https://github.com/jakubkrehel/skills/blob/main/SKILL.md) file with front-matter, configure an [`agents/openai.yaml`](https://github.com/jakubkrehel/skills/blob/main/agents/openai.yaml) file, update the top-level [`README.md`](https://github.com/jakubkrehel/skills/blob/main/README.md), increment the version in [`.claude-plugin/plugin.json`](https://github.com/jakubkrehel/skills/blob/main/.claude-plugin/plugin.json), and validate your changes using the built-in CLI commands.**

The `jakubkrehel/skills` repository hosts a collection of documentation-only skills for Claude Code. Each skill is **self-contained** within its own directory and follows strict naming and formatting conventions defined in [`AGENTS.md`](https://github.com/jakubkrehel/skills/blob/main/AGENTS.md). This guide walks through the complete process of adding a new skill, from initial directory creation to final validation.

## Prerequisites and Naming Conventions

Before creating files, consult [`AGENTS.md`](https://github.com/jakubkrehel/skills/blob/main/AGENTS.md) for the repository's style guide. All skills must use **kebab-case** identifiers that remain consistent across three locations: the directory name (`skills/<your-skill-name>/`), the front-matter `name` field in [`SKILL.md`](https://github.com/jakubkrehel/skills/blob/main/SKILL.md), and the `display_name` in [`agents/openai.yaml`](https://github.com/jakubkrehel/skills/blob/main/agents/openai.yaml). The documentation enforces sentence-case headings, no serial commas, and a maximum of 30 words per sentence.

The repository structure is registered in [`opencode.json`](https://github.com/jakubkrehel/skills/blob/main/opencode.json), which points to the `skills/` directory for automatic discovery. Keeping names synchronized ensures the harness can locate and load your skill correctly.

## Step-by-Step Implementation

### Create the Skill Directory

Start by creating a new folder under `skills/` using kebab-case naming:

```bash
mkdir skills/better-my-skill

```

This directory will contain all assets for your skill. The name must match exactly in the three locations mentioned above to prevent loading errors.

### Write the SKILL.md Entry Point

Create a [`SKILL.md`](https://github.com/jakubkrehel/skills/blob/main/SKILL.md) file inside your skill directory. This file requires YAML front-matter containing the `name` and a concise one-sentence `description`, followed by the skill's content:

```markdown
---
name: better-my-skill
description: Improves XYZ aspects of a project.
---

# Better My Skill

**What it does** – Short, concrete statement of the skill’s purpose.

## Principle 1 – Exact rule

Your rule here with specific guidelines.

## Reporting

| Finding | Recommendation |
|---------|----------------|
| Issue   | Solution       |

```

Follow the prose style rules from [`AGENTS.md`](https://github.com/jakubkrehel/skills/blob/main/AGENTS.md): use sentence-case headings, avoid serial commas, and keep sentences under 30 words.

### Configure the Agent

Add an [`agents/openai.yaml`](https://github.com/jakubkrehel/skills/blob/main/agents/openai.yaml) file to declare the agent type and invocation policy. Create the directory structure and file:

```bash
mkdir skills/better-my-skill/agents

```

Then add the configuration:

```yaml
model: openai
disable-model-invocation: true
policy:
  allow_implicit_invocation: false

```

This mirrors the layout used by existing skills such as `variant` and `better-ui`. For user-invoked skills, set `disable-model-invocation: true` and `allow_implicit_invocation: false` to prevent automatic triggering.

### Add Optional Documentation

You may include additional `.md` files alongside [`SKILL.md`](https://github.com/jakubkrehel/skills/blob/main/SKILL.md) for recipes, lookup tables, or extended examples. Keep these files within the skill directory and link them from the main [`SKILL.md`](https://github.com/jakubkrehel/skills/blob/main/SKILL.md) to maintain self-containment.

### Register in README.md

Update the top-level [`README.md`](https://github.com/jakubkrehel/skills/blob/main/README.md) to include your skill in the appropriate section. Insert a bullet following the existing format (lines 13-24):

```markdown
- **[better-my-skill](skills/better-my-skill/SKILL.md)** – Improves XYZ aspects of a project.

```

This ensures users can discover your skill when browsing the repository.

### Version Bump in plugin.json

Increment the plugin version in [`.claude-plugin/plugin.json`](https://github.com/jakubkrehel/skills/blob/main/.claude-plugin/plugin.json) to trigger distribution updates:

```json
{
  "name": "interfaces",
  "version": "1.0.1",
  "description": "Collection of UI-focused skills"
}

```

Changing the version is essential because Claude Code only pulls plugin updates when the version number changes.

### Validate the Plugin

Run the validation commands to check front-matter, YAML syntax, and version formatting:

```bash
claude plugin validate .
claude plugin validate .claude-plugin/plugin.json

```

Both commands should report "valid". Fix any errors before committing.

## Understanding the File Structure

A complete skill follows this directory layout:

```text
skills/
└─ better-my-skill/
   ├─ SKILL.md
   ├─ agents/
   │   └─ openai.yaml
   └─ additional-doc.md   # optional

```

This structure keeps the skill **self-contained** and discoverable by the Opencode loader referenced in [`opencode.json`](https://github.com/jakubkrehel/skills/blob/main/opencode.json).

## Summary

- **Create** a kebab-case directory under `skills/` that matches the name in your front-matter and agent configuration.
- **Write** a [`SKILL.md`](https://github.com/jakubkrehel/skills/blob/main/SKILL.md) with proper YAML front-matter and follow the style guide in [`AGENTS.md`](https://github.com/jakubkrehel/skills/blob/main/AGENTS.md) for prose formatting.
- **Configure** the [`agents/openai.yaml`](https://github.com/jakubkrehel/skills/blob/main/agents/openai.yaml) file to set the model type and invocation policy, matching patterns from existing skills like `variant`.
- **Update** the top-level [`README.md`](https://github.com/jakubkrehel/skills/blob/main/README.md) with a properly formatted bullet link to your skill.
- **Increment** the version field in [`.claude-plugin/plugin.json`](https://github.com/jakubkrehel/skills/blob/main/.claude-plugin/plugin.json) to enable distribution to users.
- **Validate** your changes using `claude plugin validate` commands before submitting a pull request.

## Frequently Asked Questions

### What naming convention should I use for new skills?

Use **kebab-case** (lowercase words separated by hyphens) for all skill names. The identifier must be identical in three places: the directory name (`skills/my-skill/`), the front-matter `name` field in [`SKILL.md`](https://github.com/jakubkrehel/skills/blob/main/SKILL.md), and the `display_name` in [`agents/openai.yaml`](https://github.com/jakubkrehel/skills/blob/main/agents/openai.yaml). Mismatches prevent the harness from locating the skill.

### Why do I need to bump the version in plugin.json?

The Claude Code plugin system only pulls updates when the version number changes, as implemented in `jakubkrehel/skills`. Incrementing the `version` field in [`.claude-plugin/plugin.json`](https://github.com/jakubkrehel/skills/blob/main/.claude-plugin/plugin.json) signals to the plugin manager that new content is available, ensuring users receive your skill when they update.

### How do I validate my skill before submitting a PR?

Run the built-in validation commands: `claude plugin validate .` and `claude plugin validate .claude-plugin/plugin.json`. These cheap checks catch malformed front-matter, invalid YAML syntax, and version mismatches. Both commands must return "valid" before you commit and open a pull request targeting the `main` branch.

### Can I include multiple documentation files in a single skill?

Yes. You can add supplementary `.md` files alongside [`SKILL.md`](https://github.com/jakubkrehel/skills/blob/main/SKILL.md) for recipes, lookup tables, or detailed examples. Keep all files within the skill directory and link them from the main [`SKILL.md`](https://github.com/jakubkrehel/skills/blob/main/SKILL.md) to maintain the self-contained structure required by the repository conventions.