Why Your Skills Folder Is a Mess (and Why It Matters)

If you've been using Claude Code for more than a month, your skills folder probably looks like an archaeological dig: a helper skill of unclear purpose, a 900-line SKILL.md nobody wants to touch, and a few third-party skills you grabbed from GitHub without a second glance. You're not alone — but this mess has real consequences.

The first consequence is your folder structure determines your command names. Claude Code derives the /command for each skill from the directory name, not the frontmatter — so .claude/skills/deploy-staging/SKILL.md creates /deploy-staging, while the name field only sets the display label. Vague folder names like utils or helper don't just look sloppy; they produce vague commands and, per Anthropic's own best practices, violate the naming rules that keep skills discoverable (lowercase, hyphens, gerund form like processing-pdfs).

The second consequence is scope. Skills load from six different locations — enterprise, personal, project, nested subdirectories, additional directories, and plugins — each with different visibility and an override hierarchy. Drop a skill in the wrong spot and it either leaks into every project on your machine or stays invisible to the teammates who need it. Project skills belong in a git-committed .claude/skills/; personal ones in ~/.claude/skills/. Organization isn't cosmetic — it's how you control who sees what.

The third consequence is the one most developers ignore: unvetted third-party code sitting in your skills folder. A Snyk audit of 3,984 published skills found that 13.4% contained at least one critical security issue, 36.82% had at least one flaw of any severity, and 10.9% contained hardcoded secrets. Skills inherit the full permissions of your agent — shell access, filesystem, credentials — and publishing one requires nothing more than a SKILL.md file and a week-old GitHub account. Meanwhile, daily skill submissions jumped from under 50 to over 500 in a matter of weeks, a 10x flood that makes manual vetting nearly impossible.

Anthropic's own guidance is blunt: install skills only from trusted sources and audit their files, dependencies, and bundled resources. In practice, that means your folder organization should track provenance:

• Where did this skill come from, and who maintains it?
• Is the version pinned, or can upstream changes silently alter behavior?
• Does it bundle scripts, and if so, what do they actually do?
• Is it a trusted internal skill or an untrusted third-party one?

This is the gap SkillzBench is being built to close — an independent testing lab for agent skills that pins versions to commit SHAs, security-scans and quality-judges every skill, and benchmarks each one in a sandbox so you can see its Lift in percentage points before it ever touches your agent. The waitlist is live now, and the thesis is simple: skills, proven.

A messy folder costs you vague commands, wrong loading scope, and unexamined risk. The fix starts with treating your skills folder as infrastructure — named deliberately, scoped intentionally, and vetted before anything loads.

Join the SkillzBench waitlist to follow the testing and verification work as it ships — no ratings theater, just security, quality, and benchmarked Lift shown separately.

Location Is Scope: The Six Places Skills Can Live

Where a skill folder lives isn't a storage detail — it's the decision that determines who can load it, when it loads, and what command invokes it. Get the location wrong and even a beautifully written SKILL.md becomes invisible to the agent that needs it.

According to Anthropic's official documentation, skills load from six places, each defining a scope: enterprise (managed settings for org-wide deployment), personal (~/.claude/skills/, available in all your projects), project (.claude/skills/, committed to git for team sharing), nested subdirectories, --add-dir session directories, and plugins. When conflicts arise, the override hierarchy decides which skill wins — so an enterprise policy can enforce standards across every machine it manages.

The six locations map cleanly to use cases:

• Personal (`~/.claude/skills/`) — your private toolkit, loaded everywhere on that machine.
• Project (`.claude/skills/`) — committed to git so the whole team shares identical skills.
• Enterprise/managed — organization-wide skills pushed via managed settings.
• Nested subdirectories — loaded on demand when Claude touches files in that directory.
• Plugins and --add-dir — namespaced distribution (`plugin-name:skill-name`) and per-session directories.

Three gotchas trip up most newcomers. First, the directory name becomes the /command — .claude/skills/deploy-staging/SKILL.md gives you /deploy-staging, and the frontmatter name field only sets the display label, per this independent technical guide. Second, project skills load from the startup directory and every parent up to the repo root, which makes monorepos work without extra configuration — a skill defined at root serves every package beneath it.

Third, the legacy .claude/commands/ system has merged into skills. Both .claude/commands/deploy.md and .claude/skills/deploy/SKILL.md create /deploy, and on collision the skill wins. Anthropic recommends skills for all new work, so if you're still maintaining command files, migrating them is a straightforward organizational win.

Scope decisions also carry a security dimension. Skills inherit full agent permissions — shell, filesystem, credentials — and Snyk's audit of 3,984 skills found 13.4% contained at least one critical security flaw. Location determines blast radius: a skill in your personal folder runs in every project, while a project skill runs only where the repo travels. That's why SkillzBench is building per-agent loadouts — so an agent only sees the vetted skills chosen for it, rather than everything the folder contains.

Progressive Disclosure: Structuring Each Skill for On-Demand Loading

A skill's value depends less on what's inside it than on when it gets loaded. Claude's progressive disclosure model means only the skill's name and description occupy context at startup — roughly a handful of tokens per skill — while the full body and supporting files stay out of the context window until they're actually relevant. Anthropic compares this to a well-organized manual: table of contents first, chapters on demand, detailed appendix only when needed, which makes bundled reference material effectively unbounded in size without costing context.

Structuring your folders around this three-level model is what separates lean skills from context-hogs. At rest, a skill costs almost nothing; the body loads only on relevance or invocation, and supporting files load only when referenced. The practical targets are specific:

• Keep SKILL.md under 500 lines and roughly 2–5KB — the body is an overview, not an encyclopedia
• Put long material in sibling directories: references/ for documentation, scripts/ for executable helpers
• Keep reference files one level deep from SKILL.md, and add a table of contents to any reference past 100 lines so Claude can navigate it
• Split domain-specific content into separate files (e.g., reference/finance.md, reference/sales.md) so Claude loads only the relevant slice
• Use ${CLAUDE_SKILL_DIR} for script paths so the skill stays portable across machines and agents

A concrete example from community deep-dives: a plantuml/ skill folder containing skill.md, a scripts/render.sh, and a references/syntax-guide.md keeps the main file tight while leveraging external tools and documentation without bloating it, per a Claude Code skills deep-dive. That layout follows a broader "5KB Rule": 2–5KB is the ideal skill size, and hitting 5KB is your signal to restructure.

Names and descriptions are the discovery layer — the trigger Claude uses to pick among potentially 100+ available skills. Use gerund-form, hyphenated lowercase names like processing-pdfs or testing-code, and avoid vague ones like helper or utils. Write descriptions that state both what the skill does and when to use it; almost every "my skill isn't working" complaint turns out to be a description problem, not a content problem.

This layered structure also matters for vetting. A Snyk audit of 3,984 published skills found 13.4% contained at least one critical security issue — and bundled scripts inherit full agent permissions. Keeping SKILL.md as instruction-only and isolating scripts in their own directory makes each skill easier to audit line by line. That auditability is exactly what SkillzBench is building into its verification pillar: pinning every skill version to a commit SHA, security-scanning, and benchmarking each skill's Lift so you know which packages actually help before they touch your agents.

Skills, proven. SkillzBench is building the independent testing lab for agent skills — join the waitlist to get vetted, benchmarked skills the moment launch opens.

Vetting and Curating What Enters Your Folder

Every skill you install is a small act of trust. When Claude loads a skill, it inherits the agent's full permissions — shell access, filesystem, credentials, persistent memory — and publishing one requires nothing more than a SKILL.md file and a week-old GitHub account, according to Snyk's security research.

The numbers justify treating curation as a security practice. Snyk's audit of 3,984 skills found 13.4% contained at least one critical security flaw, 10.9% had hardcoded secrets, and 76 carried confirmed malicious payloads — with 91% of those also using prompt injection. As Snyk researchers put it: if you installed a skill in the past month, there's roughly a 13% chance it contains a critical flaw. Anthropic's own guidance echoes this: install skills only from trusted sources and audit their files, dependencies, and bundled resources.

Practical vetting habits for your folder include:

• Track provenance — record where each skill came from and who authored it.
• Pin versions to specific commits so upstream changes can't silently alter behavior.
• Audit bundled scripts and dependencies before trusting any third-party skill.
• Apply the facts-vs-procedures rule: always-true facts belong in CLAUDE.md; on-demand procedures belong in skills, per official documentation.

That last rule matters for folder hygiene too. If a section of CLAUDE.md has grown into a procedure rather than a fact, it should become a skill; if a skill is just a fact Claude should always know, it's cluttering your skills folder.

The harder problem is that the ecosystem lacks a curation layer. Skills now resemble early package managers before security became a first-class concern — daily submissions jumped from under 50 to over 500 in a matter of weeks — yet there's no equivalent of verified registries or benchmarked quality signals. SkillzBench is building exactly that: verification that pins every skill version to a commit SHA with security scanning and license checks, sandboxed benchmarking that measures each skill's Lift, trust scores from security, quality, license, maintenance, and community signals, and per-agent loadouts so each agent only sees the vetted skills you've chosen for it.

Until that layer exists, the burden is yours. Vet before you copy, pin what you trust, and keep your folder as deliberately small as it can be.

Skills, proven. SkillzBench is building the verification, benchmarking, and per-agent loadout layer the skills ecosystem is missing. Join the waitlist at skillzbench.com to get early access.

A Practical Cleanup Checklist for Your Skills Folder

A tidy skills folder isn't cosmetic — it directly determines whether Claude finds the right skill at the right moment. Since only the name and description load at startup, and Claude may be choosing among 100+ skills, your folder's organization is your agent's discovery layer.

Step 1: Audit and migrate legacy commands. Custom commands have merged into skills, and when .claude/commands/deploy.md collides with .claude/skills/deploy/SKILL.md, the skill wins — official documentation recommends skills for all new work. Move each legacy command into its own skill folder, remembering that the directory name becomes the slash command, not the frontmatter.

Step 2: Split oversized skills. If a SKILL.md is juggling multiple use cases — say, one skill handling both invoice parsing and report generation — split it into single-responsibility folders. Anthropic's best-practices guidance caps SKILL.md at 500 lines, and community deep-dives suggest 2–5KB as the sweet spot, with 5KB as the restructuring threshold. Domain-specific splitting (like separate finance and sales references) lets Claude load only relevant context.

Step 3: Rewrite vague names and descriptions. Kill anything named helper or utils — use gerund-form, hyphenated lowercase names like processing-pdfs. Then rewrite descriptions to state both what the skill does and when to use it. As one independent guide puts it, almost every "my skill isn't working" problem is a description problem.

Step 4: Sort by scope. Place skills where their audience lives:

• Personal skills in `~/.claude/skills/` — available across all your projects
• Team skills in the repo's `.claude/skills/`, committed to git
• Org-wide skills in managed settings for enterprise distribution
• Distributed skills via plugins, namespaced as `plugin-name:skill-name`

Step 5: Set a review cadence for third-party skills. This is the step most teams skip, and it's the riskiest. Snyk's audit of 3,984 skills found 13.4% contained critical security flaws, and skills inherit full agent permissions — shell, filesystem, credentials. Schedule a quarterly review: pin versions, audit bundled scripts, and remove anything you can't verify.

If manual vetting sounds like a burden, SkillzBench is building the automated layer — commit-SHA pinning, security scanning, benchmarked Lift, and per-agent loadouts so each agent only sees vetted, chosen skills. Skills, proven. Join the waitlist at skillzbench.com to get early access as the platform launches.