Articles/Claude Code

⟐ Claude Code/2026-09-10Intermediate

One plugin.json turns a shelf of skills into something you can switch off as a group

When I sorted my skills by what work they belong to, the set I open almost daily turned out to be 5 percent of the total. Here is how I dropped a .claude-plugin/plugin.json into each group so I could switch a whole shelf off, plus the two loading rules I tripped over on the way.

Claude Code²⁵⁰ Agent Skills⁴ Plugins³ Context Design Indie Development¹¹

✦ Premium Article

On a rainy afternoon I opened my skills folder and started colour-coding the directories by the work they belong to. SEO research here, frontend implementation there, site operations over on the side. Partway through the sorting I noticed that the shortest column was the one I open most days.

I wrote up the counting itself in I counted 42 skills on my shelf, so I won't repeat it here. What I want to share this time is what comes after the counting.

For a while I assumed that bundling would make things lighter. It didn't. The per-turn weight didn't drop by a single character. I'm still glad I did it — what dropped was the number of moves, not the weight.

Counting by job reveals the ratio

The counting method is the same as before: add up the characters in each description field. The difference is that this time I group before I add.

# group_skills.py — count a skills folder, grouped by the work each skill serves
import os
import re
import sys
 
BASE = sys.argv[1] if len(sys.argv) > 1 else os.path.expanduser("~/.claude/skills")
 
GROUPS = {
    "seo":       ["ai-seo", "seo-audit", "programmatic-seo", "content-research-writer"],
    "web-front": ["vercel-optimize", "vercel-react-best-practices", "webapp-testing"],
    "design":    ["frontend-design", "implement-design", "web-design-guidelines"],
    "site-ops":  ["claudelab-site", "gemilab-site"],
}
 
def description_length(folder: str) -> int:
    path = os.path.join(BASE, folder, "SKILL.md")
    if not os.path.isfile(path):
        return 0
    text = open(path, encoding="utf-8", errors="replace").read()
    front = re.search(r"^---\n(.*?)\n---", text, re.S | re.M)
    if not front:
        return 0  # no frontmatter means no description to pay for
    field = re.search(r"^description:\s*(.*?)(?=^\w+:|\Z)", front.group(1), re.S | re.M)
    if not field:
        return 0
    return len(" ".join(field.group(1).split()))
 
lengths = {d: description_length(d) for d in sorted(os.listdir(BASE))
           if os.path.isdir(os.path.join(BASE, d))}
total = sum(lengths.values()) or 1
assigned = set()
 
print(f"{'group':<12}{'n':>4}{'chars':>8}{'share':>8}")
for name, members in GROUPS.items():
    present = [m for m in members if m in lengths]
    assigned.update(present)
    chars = sum(lengths[m] for m in present)
    print(f"{name:<12}{len(present):>4}{chars:>8}{chars / total * 100:>7.1f}%")
 
rest = [k for k in lengths if k not in assigned]
rest_chars = sum(lengths[k] for k in rest)
print(f"{'(rest)':<12}{len(rest):>4}{rest_chars:>8}{rest_chars / total * 100:>7.1f}%")
print(f"total {len(lengths)} folders / {total} chars")

Both the os.path.isfile guard and the 0 return for missing frontmatter earned their place. My shelf still holds a few folders whose contents are nothing but a forwarding note, and the first version of this script raised on them.

Here is what it printed for me. The grouping follows how my own week is divided, so treat it as one example rather than a template.

Group	Skills	Description chars	Share of total
SEO research and audits	5	2,442	20.7%
Frontend implementation	6	2,370	20.1%
Design and imagery	9	2,416	20.5%
Site operations	4	623	5.3%
Development workflow	7	1,145	9.7%
Everything else	11	2,774	23.6%
Total	42	11,770	100%

That table stopped me for a minute. The site-operations set, which I open nearly every day, accounts for 5.3% of the description text. The other 94.7% describes work I am not doing today. That may well be the whole of what "the shelf keeps growing" actually feels like.

Character counts are only a yardstick for comparing your own shelf against itself. When you need real numbers, claude plugin details <name> estimates tokens through the count_tokens API for your active model.

A single `.claude-plugin/plugin.json` changes what a folder means

A skills directory can hold three different kinds of thing under the same tree.

What you have	What it loads as
`<skills-dir>/foo/SKILL.md` with no manifest	A plain skill named `foo`
`<skills-dir>/foo/.claude-plugin/plugin.json`	A plugin `foo@skills-dir`, which can bundle skills, agents, hooks and more
`<plugin>/skills/bar/SKILL.md`	A skill `bar` packaged inside a plugin

There are two places it can load from. Put it in ~/.claude/skills/ for personal scope, where it loads in every project. Put it in <cwd>/.claude/skills/ for project scope, where it loads once you have accepted the workspace trust dialog for that folder.

claude plugin init writes the scaffold for you.

# scaffold at ~/.claude/skills/site-ops/ with skills and hooks folders
claude plugin init site-ops --with skills hooks
 
# rewrite an existing scaffold
claude plugin init site-ops --force

The manifest can stay small. It is optional altogether, and name is the only required field.

{
  "name": "site-ops",
  "displayName": "Site Ops",
  "version": "0.1.0",
  "description": "Article updates and deploy chores for four sites",
  "author": { "name": "Masaki Hirokawa" },
  "skills": "./skills/",
  "hooks": "./hooks/hooks.json"
}

Moving flat folders in gives you a tree like this.

~/.claude/skills/
├── site-ops/
│   ├── .claude-plugin/
│   │   └── plugin.json
│   ├── skills/
│   │   ├── claudelab-site/SKILL.md
│   │   ├── gemilab-site/SKILL.md
│   │   ├── antigravitylab-site/SKILL.md
│   │   └── rorklab-site/SKILL.md
│   └── hooks/
│       └── hooks.json
└── seo-kit/
    ├── .claude-plugin/
    │   └── plugin.json
    └── skills/
        ├── seo-audit/SKILL.md
        └── programmatic-seo/SKILL.md

I keep the migration itself to a fixed four steps.

Note the folder names you're moving, then run claude plugin init <name> --with skills to write the scaffold
Move the original folders under <name>/skills/ as they are, leaving each SKILL.md untouched
Run claude plugin validate ~/.claude/skills/<name> to catch any file whose frontmatter no longer parses
Restart Claude Code and record the Always-on figure from claude plugin details <name>

validate in step 3 exits 0 when it passes, 1 when it fails, and 2 when the validation run itself fails, such as when the path can't be read. I keep the figure from step 4 next to the pre-migration total in a note of my own.

Don't put commands/, agents/, or skills/ inside .claude-plugin/. Only plugin.json belongs there; everything else sits one level up. I got this backwards once and built a plugin that loaded with no components at all.

✦

Thank you for reading this far.

Continue Reading

What follows includes implementation code, benchmarks, and practical content we hope you'll find useful. This site runs without ads — server and development costs are supported entirely by members like you. If it's been helpful, we'd be truly grateful for your support.

WHAT YOU'LL LEARN

✦You will be able to regroup a flat skills folder into units you can switch off together, one job at a time

✦You will be able to measure the per-turn weight of your own skill descriptions broken down by the work they serve, and decide from that

✦You will be able to avoid two quiet failures before you hit them: a plugin at the repository root that never loads, and a hook you edited that keeps running the old definition

Secure payment via Stripe · Cancel anytime

✦

Unlock This Article

Get full access to the rest of this article. Buy once, read anytime. This site is ad-free — your support goes directly toward keeping it running.

Unlock all articles with Membership →

Bundling alone doesn't reduce the per-turn weight

I recounted after regrouping and felt a small disappointment. The total was still 11,770 characters.

The reason is obvious in hindsight. What accumulates each turn is not the plugin's description but the description of every skill inside it. Four skills wrapped in one plugin still contribute four description lines. claude plugin details labels this "Always-on" and says plainly that you pay it in every session, whether or not any component fires.

What bundling reduces is moves, not weight. Forty-two flat folders means touching forty-two folders when you want them gone. Bundled, a whole group goes down under one name.

# drop the sets you won't use today
claude plugin disable seo-kit@skills-dir
claude plugin disable design-kit@skills-dir
 
# put one back
claude plugin enable seo-kit@skills-dir
 
# check what is currently loaded
claude plugin list
claude plugin details site-ops

Unlike a marketplace install, there is no uninstall step, because nothing was installed. You either delete the folder or disable it by name.

Back to the table: on a day when I drop the SEO set, 2,442 characters of description leave the per-turn pile. Drop the design set too and another 2,416 goes — 41.2% of the total between them. My writing days and my implementation days are cleanly separated, so this switch lands well for me.

What takes effect immediately, and what needs a reload

The day after regrouping I spent ten minutes wondering why an edited hook did nothing. The fault was my assumption. I was sure the hook itself was written wrong, and I may still be missing something, but what I had actually misread was which half of the tree reloads live.

Edits to a SKILL.md take effect in the session you already have open. Edits to hooks/, .mcp.json, agents/, and output-styles/ do not. The old definition keeps running until you run /reload-plugins or restart Claude Code.

What you edited	Effect on the open session
`skills/*/SKILL.md`	Applies immediately
`hooks/hooks.json`	Needs `/reload-plugins` or a restart
`.mcp.json`	Same
`agents/*.md`	Same
`output-styles/*.md`	Same

Back when I only had flat skills, edit-and-it-works was simply how things were. Introduce plugins as a unit and that expectation carries over for exactly half the tree. When an edit doesn't take, my first check is whether the file I touched was a skill.

A plugin at the repository root won't load from a subdirectory

The second stumble was the more awkward one.

Project-scope skills and commands are found by walking up the directory tree. A @skills-dir plugin is not. It loads only from the .claude/skills/ of the session's primary working directory.

So a plugin sitting at your repository root simply isn't there when you start claude from, say, packages/web/. Nothing errors. It just quietly isn't there.

# loads
cd ~/work/my-repo && claude
 
# does not load — the root .claude/skills/ is never walked up to
cd ~/work/my-repo/packages/web && claude

Two ways around it: start from the repository root, or move the session's working directory with /cd from inside the session, which is available on v2.1.246 and later.

Project scope carries one more layer of restriction. Because the content comes from the repository rather than from you, it passes the same trust gate that governs project allow rules in .claude/settings.json — trusting a parent folder isn't enough, and neither is running with -p. MCP servers it declares go through per-server approval, and background monitors don't load at all. Personal scope has none of these restrictions, so anything I use only by myself lives in ~/.claude/skills/.

Resist the urge to share files with `../`

Once you split into groups, you will want two plugins to share a helper file. Letting that idea go early saved me time.

Claude Code rejects any component path that resolves outside the plugin root. A written path like ../shared-utils is rejected, and so is a symlink that leads outside. When it rejects one, you get a path escapes plugin directory error and the plugin loads without that component. The plugin doesn't fall over, which makes this an easy failure to miss.

On macOS and Linux there is one more rule. A component path containing a backslash anywhere is rejected even when it stays inside the plugin, so such components load on Windows only. Write component paths with forward slashes, like ./commands/deploy.md.

I ended up duplicating small helpers into each plugin rather than hoisting them outside. Duplication isn't pleasant, but I find it easier to live with than a component that goes missing without saying so.

Pick one group off the shelf you already have

Trying to reorganise everything at once will probably stall. Mine did.

What I'd suggest for tomorrow is this: pick the group you use least and drop a single plugin.json into that one. For me it was the nine design skills. I knew I never call them on a writing day, so the choice made itself.

Once it's in place, read its Always-on figure with claude plugin details, then spend a week with it off and a week with it on. I think you'll notice the drop in commands you type before you notice the numbers. Keep adding to the shelf if you need to — just add in units you can take down together.

Thank you for reading this far. If your own shelf has quietly grown past what you can hold in your head, I hope some of this helps.

Thank You for Reading

Claude Lab is ad-free, supported entirely by members like you. We publish practical guides daily with implementation code, benchmarks, and production-ready patterns. If you've found it useful, we'd love to have you on board.