Package your skills and hooks as a plugin

The steps

One step at a time. When a step’s check matches, tick it and the next one opens.

1. 01

   Step 1 of 5: Lay out the plugin folder

   A manifest in .claude-plugin/, and each component in its own folder beside it.

   plugins/acme-kit/

   • folder .claude-plugin
     • plugin.jsonNewthe manifest
   • folder skills
     • folder client-updatecopied from .claude/skills/
       • SKILL.md
       • example.md
   • folder hooks
     • hooks.jsonNew
   • folder scripts
     • protect-files.mjscopied from .claude/hooks/

   The kit has these files. In your own project, ask Claude:Copy

   Copy .claude/skills/client-update into plugins/acme-kit/skills/, and .claude/hooks/protect-files.mjs into plugins/acme-kit/scripts/. Copy only: don’t change or delete the originals.

   Check it worked

   plugins/acme-kit/ holds skills/client-update/SKILL.md and scripts/protect-files.mjs.

   It worked — next step Not yet
2. 02

   Step 2 of 5: Write the manifest

   plugin.json names the plugin, and the name becomes the prefix on its skills.

   plugins/acme-kit/.claude-plugin/plugin.json · JSONCopy

   {
     "name": "acme-kit",
     "description": "The client-update skill and a hook that blocks edits to .env files and test/, packaged to install in any project",
     "version": "1.0.0",
     "author": {
       "name": "HorizonLux Claude Code Challenge"
     }
   }
   

   .claude-plugin/plugin.json

   name: acme-kit

   Required, no spaces. Skills become /acme-kit:<skill>

   description: "The client-update skill…"

   What people see in /plugin

   version: 1.0.0

   Installs stay on this version until you change it

   author.name: "HorizonLux…"

   Who to credit

   Check it worked

   .claude-plugin/ holds plugin.json and nothing else.

   It worked — next step Not yet Back
3. 03

   Step 3 of 5: Move the guard hook

   Copy the hook entry into hooks/hooks.json and point it at the plugin’s own script.

   plugins/acme-kit/hooks/hooks.json · JSONCopy

   {
     "hooks": {
       "PreToolUse": [
         {
           "matcher": "Edit|Write",
           "hooks": [
             {
               "type": "command",
               "command": "node",
               "args": ["${CLAUDE_PLUGIN_ROOT}/scripts/protect-files.mjs"]
             }
           ]
         }
       ]
     }
   }
   

   Changes to hooks/hooks.jsonBefore → after

   Unchanged: "matcher": "Edit|Write",

   Unchanged: "command": "node",

   −Removed: "args": ["${CLAUDE_PROJECT_DIR}/.claude/hooks/protect-files.mjs"]

   +Added: "args": ["${CLAUDE_PLUGIN_ROOT}/scripts/protect-files.mjs"]

   ${CLAUDE_PLUGIN_ROOT} is wherever the plugin is installed, so the path works in any project. The Stop hook stays in the project: it runs npm test, which other projects may not have.

   Check it worked

   hooks.json has one PreToolUse entry, matching Edit|Write.

   It worked — next step Not yet Back
4. 04

   Step 4 of 5: Validate and load it

   Check the plugin, then start a session with it loaded for that session only.

   TerminalCopy

   Run: $ claude plugin validate ./plugins/acme-kit

   – What happens: It names the manifest it checked, then prints:

   Output: ✔ Validation passed

   Run: $ claude --plugin-dir ./plugins/acme-kit

   – What happens: Loads the plugin for this session. Nothing is installed.

   Check it worked

   The validator’s last line is ✔ Validation passed, and Claude Code starts.

   If it didn’t work

   It prints ✘ Validation failed

   Each line above the result names the field to fix. Fix it and run the command again.

   It worked — next step Not yet Back
5. 05

   Step 5 of 5: Prove both parts work

   Run the prefixed skill, and find the plugin’s hook in /hooks.

   In Claude Code

   You type: › /acme-kit:client-update

   – What happens: Claude writes the client update, as /client-update did.

   You type: › /hooks

   – What happens: One PreToolUse hook comes from project settings, one from the plugin.

   In your own project, delete the originals from .claude/ once the plugin works. In the practice project, keep them.

   Check it worked

   The skill runs, and /hooks lists a PreToolUse hook labelled with the plugin.

   If it didn’t work

   The skill is unknown

   Run /reload-plugins after editing plugin files. The Errors tab in /plugin says what failed to load.

   It worked — finish Not yet Back