Skip to content

Commit f6442a3

Browse files
Merge branch 'master' into chore/contributing-version-guardrail
2 parents 8583e16 + fdf2794 commit f6442a3

File tree

5 files changed

+390
-1
lines changed

5 files changed

+390
-1
lines changed

src/collections/blog/2026/04-02-open-source-maintenance-ai-contributors/index.mdx

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -14,7 +14,7 @@ tags:
1414
- Community
1515
- Engineering
1616
featured: false
17-
published: true
17+
published: false
1818
resource: true
1919
---
2020

src/collections/blog/2026/04-03-claude-code-skills-not-found-sessionstart-hook/hero-image.svg

Lines changed: 149 additions & 0 deletions
Loading
Lines changed: 154 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,154 @@
1+
---
2+
title: "Claude Code Skills Not Found After npx Install"
3+
subtitle: "Why installed skills disappear and the SessionStart hook that fixes it permanently"
4+
date: 2026-04-03 10:00:00 -0500
5+
author: Layer5 Team
6+
thumbnail: ./hero-image.svg
7+
darkthumbnail: ./hero-image.svg
8+
description: "npx skill install drops skills into ~/.agents/skills/ but Claude Code reads ~/.claude/skills/. Here are two fixes: a manual symlink and an auto-sync SessionStart hook."
9+
type: Blog
10+
category: Engineering
11+
tags:
12+
- ai
13+
- Engineering
14+
- Open Source
15+
featured: false
16+
published: true
17+
resource: true
18+
---
19+
20+
import { BlogWrapper } from "../../Blog.style.js";
21+
import { Link } from "gatsby";
22+
import Blockquote from "../../../../reusecore/Blockquote";
23+
import Callout from "../../../../reusecore/Callout";
24+
import CTA_FullWidth from "../../../../components/Call-To-Actions/CTA_FullWidth";
25+
import CTAImg from "../../../../assets/images/meshery/icon-only/meshery-logo-shadow.webp";
26+
27+
<BlogWrapper>
28+
29+
<div className="intro">
30+
<p>
31+
You run <code>npx skill install my-skill</code>, the install completes cleanly, and then you open Claude Code and ask it to use the skill. Claude has no idea what you are talking about. The skill simply does not exist as far as the agent is concerned. This is not a broken install or a corrupted file. It is a path mismatch: the <code>npx skill</code> CLI writes to <code>~/.agents/skills/</code>, but Claude Code looks exclusively in <code>~/.claude/skills/</code>. Two different directories, zero overlap.
32+
</p>
33+
</div>
34+
35+
## Where the Paths Diverge
36+
37+
The <code>npx skill</code> command comes from the <a href="https://github.com/anthropics/claude-code" target="_blank" rel="noopener noreferrer">Claude Code ecosystem</a> and follows the <a href="https://agentprotocol.ai" target="_blank" rel="noopener noreferrer">Agent Protocol</a> convention for storing agent assets. Under that convention, skills live at:
38+
39+
```text
40+
~/.agents/skills/<skill-name>/
41+
```
42+
43+
Claude Code, however, resolves skills from its own configuration directory:
44+
45+
```text
46+
~/.claude/skills/<skill-name>/
47+
```
48+
49+
When you run `npx skill install`, the package lands in `~/.agents/skills/`. Claude Code scans `~/.claude/skills/` at startup and finds nothing new. The two directories never communicate with each other by default.
50+
51+
<Callout type="note" title="Quick check">
52+
<p>Run <code>ls ~/.agents/skills/</code> and then <code>ls ~/.claude/skills/</code>. If the skill appears in the first list but not the second, you have confirmed the mismatch.</p>
53+
</Callout>
54+
55+
## Fix 1 - Manual Symlink
56+
57+
The fastest one-time repair is a symlink. A symlink makes the skill directory appear in both locations simultaneously without duplicating any files. Changes to the skill (updates, edits) are reflected in both paths automatically.
58+
59+
```bash
60+
# Symlink a single skill into Claude Code's skills directory
61+
ln -sfn "$HOME/.agents/skills/my-skill" "$HOME/.claude/skills/my-skill"
62+
```
63+
64+
The `-sfn` flags mean: create a symbolic link (`-s`), force-replace any existing entry (`-f`), and treat the target as a directory name rather than following it if it already exists (`-n`). After running this, Claude Code will see the skill on the next session start.
65+
66+
If you have several skills already installed that you want to migrate at once:
67+
68+
```bash
69+
# Symlink all skills from ~/.agents/skills/ into ~/.claude/skills/
70+
for d in "$HOME/.agents/skills/"/; do
71+
[ -d "$d" ] && ln -sfn "$d" "$HOME/.claude/skills/$(basename "$d")"
72+
done
73+
```
74+
75+
This approach works but it requires you to remember to run it each time you install a new skill.
76+
77+
## Fix 2 - The SessionStart Hook
78+
79+
A more durable fix is to configure a `SessionStart` hook in `~/.claude/settings.json`. Claude Code fires this hook automatically at the beginning of every session, before any user interaction. By placing the sync logic there, you never have to think about it again.
80+
81+
<Blockquote
82+
quote="A SessionStart hook runs once at the top of every Claude Code session. That makes it the right place for one-time environment setup that should always be current."
83+
/>
84+
85+
Open (or create) `~/.claude/settings.json` and add the following `hooks` block. If you already have other settings in the file, merge the `hooks` key into your existing JSON rather than replacing the whole file.
86+
87+
```json
88+
{
89+
"hooks": {
90+
"SessionStart": [
91+
{
92+
"hooks": [
93+
{
94+
"type": "command",
95+
"command": "for d in \"$HOME/.agents/skills/*/\"; do [ -d \"$d\" ] && ln -sfn \"$d\" \"$HOME/.claude/skills/$(basename \"$d\")\"; done 2>/dev/null || true",
96+
"async": true
97+
}
98+
]
99+
}
100+
]
101+
}
102+
}
103+
```
104+
105+
The command iterates over every subdirectory in `~/.agents/skills/`, checks that it is actually a directory (guards against empty globs), and creates or refreshes a symlink for it in `~/.claude/skills/`. The `2>/dev/null || true` at the end prevents the hook from surfacing errors when `~/.agents/skills/` does not yet exist or is empty.
106+
107+
Setting `"async": true` means Claude Code does not wait for the symlink loop to finish before proceeding. The operation is fast enough that it will complete well before you type your first message, but marking it async avoids any perceptible delay on startup.
108+
109+
<Callout type="tip" title="Verify the hook is working">
110+
<p>After saving <code>settings.json</code>, close Claude Code completely and reopen it. Run <code>ls ~/.claude/skills/</code> from a terminal while the session is live - your <code>~/.agents/skills/</code> entries should now appear as symlinks.</p>
111+
</Callout>
112+
113+
## What the Hook Does Not Cover
114+
115+
The hook syncs directories but it does not install skills. You still use `npx skill install` to install and `npx skill update` to update. The hook simply ensures that whatever lands in `~/.agents/skills/` is also visible to Claude Code - automatically, every session.
116+
117+
It also does not handle the reverse direction. Skills placed directly in `~/.claude/skills/` (without going through `npx skill install`) are already in the right place and need no syncing.
118+
119+
If you keep skills in a third location - for example a team-shared directory on a network mount or a dotfiles repo you manage yourself - you can extend the hook command to loop over that path as well:
120+
121+
```bash
122+
# Extended version: sync from both ~/.agents/skills/ and ~/dotfiles/skills/
123+
for d in "$HOME/.agents/skills"/*/ "$HOME/dotfiles/skills"/*/; do
124+
[ -d "$d" ] && ln -sfn "$d" "$HOME/.claude/skills/$(basename "$d")"
125+
done 2>/dev/null || true
126+
```
127+
128+
## Why This Happens at All
129+
130+
The root cause is that the `npx skill` CLI and Claude Code were developed along different conventions for where agent assets should live. The Agent Protocol ecosystem uses `~/.agents/` as a neutral, tool-agnostic home for skills, MCP servers, and similar artifacts. Claude Code uses `~/.claude/` as its configuration root, following the same pattern as `~/.vscode/`, `~/.cursor/`, and similar editor-specific directories.
131+
132+
Neither convention is wrong. They serve different goals. The mismatch will likely be resolved in a future release - either `npx skill install` will detect the Claude Code directory and offer to install there, or Claude Code will grow support for reading from multiple skill paths. Until then, the symlink approach or the SessionStart hook bridges the gap without touching either tool's internals.
133+
134+
<Blockquote
135+
quote="The fix takes thirty seconds. The SessionStart hook takes sixty. Either way, you only do it once."
136+
/>
137+
138+
<CTA_FullWidth
139+
image={CTAImg}
140+
heading="Explore Meshery and Claude Code Integration"
141+
alt="Meshery - Cloud Native Manager"
142+
content="Meshery is the open source, cloud native management platform. Pair it with Claude Code skills to automate infrastructure workflows directly from your AI coding session."
143+
button_text="Get Meshery"
144+
url="/cloud-native-management/meshery"
145+
external_link={false}
146+
/>
147+
148+
<div className="outro">
149+
<p>
150+
Hit a different Claude Code configuration issue? The <Link to="/community">Layer5 community</Link> on <a href="https://slack.layer5.io" target="_blank" rel="noopener noreferrer">Slack</a> includes a growing group of developers working through exactly these kinds of AI tooling edge cases - drop in and share what you found.
151+
</p>
152+
</div>
153+
154+
</BlogWrapper>
Lines changed: 86 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,86 @@
1+
---
2+
type: News
3+
title: "Meshery 1.0 debuts, offering new layer of control for cloud-native infrastructure"
4+
subtitle: "Meshery 1.0 adds a visual control layer to simplify managing cloud-native infrastructure."
5+
date: 2026-03-25 12:15:05 +0000
6+
author: "Sean Michael Kerner"
7+
thumbnail: ./news-hero.webp
8+
darkthumbnail: ./news-hero.webp
9+
description: "Meshery 1.0 adds a visual control layer that simplifies management of cloud-native infrastructure."
10+
category: Press Release
11+
tags: ["Meshery"]
12+
presskit: ""
13+
resource: false
14+
published: true
15+
source_url: "https://www.networkworld.com/article/4150130/meshery-1-0-debuts-offering-new-layer-of-control-for-cloud-native-infrastructure.html"
16+
17+
---
18+
19+
{/* A template and instructions for creating news entries. Any styles to be defined can be defined in News.style.js and the class can be used here */}
20+
21+
import { NewsWrapper } from "../../News.style.js";
22+
23+
<NewsWrapper>
24+
Open-source Meshery provides a workspace to design and operate Kubernetes-based infrastructure, showing engineering teams what their infrastructure looks like, how components relate, where configurations conflict, and the impact of proposed changes.
25+
26+
Managing Kubernetes infrastructure across multi-cloud environments has long produced YAML sprawl, configuration drift, and tribal knowledge that lives in individuals rather than systems. AI tools that generate infrastructure configurations faster than teams can review them have made that issue harder to contain. It’s a problem that the open-source Meshery technology was built to solve. Meshery v1.0 is now out, providing a visual management and governance platform for cloud native infrastructure.
27+
28+
Meshery began six years ago as an effort led by Layer5, with a service mesh focus, but it has since expanded well beyond it. Today the platform supports more than 300 integrations across AWS, Azure, GCP and open-source projects. The project ranks as the sixth highest-velocity project in the Cloud Native Computing Foundation (CNCF), with a 350% increase in code commits over the past year, 3,000 contributors, and 10,000 GitHub stars.
29+
30+
"It’s a multi-layer visual designer and visual operator," Lee Calcote, Layer5 founder and Meshery creator, told Network World.Meshery began six years ago as an effort led by Layer5, with a service mesh focus, but it has since expanded well beyond it. Today the platform supports more than 300 integrations across AWS, Azure, GCP and open-source projects. The project ranks as the sixth highest-velocity project in the Cloud Native Computing Foundation (CNCF), with a 350% increase in code commits over the past year, 3,000 contributors, and 10,000 GitHub stars.
31+
32+
## What Meshery does
33+
34+
Despite its name, Meshery is not a service mesh tool. Calcote said the project has spent years trying to shake "that explicit and restrictive connotation." Service mesh was one early use case handled through adapters, but the platform was always built to manage anything that can be described in Kubernetes terms. Calcote said the intent from the start is to be something of a cloud management platform.
35+
36+
In practical terms, Meshery gives engineering teams a shared workspace to design, visualize, and operate Kubernetes-based infrastructure. Rather than working directly against YAML files or Helm charts, teams work with visual representations of their infrastructure inside a component called Kanvas. The visual layout is semantically meaningful: components, their relationships and their configurations are all represented as a connected diagram rather than disconnected text files.
37+
38+
The core unit is a design, a YAML or JSON document representing declarative infrastructure intent. It functions similarly to a shared document in a collaborative editing tool. Teams can leave comments and record architectural decisions inside a design, giving new team members context on why particular configuration choices were made. Kanvas shipped in two forms with v1.0. Kanvas Designer, now generally available, is a drag-and-drop interface for building and modifying infrastructure designs. Kanvas Operator, currently in beta, provides a real-time live view of running clusters for SRE and platform teams.
39+
40+
Meshery is Kubernetes-centric but does not require Kubernetes to run. It does more when Kubernetes is present, but it can also be used to stand up greenfield infrastructure or to discover and document what is already running in a brownfield environment.
41+
42+
Validation runs automatically through an embedded Open Policy Agent (OPA) policy engine on every design change. The engine applies a deterministic rule set across thousands of components and cloud services, identifying relationships between components and flagging configuration issues before changes are applied.
43+
44+
## Where Meshery fits against IaC and infrastructure management tools
45+
46+
There are a lot of different tools in the infrastructure space, including Infrastructure-as-Code (IaC). Tools like Terraform, Pulumi, Spacelift and Crossplane are common points of comparison for Meshery.
47+
48+
Meshery does not replace IaC tooling. Calcote explained that Meshery uses the Helm package manager internally for deployments and can consume Crossplane composite resource definitions, sitting above those tools rather than alongside them.
49+
50+
Where IaC tools manage infrastructure state through code and pipelines, Meshery adds the visual governance layer on top: showing teams what their infrastructure looks like, how components relate, where configurations conflict, and what a proposed change will actually do before it is applied.
51+
52+
Calcote described it as an abstraction on top of Kubernetes custom resource definitions (CRDs), similar in concept to how Crossplane manages them but operating at a higher level across the full stack.
53+
54+
## Networking capabilities
55+
56+
Managing and understanding cloud-native network configuration is part of Meshery.
57+
58+
Meshery includes a built-in load generator called Nighthawk, a C++ tool developed in collaboration with the Envoy project. Nighthawk generates HTTP and gRPC traffic against target infrastructure, measures latency percentiles and throughput and renders results as visual graphs inside Meshery.
59+
60+
Calcote cited Intel as a user that applied the tool to iteratively deploy infrastructure configurations, run performance tests, adjust settings and retest in successive cycles.
61+
62+
A GitHub Action integrates Meshery into GitOps pipelines. When a configuration change is committed, the action can deploy the infrastructure change, run a defined performance test against specified endpoints and return results plus a visual diagram snapshot directly in the pull request. Teams can set throughput and latency thresholds to gate deployments automatically based on the results.
63+
64+
Meshery is also being used to help organizations migrate from the nginx ingress controller, which is no longer supported in Kubernetes. That technology had been widely deployed to help manage network traffic. Calcote noted that getting senior SREs and junior DevOps engineers aligned on what a configuration change actually involves is as much a coordination problem as a technical one.
65+
66+
Teams are also turning to LLMs for quick answers on how to handle the migration, and in environments where AI tooling is built into pipelines, configuration recommendations are arriving faster than teams can meaningfully review them. The visual rendering that Meshery provides addresses that directly.
67+
68+
## What changed in v1.0
69+
70+
Calcote described v1.0 as a maturity milestone rather than a feature release. "It’s a polishing of the work that we’ve been doing for years," he said.
71+
72+
Two structural changes accompany the v1.0 release. Meshery restructured its GitHub footprint into two organizations: github.com/meshery for the core platform, including Meshery Operator and MeshSync, and github.com/meshery-extensions for the 300-plus integrations and adapters. The separation allows the extension community to iterate independently without affecting core platform stability.
73+
74+
Layer5 also launched the Certified Meshery Contributor program alongside v1.0, which the project describes as the first contributor certification in the CNCF. The free program includes five exams covering Meshery’s server, CLI, UI, models and extensibility domains. It is aimed at practitioners working in Go, React and OpenAPI.
75+
76+
## What comes next
77+
78+
The primary post-1.0 roadmap item is a bring-your-own LLM integration. Currently the OPA policy engine operates deterministically. The planned integration will let users direct infrastructure queries to an LLM of their choice.
79+
80+
"Since Meshery is looking at your actively running infrastructure, you may want to ask any number of questions about optimization, about configuration changes that you might like to do," Calcote said.
81+
82+
A parallel workstream will give users the option to choose between the existing deterministic ruleset and LLM-based assessment for the same governance tasks the policy engine handles today, including evaluating cost, security and resiliency tradeoffs.
83+
84+
Looking further ahead, Calcote described a vision for Meshery becoming a standard format for sharing and presenting infrastructure designs. "It becomes the canonical way of expressing these concepts, with the added benefit that whatever architecture you’re trying to promote, that it’s also deployable," Calcote said.
85+
86+
</NewsWrapper>
42.4 KB
Loading

0 commit comments

Comments
 (0)