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

To add a new skill for Claude Code users, you must append a new entry to the skills array in .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 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. 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:

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

"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, which handles marketplace-specific metadata. When adding a new skill for Claude Code users, ensure the version field in marketplace.json matches the version in 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:

{
  "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 to append the new skill object containing name, display_name, description, and path fields.
• Increment the version property in plugin.json to trigger Claude Code's update detection mechanism.
• Synchronize marketplace.json to ensure the version field matches across both manifest files.
• Verify the skill directory contains a 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 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 is mandatory for Claude Code to load the skill, 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.

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