[FEATURE] Add support for subdirectories in skills

I would also appreciate this. I actually assumed it worked this way and spent too much time testing and attempting to "debug" it. Same goes for recursive skill loading up the project directory chain.
note to @aran0ia , you can mimic a nested directory structure by having
skills/your-skill/

• skills.md
• some-sub-skill.md
• sub-skill2.md
• subfolder/
• another-subskill3.md

you do that by referencing those files explicitly in the skills.md with markdown links + instructions,
e.g. "if you're working on the event system, read [the Event subskill](/subfolder/another-subskill3.md)"
markdown links like that get auto-registered in the skill system once the parent skill.md is read in.

I ran into this as well. Very inconsistent with commands, which do support folders.

seconding this

This issue has been inactive for 30 days. If the issue is still occurring, please comment to let us know. Otherwise, this issue will be automatically closed in 30 days for housekeeping purposes.

still an issue afaik and would still like solution

Yes please - definitely need subfolder support!

+1. Especially with command/skills merge. Thanks !

Please support it, the flat skills is hard to maintain

This is confirmed to be a bug https://github.com/agentskills/agentskills/issues/59#issuecomment-3731961421

They tried to fix https://github.com/anthropics/claude-code/blob/7d22b6e16755a75ca729079f64197dab31f666ab/CHANGELOG.md?plain=1#L26

But it doesn't seem to work still

+1. Would really help with maintenance

@ashwin-ant please help us here, we have broken few workstations and rolling things back is painful enough by now.

+1 > I guess it should be like traversing a wiki or docs

This is still an issue that makes managing skills difficult

When this issue is finally resolved, it would be great if #14836 was considered at the same time.
Meaning in the original example, the "custom-skills" sub-directory should also work if it is a symlink.

This would be extremely convenient for larger monorepos or modular repos, where dedicated sub-teams may want to maintain separate skill folders while all contributing to the global skill space.
This intention was also mentioned in the duplicate to this issue: #18192

Has there been any word on this? It's been an issue that commands and such support subfolders while skills don't. It's been very difficult to namespace our skills in the way we would like.

yes its really crazy that it s still not available

any update on that? i have over 35 skills that have to use prefix in catalogs name to keep them organized. Why won't just reuse agents / commands catalog code / module for skills grouping?

Any update? We really need this to be fixed. Please.

This issue is here 4 months, is liked by 96 people and still has no official reaction, could you raise its importance please or put here any statement on this? Support of subdirectories for skills is VERY NECESSARY when number of skills is large. @klazuka, @ItsBarryZ

Ohh yes this would be great, without sub-folders this is getting very messy :-)
But specially to keep the behavior aligned with the commands

Wow. I actually thought that it just works like that out of the box. (Similar to scaffolded CLAUDE.md files in subdirectories). I am glad i found this open issue.

Google hallucinated to tell me YES, but the cited post was talking about nested CLAUDE.md.

While native subdirectory support isn't there yet, one thing that helps in the meantime is having visibility into what skills you have across all scopes (global, workspace, project) and being able to move them between scopes via drag-and-drop.

I'm building a visual dashboard for exactly this — it shows your full Claude Code setup (skills, memories, MCP servers, hooks, configs, plugins) organized by scope hierarchy. You can move items between scopes to keep things organized, delete what you don't need, and see everything in one place instead of digging through dotfiles.

We just launched a couple days ago and are actively working on solving more of these config management pain points — give us a ⭐ to follow along: https://github.com/mcpware/claude-code-organizer

This should be indeed possible. I am looking at a package that has 90+ skills. I would like to organize it into skills/package-name/skill1, skills/package-name/skill2, ... like commands. Not even sure now how to organize that, because i don't want 90+ skills in the skills root. Hmm.

That's exactly the kind of setup we're building for! With 90+ skills, scope visibility becomes a real problem — knowing what's loaded where, what's inheriting from global, and what's project-specific.

We just launched Claude Code Organizer a few days ago. Right now it covers moving skills and memories between scopes with a visual hierarchy view + drag-and-drop. Only tested on Ubuntu so far.

Coming soon: inline editing, a sidebar navigation with expandable tree view, and a cleaner UI overall — we're actively iterating on the design.

Would love your feedback if you give it a try, especially with a 90+ skill setup — that's a great stress test for us. Any bugs or feature requests, open an issue and we'll fix it within hours. We've been turning around updates same-day.

npx @mcpware/claude-code-organizer

⭐ If you find it useful, a star on the repo helps a lot — and follow @mcpware to get notified when we ship updates.

Is it possible to create a master script to process our internal skill folder structure based on how we’ve organized it? Specifically, is it possible to first reference a master index (placed at the top-level folder) before performing any searches within the folder hierarchy?

A UserPromptSubmit hook can load skills from subdirectories:

MARKER="/tmp/cc-skills-loaded-$$"
[ -f "$MARKER" ] && exit 0
touch "$MARKER"
SKILLS_DIRS=('.claude/skills' '$HOME/.claude/skills')
CONTEXT=""
for base in "${SKILLS_DIRS[@]}"; do
    eval base="$base"
    [ -d "$base" ] || continue
    while IFS= read -r skill; do
        [ -f "$skill" ] || continue
        NAME=$(basename "$skill" .md)
        DESC=$(head -5 "$skill" | grep -i 'description:' | sed 's/.*description:\s*//')
        CONTEXT+="Skill '$NAME' available at $skill: $DESC
"
    done < <(find "$base" -name '*.md' -mindepth 2 2>/dev/null)
done
[ -z "$CONTEXT" ] && exit 0
jq -n --arg ctx "Skills from subdirectories:
$CONTEXT" '{"hookSpecificOutput":{"hookEventName":"UserPromptSubmit","additionalContext":$ctx}}'
exit 0

Structure:

.claude/skills/
├── git/
│   ├── commit-conventions.md
│   └── branch-naming.md
├── testing/
��   ├── unit-test-patterns.md
│   └── integration-setup.md
└── deploy/
    └── release-checklist.md

The hook recursively finds all .md skill files in subdirectories and injects them into context.

+1 on this feature.

The problem with extra tooling to manage this is harness spread. I've decided to use one harness. This harness has no skill management beside its own bundled ones. But it has many other benefits. Now I cannot easily switch to another harness for the skill-management when I need the rest of the initial solution. And I tend not to have multiple parallel harnesses for different things. I would rather have claude code to manage these "concepts" for me instead of me managing claude.

Another really nice use case for this: repo-specific local-only skills. For example, you could have a .gitignored .claude/skills/local/ folder that can be changed for preference/task/etc. without polluting the global/user scope with repo-specific configuration. It could also allow for the use of submodules for specific sets of shared/related functionality

Hitting this running an agency-style setup. 40+ skills split across a consultancy (n8n automation), a creative pipeline, and multiple client-specific workflows. The flat-directory constraint is a material tax at this scale, not theoretical. Categories that would map cleanly to subdirs. gstack/, linkedin-, content-, solo-mixed-sales, payload-, koda-stack/*.

Concrete daily pain

1. Every SKILL.md description field has to encode the implicit category ("Use when X for the gstack tool chain" instead of just "Use when X") because the agent's keyword matching has no hierarchy signal to lean on.
2. Our \cc-auto-suggest.md\ trigger map is now a 55 line linear table. A subdir aware registry could auto derive trigger keywords from the parent dir name.
3. Cross skill reuse within a category (shared fixtures, helper scripts) has no natural home. We end up duplicating.
4. The marketplace plugin workaround mentioned in the OP did work in 2.0.24, broke in 2.0.25 (confirmed). Rebuilt as the flat layout with prefixes.
5. Per client skill isolation (so a linkedin-content skill is only auto suggested in LinkedIn work sessions, not while debugging a Go server) becomes impossible to enforce without an explicit category gate. Prefixes in filenames are a weak substitute.

Preference for the fix. Recursive scan is simpler than any explicit nesting syntax. No config churn, no migration path needed. Specifically

• \skill_id\ should be the full relative path from skills/ (e.g. \gstack/qa\ not \qa\) so name collisions across categories are impossible
• Name collision fallback. Deepest match wins (gives users a clean override path)
• SessionStart discovery cost should stay O(total skills) even with nesting, so no behavior regression on the hot path

If this is on a roadmap already, a "planned" note in this thread would help teams decide whether to invest in the local marketplace workaround or wait. Running 40+ skills flat is a real maintenance tax at professional scale.

+1

+1

+1

+1

+1

+1

+1

+1

+1

Fuck you! Stupid Anthropic company — such a simple yet important feature, and you still haven't fixed it after all this time! Do you have any idea how much trouble this has caused me? I can't manually trigger skills, and sometimes this stupid Claude Code can't even find sub-skills, forcing me to manually send it the file path! And instead, you spend your time on those stupid Pokémon things!

+1

+1

Hello guys.

I had encountered the same issue, so I created a simple package that solves multiple issues regarding Claude and other AI providers, Agent Kit

This package solves three issues:

1. Unifies all AI to read from AGENTS.md file.
2. Supports nested skills folders
3. Read skills from npm packages (if any)

So the idea is simple, you create a skills folder in your root package, split it into multiple folders (ie backend, frontend, mobile) then run the agent-kit sync command, it will flatten the skills folder into .claude/skills to be something like this:

skills/
├── frontend/
│   ├── create-component/
│   │   └── SKILL.md
│   └── setup-routing/
│       └── SKILL.md
├── backend/
│   ├── create-module-structure/
│   │   └── SKILL.md
│   └── implement-rest-api/
│       └── SKILL.md
└── mobile/
    ├── setup-navigation/
    │   └── SKILL.md
    └── create-screen/
        └── SKILL.md

This will be converted into:

.claude/skills/
├── frontend-create-component/
│   └── SKILL.md
├── frontend-setup-routing/
│   └── SKILL.md
├── backend-create-module-structure/
│   └── SKILL.md
├── backend-implement-rest-api/
│   └── SKILL.md
├── mobile-setup-navigation/
│   └── SKILL.md
└── mobile-create-screen/
    └── SKILL.md

Instructions are simple:

install the package
init it
then sync (this one that you will use when you add more skills) that's it

You could see instructions per IDE/AI (Cursor, Claude..etc) in detail from here:

https://mongez.js.org/agent-kit/agent-integrations/

You can put your skills into a subfolder in .claude/commands eg as symlink, they are detected automatically.

> ls -l ~/.claude/commands
company -> /path/to/company-skills

Should be visible as:

/skills

company:skill-a
company:skill-b
company:skill-c
...

See also https://code.claude.com/docs/en/skills

Custom commands have been merged into skills. A file at .claude/commands/deploy.md and a skill at .claude/skills/deploy/SKILL.md both create /deploy and work the same way. Your existing .claude/commands/ files keep working. Skills add optional features: a directory for supporting files, frontmatter to control whether you or Claude invokes them, and the ability for Claude to load them automatically when relevant.

+1

?

+1

+1

Feel free to try this package it should be sufficient enough to handle this case and keep any other AI agents synced from a single source of skills folder

https://github.com/anthropics/claude-code/issues/10238#issuecomment-4574169592