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

[yasserstudio]

Preflight Checklist

• I have searched existing issues and this hasn't been reported yet
• This is a single bug report (please file separate reports for different bugs)
• 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:

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

2. Verify the skill exists on disk:

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

3. Verify the SKILL.md has valid frontmatter:

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

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

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

5. 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

• [FEATURE] SKILL Tool should recognize local skills in ~/.claude/skills/ #19212 — Skills in ~/.claude/skills/ not recognized (closed, similar but different path)
• Feature: path-based Skill tool invocation for non-discovered skills #46308 — Feature request for path-based Skill invocation (open, would solve this as a workaround)
• [BUG] Skills not loading from ~/.claude/skills/ directory #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.

[github-actions]

Found 3 possible duplicate issues:

1. [BUG] Claude Code assistant not aware of available skills in .claude/skills/ directory #9716
2. [FEATURE] SKILL Tool should recognize local skills in ~/.claude/skills/ #19212
3. Support for AGENTS.md and .agents/skills/, the community has been asking since August 2025 #31005

This issue will be automatically closed as a duplicate in 3 days.

• If your issue is a duplicate, please close it and 👍 the existing issue instead
• To prevent auto-closure, add a comment or 👎 this comment

🤖 Generated with Claude Code

[0xbrainkid]

This is a capability-registration integrity problem.

If skills installed via npx skills add under ~/.agents/skills/ are not recognized by the Skill tool and only return Unknown skill, then the system is breaking the link between installation success and runtime discoverability.

From the user’s point of view, the workflow likely looked complete:

• install succeeded
• expected location populated
• invocation still fails as if the skill does not exist

That is one of the most frustrating classes of tool bugs because it invalidates the user’s model of what “installed” means.

I would want clarity on:

1. whether the install path is no longer part of the runtime discovery set
2. whether the Skill tool is reading a stale cache / registry instead of the current filesystem
3. whether the product should validate registration at install time rather than letting the user discover failure only at invocation

A skill install path should either register a usable capability or fail loudly during install. Silent success followed by Unknown skill makes the capability surface feel untrustworthy.

[github-actions]

Closing for now — inactive for too long. Please open a new issue if this is still relevant.

[github-actions]

This issue has been automatically locked since it was closed and has not had any activity for 7 days. If you're experiencing a similar issue, please file a new issue and reference this one if it's relevant.