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

Skill names must be manually synchronized across three specific locations—the directory name, the front-matter name field in SKILL.md, and the display_name key in 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 contains a YAML front-matter block with a name field that must exactly match the directory name. As documented in AGENTS.md at line 86, this field establishes the skill's internal identity:

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

---
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 and set the front-matter name: field to the exact directory name (e.g., name: my-skill).

3. Edit 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 front-matter:

#!/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 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 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 front-matter, and 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 front-matter, and the display_name key in 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 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.

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