[BUG] Skills installed via npx skills add (~/.agents/skills/) not recognized by Skill tool — 'Unknown skill' error

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?

Summary

Skills installed via npx skills add from skills.sh are stored at ~/.agents/skills/<skill-name>/SKILL.md but are not recognized by the Skill tool. Attempting to invoke them returns Unknown skill: <name>.

Environment

• OS: macOS (Darwin 25.4.0)
• Claude Code Version: 2.1.119 (latest)
• Installation: Standard
• Model: Claude Opus 4.6

Steps to Reproduce

1. Install a skill from the skills.sh registry:

``bash
npx skills add kostja94/marketing-skills --yes --global
``

1. Verify the skill exists on disk:

``bash
ls ~/.agents/skills/translation/
# SKILL.md
``

1. Verify the SKILL.md has valid frontmatter:

``yaml
---
name: translation
description: When the user wants to translate content...
metadata:
version: 1.0.1
---
``

1. In Claude Code, attempt to invoke the skill:

``
Skill("translation")
Skill("kostja94/marketing-skills@translation")
``

1. Result: Unknown skill: translation / Unknown skill: kostja94/marketing-skills@translation

Expected Behavior

The Skill tool should discover and invoke skills installed at ~/.agents/skills/ (the standard location used by npx skills add). These skills have valid SKILL.md files with proper frontmatter and should be loadable the same way plugin skills are.

Actual Behavior

The Skill tool only recognizes:

• Built-in slash commands
• Plugin skills installed via /plugin

Skills at ~/.agents/skills/ are completely invisible to the Skill tool despite being valid SKILL.md files.

Current Workaround

The only workaround is to manually Read the SKILL.md file and follow its instructions. This pollutes the conversation context with the full skill content instead of using the harness-managed scoped injection that the Skill tool provides.

Read("~/.agents/skills/translation/SKILL.md")

Impact

The skills.sh ecosystem has hundreds of community skills that users install via npx skills add. None of these are invocable through the Skill tool, which means:

• Users must manually read SKILL.md files instead of using the proper tool
• Skill content permanently enters the conversation context (no scoped injection)
• The CLAUDE.md pattern of documenting "mandatory skills" (e.g., kostja94/marketing-skills@translation) creates a false expectation that these skills are invocable

Related Issues

• #19212 — Skills in ~/.claude/skills/ not recognized (closed, similar but different path)
• #46308 — Feature request for path-based Skill invocation (open, would solve this as a workaround)
• #25072 — Skills not loaded after restarts

Suggested Fix

Add ~/.agents/skills/ to the Skill tool's discovery paths, alongside ~/.claude/skills/ and plugin directories. The SKILL.md format is identical — only the directory location differs.

What Should Happen?

Skills with valid SKILL.md files at ~/.agents/skills/ should be discoverable and invocable via the Skill tool.

Error Messages/Logs

Error: Unknown skill: translation
Error: Unknown skill: kostja94/marketing-skills@translation

Claude Model

Opus

Is this a regression?

Not sure / not applicable

Claude Code Version

2.1.119

Platform

Anthropic API (Max plan)

Operating System

macOS

Terminal/Shell

Terminal.app (macOS)

Additional Information

The ~/.agents/skills/ directory contains 100+ skills installed via npx skills add. All have valid SKILL.md files with proper frontmatter. None are discoverable by the Skill tool.