anthropics / anthropics/claude-agent-sdk-python

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

Open
#456 5 comments 9 reactions 0 assignees View on GitHub
enhancement
Dominant language
Python
Stars
8.1k
Forks
1.3k
Avg merge
2d 31m
Merged PRs (30d)
1

Description

## 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:

```python
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:

```python
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

Contributor guide

No contributing guide indexed for this repository

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.