[BUG] Skills fail to load silently on macOS due to quarantine attributes

Preflight Checklist

• [x] I have searched existing issues and this hasn't been reported yet
• [x] This is a single bug report (please file separate reports for different bugs)
• [x] I am using the latest version of Claude Code

What's Wrong?

Bug Report: Skills Fail to Load Due to macOS Quarantine Attributes

Report Date: November 26, 2025
Claude Code Version: 2.0.55 (Claude Code)
Platform: macOS (Darwin 25.1.0)

---

Summary

Custom skills placed in .claude/skills/ fail to load silently when files have macOS quarantine attributes (com.apple.quarantine). The skill loader does not handle quarantined files, provide error messages, or inform users why skills are unavailable.

Environment

• OS: macOS (Darwin 25.1.0)
• Claude Code Version: [Check with claude --version or from UI]
• Working Directory: /Users/Srini/learn/CC/WithoutSA
• Skill Location: .claude/skills/srini/codebase-documenter/

Steps to Reproduce

1. Create or download a custom skill in .claude/skills/
2. Ensure the skill files have macOS quarantine attributes (this happens automatically when downloading files from the internet, transferring via AirDrop, or extracting from downloaded ZIP files)
3. Launch Claude Code in a project directory
4. Ask Claude to use the skill or check available skills
5. Observe: The skill does not appear in <available_skills> and is completely unavailable

Expected Behavior

When a skill file has quarantine attributes, Claude Code should:

Option 1 (Best UX):

• Detect quarantined skill files during startup
• Show a warning message to the user:

``
⚠️ Warning: Skill 'codebase-documenter' could not be loaded due to macOS security restrictions.
Run: xattr -dr com.apple.quarantine ~/.claude/skills/codebase-documenter/
``

Option 2 (Automatic):

• Automatically remove quarantine attributes from .claude/skills/ directory
• Show a notification: "Removed security restrictions from custom skills"

Option 3 (Minimal):

• Include skill loading errors in startup logs
• Provide a --verbose flag to show skill loading diagnostics

Actual Behavior

• Skills with quarantine attributes fail to load silently
• No error messages displayed to user
• No logs indicating why skills failed to load
• <available_skills> section remains empty
• User has no indication that skills exist but are blocked

Root Cause Analysis

File System Evidence

# Quarantined skill file
$ ls -la@ .claude/skills/srini/codebase-documenter/SKILL.md
-rw-r--r--@ 1 user  staff  6450 Nov 27  2025 SKILL.md
	com.apple.quarantine	  21

# After fix
$ xattr -dr com.apple.quarantine .claude/skills/srini/
$ ls -la@ .claude/skills/srini/codebase-documenter/SKILL.md
-rw-r--r--  1 user  staff  6450 Nov 27  2025 SKILL.md

Skill Structure (Verified Correct)

.claude/skills/srini/codebase-documenter/
├── SKILL.md                      # Proper frontmatter format
├── scripts/
│   └── analyze_codebase.py      # Also quarantined
└── (other supporting files)

SKILL.md Format (Verified Correct)

---
name: codebase-documenter
description: Comprehensive codebase analysis and documentation generator...
---

# Codebase Documenter
...

Diagnostic Information

What We Checked

1. Directory structure: ✅ Correct (.claude/skills/srini/codebase-documenter/)
2. SKILL.md format: ✅ Valid YAML frontmatter with name and description
3. File permissions: ✅ Readable (-rw-r--r--)
4. Settings config: ✅ No issues in .claude/settings.local.json
5. File attributes: ❌ QUARANTINE ATTRIBUTE PRESENT

Available Skills During Session

<available_skills>

</available_skills>

Expected:

<available_skills>
- codebase-documenter: Comprehensive codebase analysis and documentation generator...
</available_skills>

Workaround

Users can manually remove quarantine attributes:

# For a specific skill
xattr -dr com.apple.quarantine ~/.claude/skills/your-skill-name/

# For all skills
xattr -dr com.apple.quarantine ~/.claude/skills/

# Restart Claude Code for changes to take effect

Impact

• Severity: Medium
• Frequency: Common (affects all macOS users who download skills)
• User Experience: Poor (silent failure, no debugging information)

Affected Users

• macOS users who download custom skills from the internet
• Users who transfer skill files via AirDrop or external drives
• Users who extract skills from ZIP archives downloaded from GitHub/web
• Any macOS user working with externally-sourced skill files

Suggested Fixes

1. Skill Loader Enhancement (Recommended)

Add error handling in the skill loader:

# Pseudocode for skill loader
def load_skill(skill_path):
    try:
        # Attempt to read skill file
        content = read_file(skill_path)
        parse_skill(content)
    except PermissionError as e:
        # Check for quarantine attribute
        if has_quarantine_attribute(skill_path):
            log_warning(f"Skill {skill_path} blocked by macOS quarantine")
            show_user_message(
                f"⚠️ Skill blocked: {skill_name}\n"
                f"Run: xattr -dr com.apple.quarantine {skill_path}"
            )
        else:
            log_error(f"Permission denied: {skill_path}")
    except Exception as e:
        log_error(f"Failed to load skill {skill_path}: {e}")

2. Automatic Quarantine Removal (Alternative)

Add startup routine to remove quarantine from skill files:

def initialize_skills():
    skills_dir = ".claude/skills"
    if is_macos():
        # Automatically remove quarantine from skills directory
        remove_quarantine_attributes(skills_dir)
    load_all_skills(skills_dir)

3. Diagnostic Command (Minimal)

Add a diagnostic command:

claude skills diagnose
# Output:
# ✓ Found skill: codebase-documenter
# ✗ Blocked by quarantine: /path/to/skill/SKILL.md
# Fix: xattr -dr com.apple.quarantine /path/to/skill/

Additional Context

Why This Happens

macOS applies quarantine attributes to files from:

• Web downloads (Safari, Chrome, Firefox)
• Email attachments
• AirDrop transfers
• Extracted ZIP/archive files from downloads
• Files copied from external drives

The quarantine attribute is part of macOS's Gatekeeper security system and prevents applications from executing or reading certain files without user approval.

Related Issues

• Similar issues may affect .claude/commands/ and .claude/agents/ directories
• Would be worth auditing all .claude/ file loading mechanisms

Reproduction Script

#!/bin/bash
# Script to reproduce the bug

# 1. Create test skill directory
mkdir -p .claude/skills/test-skill

# 2. Create SKILL.md with quarantine attribute
cat > .claude/skills/test-skill/SKILL.md << 'EOF'
---
name: test-skill
description: Test skill for bug reproduction
---

# Test Skill
This skill should appear in available_skills.
EOF

# 3. Simulate downloaded file by adding quarantine attribute
xattr -w com.apple.quarantine "0001;00000000;Browser;" .claude/skills/test-skill/SKILL.md

# 4. Verify attribute exists
echo "Checking for quarantine attribute:"
xattr -l .claude/skills/test-skill/SKILL.md

# 5. Start Claude Code and verify skill is NOT available
echo "Start Claude Code and check <available_skills> - test-skill should be missing"

# 6. Remove quarantine and restart
echo "Removing quarantine..."
xattr -d com.apple.quarantine .claude/skills/test-skill/SKILL.md

echo "Restart Claude Code - test-skill should now appear"

Expected Fix Timeline

This bug affects core functionality (custom skills) on a major platform (macOS). Would appreciate:

• Acknowledgment of the issue
• Priority/severity assessment from the team
• Estimated timeline for fix (if possible)

Contact

• Reported by: [Your GitHub username]
• GitHub Issue: [Will be filled after submission]
• Willing to test fixes: Yes

---

Verification Steps After Fix

1. Download a skill file from the internet (will have quarantine attribute)
2. Place in .claude/skills/
3. Launch Claude Code
4. Verify one of:

• Skill loads successfully with warning message
• Skill loads after auto-removing quarantine
• Clear error message explaining the issue

---

Thank you for Claude Code - this is an amazing tool! This bug report is submitted to help improve the user experience for the macOS community.

What Should Happen?

The detail is captured above. Not the bug summary generated by CC

Error Messages/Logs

All there in the body of the defect

Steps to Reproduce

All there in the body of the defect

Claude Model

Sonnet (default)

Is this a regression?

I don't know

Last Working Version

_No response_

Claude Code Version

2.0.55 (Claude Code)

Platform

Other

Operating System

macOS

Terminal/Shell

Terminal.app (macOS)

Additional Information

BUG_REPORT_SKILL_LOADING.md