Feature: Add explicit skill/command path configuration separate from CLI settings

[jsham042]

Problem

The .claude/ directory serves dual purposes:

1. Claude Code CLI reads it for settings, permissions, and MCP server configuration
2. Agent SDK reads it for skills/commands discovery (.claude/commands/*.md, .claude/agents/*.md)

When building agents that need custom skills while running from directories where Claude Code CLI is also used, this creates confusion. Skills must be discoverable from the working directory's .claude/ path, often requiring symlinks.

Current Behavior

The SDK correctly isolates settings by default (setting_sources=None loads no settings), which is good. However, if you want to use custom commands/skills, they must exist in {cwd}/.claude/commands/ or {cwd}/.claude/agents/.

Workaround

Symlink the project's .claude/ into each session directory:

claude_symlink = session_path / ".claude"
project_claude = project_root / ".claude"
if project_claude.exists() and not claude_symlink.exists():
    claude_symlink.symlink_to(project_claude)

Proposed Solution

Add explicit path configuration for agent resources:

ClaudeAgentOptions(
    # Explicit paths for agent resources (independent of setting_sources)
    commands_path="/path/to/my/commands",  # or list of paths
    agents_path="/path/to/my/agents",

    # Existing setting_sources continues to control CLI settings
    setting_sources=None,  # Still isolated from CLI settings
)

This would:

• Decouple agent resource discovery from CLI settings
• Eliminate the need for symlinks
• Make it clear what is agent config vs CLI config

Alternatives Considered

1. Document the symlink pattern - Works but feels like a workaround
2. Subdirectory convention (e.g., .claude/agent/commands/) - Still couples to .claude/ directory