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

To add a new skill to the jakubkrehel/skills repository, create a kebab-case directory under skills/, add a SKILL.md file with front-matter, configure an agents/openai.yaml file, update the top-level README.md, increment the version in .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. 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 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, and the display_name in 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, 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:

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

---
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: use sentence-case headings, avoid serial commas, and keep sentences under 30 words.

Configure the Agent

Add an agents/openai.yaml file to declare the agent type and invocation policy. Create the directory structure and file:

mkdir skills/better-my-skill/agents

Then add the configuration:

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 for recipes, lookup tables, or extended examples. Keep these files within the skill directory and link them from the main SKILL.md to maintain self-containment.

Register in README.md

Update the top-level README.md to include your skill in the appropriate section. Insert a bullet following the existing format (lines 13-24):

- **[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 to trigger distribution updates:

{
  "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:

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:

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.

Summary

• Create a kebab-case directory under skills/ that matches the name in your front-matter and agent configuration.
• Write a SKILL.md with proper YAML front-matter and follow the style guide in AGENTS.md for prose formatting.
• Configure the 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 with a properly formatted bullet link to your skill.
• Increment the version field in .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, and the display_name in 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 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 for recipes, lookup tables, or detailed examples. Keep all files within the skill directory and link them from the main SKILL.md to maintain the self-contained structure required by the repository conventions.

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