[BUG] Cowork only loads 3/27 personal skills from ~/.claude/skills/ — UI does not scan directory

[basaltnode7-arch]

Summary

Cowork only loads 3 out of 27 personal skills from ~/.claude/skills/, despite all 27 having valid YAML frontmatter (name: and description: fields), valid SKILL.md files, correct directory structure, and proper file permissions. 20+ hours of engineering time spent trying to fix this, and all Cowork/chat session history permanently lost after a destructive troubleshooting step that resolved nothing.

Environment

• Platform: macOS, Mac Mini M-series
• App: Claude Desktop (Cowork mode)
• Plan: Claude Max

The Paradox

Inside a Cowork session, Claude CAN see and use all 27 skills — they appear in the session's available_skills list and can be invoked with the Skill tool. The skill content works perfectly.

In the Customize → Skills panel, only 3 personal skills appear: canvas-design, skill-creator, theme-factory. The other 24 are invisible.

This means the underlying skill-loading mechanism works, but the UI management layer does not scan the same directory, creating an inconsistency where skills work but cannot be managed.

Key Observation

The 3 skills that DO load were originally installed through the Cowork Customize UI. The 24 that do NOT load were deployed to ~/.claude/skills/ via rsync/file copy from a GitHub repo. This strongly suggests Cowork maintains an internal registry of "known" skills and does NOT scan ~/.claude/skills/ at startup to discover new skill folders — contrary to documentation.

Steps to Reproduce

1. Place 27 skill folders in ~/.claude/skills/, each containing a SKILL.md with valid YAML frontmatter (---, name:, description:)
2. Verify all pass frontmatter validation and total description budget is under 16K characters
3. Quit Claude desktop app (Cmd+Q) and reopen
4. Open Cowork → Customize → Skills
5. Result: Only 3 personal skills appear. The other 24 are not listed.

What We Tried (All Failed)

1. ✅ Fixed YAML frontmatter on all skills (10 were missing name: or description: — all fixed)
2. ✅ Trimmed descriptions to fit 16K SLASH_COMMAND_TOOL_CHAR_BUDGET — currently at 7,294/16,000 chars (45%)
3. ✅ Removed all skills from Customize and restarted — only same 3 reappear
4. ✅ Ran deploy.sh --force with rsync — confirmed 27 skills deployed with valid frontmatter
5. ✅ Restarted Claude desktop app multiple times
6. ✅ Built automated deployment pipeline with frontmatter validation, budget monitoring, webhook alerts
7. ❌ Deleted ~/Library/Application Support/Claude/local-agent-mode-sessions/ to clear cached data — lost ALL Cowork and chat session history permanently. Skills still did not load. Data is unrecoverable (no Time Machine backup).

Deploy Script Output (Confirming Everything Works at File Level)

[2026-04-19 10:40:02] Excluding 25 skills from Cowork (see .cowork-exclude)
[2026-04-19 10:40:02] ✓ All 52 skills have valid frontmatter
[2026-04-19 10:40:02] 📊 Budget: 7294/16000 chars (45%) across 27 Cowork skills
[2026-04-19 10:40:02] ✓ Budget healthy (45%)
[2026-04-19 10:40:02] ✓ Claude skills updated (27 deployed)

Technical Details

• Skills directory: ~/.claude/skills/ (rwxr-xr-x permissions)
• Skills on disk: 27 folders, each with SKILL.md containing valid YAML frontmatter
• Skills that load (3): canvas-design, skill-creator, theme-factory
• Skills that do NOT load (24): agentic-development, airtable-ops, automation-pipeline-ops, cfo-advisor, champion-proof-proposal, cold-outreach, consolidate-memory, contract-and-proposal-writer, docx, intent-engineering, karpathy-loop-seo, lead-magnets, offer-stack-builder, pdf, pptx, sales-enablement, strategic-presentation-creator, superpowers, tii-executive-coach, vibe-coding, xlsx, tii-brand-voice-guardian, tii-content-repurposing, schedule
• Source: GitHub repo with automated deploy pipeline (scripts/deploy.sh)

Business Impact

• 20+ hours of engineering time across 12 days (April 7–19, 2026) building deployment infrastructure that works perfectly at the file system level but is ignored by Cowork's skill detection
• All Cowork session history and chat history permanently destroyed while attempting to troubleshoot this bug — on the suggestion that clearing session data might fix skill detection (it didn't, and the two systems are unrelated)
• We are a coaching institute (The Integral Institute) with 79 custom skills powering daily operations — executive coaching, SEO content pipeline (235+ articles), client proposals, cold outreach. Without reliable skill loading, our AI workflow is broken.

Requested Fix

1. Cowork must scan ~/.claude/skills/ on startup and detect ALL valid skills with YAML frontmatter, not only those previously registered through the UI
2. Add a "Rescan" button in Customize → Skills to manually trigger skill discovery from disk
3. Or provide a CLI command (e.g., claude skills scan) to register skills from disk
4. Document the exact mechanism for personal skill auto-detection — what triggers registration, what the hidden registry is, how power users can manage it
5. Never suggest deleting session data (local-agent-mode-sessions/) as a troubleshooting step for skill detection issues — the two systems are unrelated

Related Issues

• [BUG] Co-Work fails to uninstall locally-uploaded plugins #28068 — Cowork fails to uninstall locally-uploaded plugins
• Cannot uninstall plugin: enabledPlugins false ignored, plugin re-installs every session #28554 — Cannot uninstall plugin: enabledPlugins false ignored, plugin re-installs every session

[github-actions]

Found 3 possible duplicate issues:

1. Desktop app Customize window doesn't show user-authored skills from ~/.claude/skills/ #39994
2. [BUG] Skills from ~/.claude/skills/ and plugins not shown in Customize -> Skills panel #31597
3. Cowork: User-defined Skills from ~/.claude/skills/ not loaded #43270

This issue will be automatically closed as a duplicate in 3 days.

• If your issue is a duplicate, please close it and 👍 the existing issue instead
• To prevent auto-closure, add a comment or 👎 this comment

🤖 Generated with Claude Code

[abhinas90]

This looks like the Cowork skill scanner is only picking up skills from the first level of ~/.claude/skills/ — not recursing into subdirectories.

Possible workaround while waiting for a fix:

1. Move all your skills to flat structure in ~/.claude/skills/ (no subdirectories)
2. Or symlink subdirectory skill files up to the root level

The YAML frontmatter validation should work if you have name: and description: at minimum — but the scan itself might be stopping at directory depth 0.

If the 3 that work are in the root of skills/ and the 24 that don't are in subdirectories, that confirms the depth issue. Could you check that?

Side note: this kind of environment inconsistency is exactly why skill portability matters. If you're managing a lot of skills across machines, storing them in a versioned repo and publishing to ClawHub can help — then they install consistently regardless of local path issues: https://clawhub.dev

[basaltnode7-arch]

Correction — Bug is more severe than originally reported.

In the original report I stated that all 27 skills work inside Cowork sessions even though the Customize UI doesn't show them. Upon verification, this is not accurate.

The current Cowork session only loads 10 skills — not 27. The loaded skills are: canvas-design, consolidate-memory, docx, pdf, pptx, schedule, setup-cowork, skill-creator, theme-factory, xlsx.

The other 17 custom skills (agentic-development, automation-pipeline-ops, cold-outreach, intent-engineering, karpathy-loop-seo, superpowers, tii-executive-coach, tii-brand-voice-guardian, tii-content-repurposing, sales-enablement, champion-proof-proposal, cfo-advisor, airtable-ops, contract-and-proposal-writer, lead-magnets, offer-stack-builder, strategic-presentation-creator) are not available inside sessions either.

This means the skills don't just fail to appear in the UI — they also fail to load into Cowork sessions entirely. The files are on disk with valid YAML frontmatter but Cowork ignores them completely, both in the management UI and at runtime.

[basaltnode7-arch]

Smoking gun — skills ARE registered but UI won't show them.

When attempting to manually upload a skill ZIP through Customize → Skills → Upload, the dialog returns:

⚠️ "This skill name is already in use. Try a different name."

This proves:

1. Cowork's internal registry DOES know about the skills — it recognizes the name and blocks a duplicate
2. The Customize → Skills UI refuses to display them even though they're registered
3. The user cannot re-upload them (blocked as duplicate) AND cannot see/manage them (not listed)

The user is completely stuck: can't add (already exists), can't see (not displayed), can't remove (not listed), can't use (not loaded into sessions).

Screenshot of the error dialog attached to this comment confirms the exact wording.

This appears to be a UI rendering/filtering bug — the skills exist in the internal registry but are being filtered out of the display list, possibly due to how they were originally registered (file copy vs. UI upload).

[basaltnode7-arch]

Important correction — ZERO custom skills load, not 3.

The 3 skills that appear in Customize → Skills (canvas-design, skill-creator, theme-factory) are Anthropic's built-in default skills, not user-installed skills. This means:

• 0 out of 27 custom personal skills load — not 3 as originally reported
• Cowork has never successfully loaded any skill deployed via file copy to ~/.claude/skills/
• The only skills that appear are Anthropic's own defaults that ship with the app
• Built-in skills (schedule, setup-cowork, context) also load because they're Anthropic defaults

The entire personal skills feature appears broken for file-deployed skills. No custom skill placed in ~/.claude/skills/ via any method other than the Upload UI has ever been detected by Cowork in our experience.

[basaltnode7-arch]

Workaround confirmed — manual UI upload is the ONLY way to register skills.

After removing all skills from ~/.claude/skills/ and re-uploading all 27 as ZIP files through the Customize → Skills → "+" → Upload dialog, all skills now appear and load correctly.

Root cause confirmed: Placing SKILL.md files in ~/.claude/skills/ via file copy, rsync, or any method other than the Cowork Upload UI does NOT register the skill. Cowork maintains an internal registry that is only written to via the Upload UI. The ~/.claude/skills/ directory is read for content but not scanned for discovery.

Documentation gap: The Claude docs and help center articles state that personal skills placed in ~/.claude/skills/ should be automatically available. This is incorrect. Skills must be uploaded through the UI to be registered. This undocumented requirement cost 24+ working hours and the permanent loss of all session history.

The bug still stands: Cowork should scan ~/.claude/skills/ for new skills, or at minimum the documentation should clearly state that UI upload is required for registration.