# How Skill Names Are Synchronized Across Different Files in jakubkrehel/skills

> Learn how skill names synchronize across jakubkrehel/skills files. Discover the manual process ensuring consistent discovery and invocation by the Claude-Code plugin.

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

---

**Skill names must be manually synchronized across three specific locations—the directory name, the front-matter `name` field in [`SKILL.md`](https://github.com/jakubkrehel/skills/blob/main/SKILL.md), and the `display_name` key in [`agents/openai.yaml`](https://github.com/jakubkrehel/skills/blob/main/agents/openai.yaml)—to ensure consistent discovery and invocation by the Claude-Code plugin.**

In the **jakubkrehel/skills** repository, each skill requires identical identifiers in three distinct locations to function correctly within the CLI and Claude-Code ecosystem. Unlike repositories with automated configuration management, this project relies on a documented manual convention to keep skill names synchronized across different files. Understanding this synchronization pattern is essential for developers creating new skills or renaming existing ones.

## The Three Required Locations for Skill Names

Every skill in the repository must declare its identifier in exactly three places. These **textual literals** are not automatically linked, so developers must ensure they match manually.

### Directory Name

The folder containing the skill serves as the canonical identifier used by the file system and CLI tools. For example, the *better-ui* skill resides in `skills/better-ui/`. The directory name acts as the base reference for all other name declarations.

### Front-Matter in SKILL.md

Each skill's entry-point file [`SKILL.md`](https://github.com/jakubkrehel/skills/blob/main/SKILL.md) contains a YAML front-matter block with a `name` field that must exactly match the directory name. As documented in [`AGENTS.md`](https://github.com/jakubkrehel/skills/blob/main/AGENTS.md) at line 86, this field establishes the skill's internal identity:

```yaml
---
name: better-ui
description: Polishes and improves the UI in your project. Covers concentric border radius, optical alignment, surface depth, contextual icons, hit areas and more.
---

```

The value following `name:` must be identical to the parent directory name to prevent routing errors.

### agents/openai.yaml Configuration

Inside `skills/<skill>/agents/openai.yaml`, the `display_name` key provides the human-readable title presented to users. While typically title-cased, this should correspond to the same identifier used in the directory and front-matter:

```yaml
---
display_name: "Better UI"
disable_model_invocation: false
policy:
  allow_implicit_invocation: false
---

```

This file enables the Claude-Code harness to present the skill correctly in user interfaces.

## Manual Synchronization Workflow

The repository provides no automated synchronization tool. According to the source code documentation, developers must follow this four-step process when creating or renaming a skill:

1. **Create or rename the directory** to match your desired identifier (e.g., `skills/my-skill/`).

2. **Edit [`SKILL.md`](https://github.com/jakubkrehel/skills/blob/main/SKILL.md)** and set the front-matter `name:` field to the exact directory name (e.g., `name: my-skill`).

3. **Edit [`agents/openai.yaml`](https://github.com/jakubkrehel/skills/blob/main/agents/openai.yaml)** and set `display_name:` to a human-readable version of the same identifier (e.g., `display_name: "My Skill"`).

4. **Run a repository-wide search** using `grep -R "old-name"` to verify no stale references remain.

This manual workflow ensures that the skill can be discovered by the CLI (`skills add ...`), invoked by the Claude-Code plugin (via `display_name`), and referenced internally through consistent file paths.

## Detecting Mismatches with Verification Scripts

To identify synchronization errors across the codebase, use this shell script that compares directory names against their corresponding [`SKILL.md`](https://github.com/jakubkrehel/skills/blob/main/SKILL.md) front-matter:

```bash
#!/usr/bin/env bash

# Find any skill where the front-matter name differs from its directory name

while IFS= read -r -d '' skill_dir; do
  front_name=$(grep -m1 '^name:' "$skill_dir/SKILL.md" | cut -d' ' -f2)
  dir_name=$(basename "$skill_dir")
  if [[ "$front_name" != "$dir_name" ]]; then
    echo "Mismatch in $skill_dir: front-matter name='$front_name' vs directory='$dir_name'"
  fi
done < <(find . -type d -path "./skills/*")

```

Running this verification script will print any skill whose directory name and [`SKILL.md`](https://github.com/jakubkrehel/skills/blob/main/SKILL.md) name field are out of sync, preventing runtime discovery failures.

## Why This Convention Matters

The three-location naming convention serves distinct technical purposes within the jakubkrehel/skills architecture. The **directory name** enables file system operations and CLI commands. The **front-matter `name`** provides a machine-readable identifier for internal routing. The **display_name** in [`agents/openai.yaml`](https://github.com/jakubkrehel/skills/blob/main/agents/openai.yaml) supplies the presentation layer for user interfaces.

Keeping these synchronized guarantees that the Claude-Code plugin can correctly discover, display, and invoke skills without configuration drift or reference errors.

## Summary

- **Skill names** in jakubkrehel/skills must match across exactly three locations: the directory name, [`SKILL.md`](https://github.com/jakubkrehel/skills/blob/main/SKILL.md) front-matter, and [`agents/openai.yaml`](https://github.com/jakubkrehel/skills/blob/main/agents/openai.yaml).
- **No automated tool** exists for synchronization; developers must manually update all three locations when renaming skills.
- **AGENTS.md** documents this convention at line 86, recommending `grep` verification to catch stale references.
- **Verification scripts** can detect mismatches between directory names and front-matter declarations before they cause runtime issues.
- The `display_name` field supports human-readable presentation while the directory and front-matter names handle machine identification.

## Frequently Asked Questions

### What files contain skill names in jakubkrehel/skills?

Skill names appear in three specific files: the directory name itself (e.g., `skills/better-ui/`), the `name` field in [`SKILL.md`](https://github.com/jakubkrehel/skills/blob/main/SKILL.md) front-matter, and the `display_name` key in [`agents/openai.yaml`](https://github.com/jakubkrehel/skills/blob/main/agents/openai.yaml). Each serves a different purpose in the discovery and presentation pipeline.

### Is there an automated tool to sync skill names?

No, the repository does not provide an automated synchronization tool. Developers must manually ensure all three locations match when creating or renaming a skill, followed by a repository-wide `grep` search to confirm no stale references remain.

### How do I verify skill names are synchronized?

Use the provided bash script to compare directory names against their [`SKILL.md`](https://github.com/jakubkrehel/skills/blob/main/SKILL.md) front-matter `name` fields. Additionally, run `grep -R "old-skill-name"` across the repository to catch any lingering references in documentation or configuration files.

### What happens if skill names are out of sync?

Mismatched skill names can cause CLI discovery failures, prevent the Claude-Code plugin from invoking the correct skill, or result in broken references within the codebase. The skill may appear unavailable or fail to load correctly when `display_name` does not correspond to the actual directory structure.