[FEATURE] - Configurable Discovery Paths for Skills, Workflows, and Agents

Preflight Checklist

• [x] I have searched existing requests and this feature hasn't been requested yet
• [x] This is a single feature request (not multiple features)

Problem Statement

Look, I'm going to be direct: the current design of hardcoded discovery paths for skills, workflows, and agents in Claude Code is a half-baked solution that forces developers into stupid workarounds.

The Problem

Claude Code looks for skills, workflows, and agents in exactly two places:

• .claude/skills/, .claude/workflows/, .claude/agents/ (project scope)
• ~/.claude/skills/, ~/.claude/workflows/, ~/.claude/agents/ (personal scope)

This is broken when working in repositories where .claude/ isn't gitignored—which, let's be honest, is a lot of repositories. You've got competing constraints:

1. If you commit .claude/ to version control: Personal tools get committed. Now you've got tools that work for you but break for teammates, or worse, they pollute the shared codebase with junk.

1. If you ask the repo maintainer to gitignore .claude/: You hit a wall in enterprise environments, monorepos, or any project with strict gitignore policies. "No, we can't gitignore a hidden directory" is a real response you get.

1. If you use ~/.claude/ instead: Now your tools are global. Good luck having project-specific configurations, workflows that reference local scripts, or agent definitions that make sense only in this repo's context.

This is why developers are creating .claude/local/ directories and manually symlinking into .claude/. That's a bandaid, not a solution. It's the kind of thing you end up doing when the tool doesn't give you the knobs you need.

Why This Matters

Consider a real scenario: you're working in a monorepo with 15 services. You write a skill that orchestrates builds for your service. Your teammate writes one for theirs. Neither of you wants these in version control—they're personal workflows. But you also don't want them cluttering ~/.claude/ alongside tools you use across every project globally.

Proposed Solution

The sensible thing to do is:

my-monorepo/
  .claude/
    settings.json
    settings.local.json  (gitignored)
  .claude/local/  (gitignored)
    skills/
      my-build-orchestrator/
      my-test-runner/
    workflows/
    agents/

But Claude Code won't look there. So you symlink, or you don't use the tools at all, or you commit them.

The Solution (Already Partially Implemented)

Claude Code already has this capability for one thing: plansDirectory. From the settings schema:

{
  "plansDirectory": "custom/path/to/plans"
}

This lets you point to any directory for plans. It's relative to the project root, it works, it's clean. You already solved this problem once. Do it again.

Add three new settings (or one unified one):

{
  "skillsDirectory": ".claude/local/skills",
  "workflowsDirectory": ".claude/local/workflows", 
  "agentsDirectory": ".claude/local/agents"
}

Or simpler:

{
  "customAssetDirectory": ".claude/local"
}

Where Claude Code looks for {customAssetDirectory}/skills/, {customAssetDirectory}/workflows/, {customAssetDirectory}/agents/.

Implementation Details

The discovery logic currently is (approximately):

1. Scan bundled assets
2. Scan ~/.claude/{asset-type}/
3. Scan ./.claude/{asset-type}/ and parent directories

Change it to:

1. Scan bundled assets
2. Scan ~/.claude/{asset-type}/ and ~/.claude/settings.json for skillsDirectory override
3. Scan ./.claude/{asset-type}/, ./.claude/settings.json, ./.claude/settings.local.json for custom path overrides
4. Resolve relative paths against the project root (same as plansDirectory)

Precedence (from highest to lowest):

• ./.claude/settings.local.json custom path
• ./.claude/settings.json custom path
• ~/.claude/settings.json custom path
• Built-in paths (./.claude/{asset}, ~/.claude/{asset})

This is consistent with how settings already layer. No surprises.

Why This Will Get Used

• Enterprise teams that can't modify .gitignore will finally be able to have project-local tools
• Monorepo developers will stop committing personal workflows
• People who like organization will stop symlinking or storing everything globally
• Anyone working in multiple repos with different conventions will have the flexibility to adapt

Right now, anyone trying to do this "properly" hits a brick wall. The workarounds exist, but they're inelegant. Give developers the knob and they'll use it.

What I'm Not Asking For

I'm not asking for environment variable overrides, complex path resolution, or nested discovery. I'm asking for something your own codebase already implements for plans. Copy that pattern. It works.

Summary

The current design assumes everyone has full control over their repository's .gitignore and wants all personal tools in ~/.claude/. That's not reality. Add configurable discovery paths for skills, workflows, and agents—use the same pattern you already use for plans. It's a small change that removes a stupid workaround from the ecosystem.

Alternative Solutions

_No response_

Priority

High - Significant impact on productivity

Feature Category

Configuration and settings

Use Case Example

_No response_

Additional Context

_No response_