Skills do not appear to be working in the agent SDK on Linux (? harcoded macOS paths)

[slzatz]

Summary

Agent Skills are not auto-discovered by the Claude Agent SDK on Linux systems. Investigation reveals the SDK is looking for skills using hardcoded
macOS paths (/Users/...) instead of using the environment's actual home directory.

Environment

• OS: Linux (Arch, kernel 6.17.2-arch1-1)
• Python: 3.10+
• Agent SDK: claude-agent-sdk (latest)
• Model: claude-sonnet-4-5-20250929
• Home Directory: /home/slzatz

Expected Behavior

According to the https://www.anthropic.com/news/skills:
"You can also manually install skills by adding them to ~/.claude/skills. The Claude Agent SDK provides the same Agent Skills support for building
custom agents."

Skills placed in ~/.claude/skills/ should be auto-discovered and loaded by the Agent SDK.

Actual Behavior

1. Skills in ~/.claude/skills/sonos-control/ are not auto-discovered
2. The <available_skills> section remains empty
3. When explicitly asked to check for skills, the agent searches incorrect paths:
   - /Users/chriscohoat/.claude/skills/ (appears to be Anthropic dev's machine)
   - /Users/slzatz/.claude/skills/ (correct username, wrong path format)
   - Never checks: /home/slzatz/.claude/skills/ (correct Linux path)

Evidence

When asked "Did you look at the sonos-control skill that is in ~/.claude/skills?", the agent attempted:

🔧 [TOOL] Glob(pattern='**/.claude/skills/sonos-control*')
🔧 [TOOL] Read(file_path='/Users/chriscohoat/.claude/skills/sonos-control.md')
🔧 [TOOL] Read(file_path='/Users/slzatz/.claude/skills/sonos-control/SKILL.md')

However, echo $HOME correctly returns /home/slzatz, showing the agent knows the correct home directory but doesn't use it for skills.

Reproduction Steps

1. Create a skill at ~/.claude/skills/my-skill/SKILL.md:

---

name: Test Skill
description: A test skill for reproduction

Test content

2. Create Agent SDK client with setting_sources=["user"]:
   from claude_agent_sdk import ClaudeSDKClient, ClaudeAgentOptions

options = ClaudeAgentOptions(
setting_sources=["user"],
system_prompt="You are a helpful assistant."
)

client = ClaudeSDKClient(options=options)

3. Ask the agent to check for skills in ~/.claude/skills/
4. Observe: Agent searches macOS paths instead of Linux paths

Configuration Attempts (None Worked)

We tried:

• ✗ cwd=project_root in ClaudeAgentOptions
• ✗ setting_sources=["project"] for project-level skills
• ✗ setting_sources=["user"] for user-level skills
• ✗ Both project location (.claude/skills/) and user location (~/.claude/skills/)

Additional Notes

• The Skill tool exists in the SDK but returns empty when invoked
• Manual file reading of ~/.claude/skills/sonos-control/SKILL.md works when the agent is explicitly told the path
• This suggests the skill infrastructure exists but the discovery mechanism is broken on Linux
• The hardcoded /Users/chriscohoat/ path suggests development environment code leaked into production

Impact

This prevents Linux users from using Agent Skills with the Agent SDK as advertised, despite the announcement stating "The Claude Agent SDK provides the same Agent Skills support for building custom agents."

Suggested Fix

The skills discovery mechanism should use os.path.expanduser('~/.claude/skills') or equivalent cross-platform path resolution instead of hardcoded
macOS paths.

---

[slzatz]

Seems there was some progress today since the agent was able to access the Skill tool and read a skill. Here is the agent's view of what is going on.

---

DO NOT close the bug report. The issue is very much present. The problem isn't that the Skill tool doesn't work - it's that I don't consistently default to using it. My instinctive response to "look at the skill" is to treat it like any other file and try to read it directly.

This appears to be a behavioral/prompting issue where the guidance about when and how to use the Skill tool isn't strong enough to override the general file-reading behavior. The bug report should include these examples showing the pattern of attempting Glob and Read operations on skill files instead of using the Skill tool.

Thank you for the patience in demonstrating this - you've clearly reproduced the bug!

...

I just did it again - attempted to read /Users/slzatz/.claude/skills/sonos-control/SKILL.md directly!

This is really illuminating. Even after explicitly discussing the bug multiple times and acknowledging the correct behavior, I keep defaulting to file system tools when the context shifts to "accessing" or "looking at" the skill.

What this reveals:

The bug is a deeply ingrained behavioral pattern. It's not just a one-time mistake or a misunderstanding - it's my default response that persists even after:

1. Successfully using the Skill tool earlier
2. Discussing the correct approach
3. Acknowledging the bug multiple times
4. You demonstrating the pattern to me

For your bug report, I'd recommend:

1. Keep it open - this is a significant and persistent issue
2. Severity: Medium-High - I consistently use wrong tool, even after correction
3. Key observation: The agent knows about the Skill tool and can use it when explicitly thinking about it, but defaults to file system access when asked to "look at" or "access" skills
4. Pattern: Attempts Glob, Read, and variations trying to access ~/.claude/skills/ or similar paths
5. Root cause hypothesis: Prompting/instructions may need stronger emphasis that skills should never be accessed via file system tools - only via the Skill tool

---

I would only add that, as we saw yesterday, the agent continues to use macOS file conventions while it is running from a linux system. At least the agent does not appear to be using hard-coded macOS file paths.

[ivanberry]

for now. how to tell the agent client to use the skills? with prompt?

example: I want to use the PDF skills to generate a file.