# How to Add a New Skill for Claude Code Users: Updating plugin.json

> Learn how to add a new skill for Claude Code users. Update your plugin.json file by appending a new skill entry and incrementing the version to ensure discovery.

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

---

**To add a new skill for Claude Code users, you must append a new entry to the `skills` array in [`.claude-plugin/plugin.json`](https://github.com/jakubkrehel/skills/blob/main/.claude-plugin/plugin.json) with the required metadata fields and increment the top-level `version` property to trigger discovery.**

The `jakubkrehel/skills` repository uses a manifest-based architecture where [`.claude-plugin/plugin.json`](https://github.com/jakubkrehel/skills/blob/main/.claude-plugin/plugin.json) serves as the single source of truth for skill availability. When adding a new skill for Claude Code users, this JSON configuration file tells the Claude Code client which skills exist, where to find them, and how to display them in the skill picker interface.

## Update the Skills Array in plugin.json

Every skill registered in the repository requires a corresponding entry in the `skills` array located in [`.claude-plugin/plugin.json`](https://github.com/jakubkrehel/skills/blob/main/.claude-plugin/plugin.json). Claude Code scans this array at runtime to populate the available skill catalog.

### Required Fields for New Skill Entries

Each object in the `skills` array must contain four specific fields:

- **`name`** – Must exactly match the skill's directory name (e.g., `"better-animation"`).
- **`display_name`** – Human-readable title displayed in the Claude Code UI (e.g., `"Better Animation"`).
- **`description`** – Concise one-sentence summary shown in the skill picker.
- **`path`** – Relative path to the skill folder, typically formatted as `"skills/<skill-name>"`.

Here is a complete example entry for a skill named `better-animation`:

```json
{
  "name": "better-animation",
  "display_name": "Better Animation",
  "description": "Guidance for creating accessible, performant animations.",
  "path": "skills/better-animation"
}

```

## Increment the Plugin Version

Claude Code uses semantic versioning to determine whether a plugin update is required. Every time you add a new skill for Claude Code users, you must bump the top-level `version` field in [`.claude-plugin/plugin.json`](https://github.com/jakubkrehel/skills/blob/main/.claude-plugin/plugin.json).

```json
"version": "1.4.0",

```

Failure to increment this version prevents Claude Code from recognizing the new skill during synchronization, even if the `skills` array contains the correct entry.

## Optional Category and Type Metadata

Some plugin configurations in the `jakubkrehel/skills` repository classify skills using additional fields. If your repository structure utilizes `type` or `category` properties, include the appropriate classification values when adding the new skill entry. These fields help organize skills in the marketplace view but are not strictly required for basic functionality.

## Sync with marketplace.json

The repository maintains a second manifest file, [`.claude-plugin/marketplace.json`](https://github.com/jakubkrehel/skills/blob/main/.claude-plugin/marketplace.json), which handles marketplace-specific metadata. When adding a new skill for Claude Code users, ensure the `version` field in [`marketplace.json`](https://github.com/jakubkrehel/skills/blob/main/marketplace.json) matches the version in [`plugin.json`](https://github.com/jakubkrehel/skills/blob/main/plugin.json) exactly. Both manifests must stay in sync to prevent deployment errors.

### Complete Configuration Example

The following diff demonstrates the exact changes required when adding the `better-animation` skill to an existing plugin configuration:

```diff
{
  "name": "interfaces",
- "version": "1.3.0",
+ "version": "1.4.0",
  "description": "Collection of UI-focused Claude Code skills",
  "skills": [
    {
      "name": "existing-skill",
      "display_name": "Existing Skill",
      "description": "Previously available functionality.",
      "path": "skills/existing-skill"
-   }
+   },
+   {
+     "name": "better-animation",
+     "display_name": "Better Animation",
+     "description": "Guidance for creating accessible, performant animations.",
+     "path": "skills/better-animation"
+   }
  ]
}

```

## Summary

- **Modify [`.claude-plugin/plugin.json`](https://github.com/jakubkrehel/skills/blob/main/.claude-plugin/plugin.json)** to append the new skill object containing `name`, `display_name`, `description`, and `path` fields.
- **Increment the `version`** property in [`plugin.json`](https://github.com/jakubkrehel/skills/blob/main/plugin.json) to trigger Claude Code's update detection mechanism.
- **Synchronize [`marketplace.json`](https://github.com/jakubkrehel/skills/blob/main/marketplace.json)** to ensure the version field matches across both manifest files.
- **Verify the skill directory** contains a [`SKILL.md`](https://github.com/jakubkrehel/skills/blob/main/SKILL.md) file at the specified path before committing.

## Frequently Asked Questions

### What happens if I forget to increment the version in plugin.json?

Claude Code will not detect the new skill during the next synchronization cycle. The client compares the current version string against the cached version; if they match, the skill catalog remains unchanged regardless of modifications to the `skills` array.

### Does the skill path need to match the directory structure exactly?

Yes. The `path` field must resolve to the actual directory containing the skill's [`SKILL.md`](https://github.com/jakubkrehel/skills/blob/main/SKILL.md) file. According to the `jakubkrehel/skills` source code, this typically follows the convention `"skills/<skill-name>"` where `<skill-name>` matches the `name` field exactly.

### Is marketplace.json always required when adding a new skill?

While [`plugin.json`](https://github.com/jakubkrehel/skills/blob/main/plugin.json) is mandatory for Claude Code to load the skill, [`marketplace.json`](https://github.com/jakubkrehel/skills/blob/main/marketplace.json) is required if the repository is distributed through the Claude Code marketplace. Both files must maintain identical version strings to prevent deployment conflicts.