How to Find the Zed Skills That Never Made It Into the Catalog (2026 Guide)

A skill only influences the agent if its name and description make it into the catalog the model sees. Zed's documentation names four conditions that keep a file out, plus one that lets it in with a caveat.

The catalog has a byte budget. This is the one nobody expects:

"50KB catalog budget. The total size of all skill names and descriptions is capped at 50KB. Skills that don't fit are dropped from the catalog with a warning in the UI. Keep descriptions concise."

Note what is being measured — names and descriptions, not bodies. So a skill can be dropped because of how verbose your other skills' descriptions are. Adding a skill can evict one you have relied on for months, and the only signal is a warning in the UI you may not have been looking at.

Nesting is not supported. Zed is unambiguous:

"Flat layout only. Skills must be direct children of the skills root. Nested folders like ~/.agents/skills/group/my-skill/ are not discovered."

If you have been organising skills into folders — and the instinct to group by domain is a good one — those skills are not merely deprioritised. They are not found.

Untrusted worktrees contribute nothing. This one catches people on day one of a new repo:

"Project-local skills only load from trusted worktrees. Skills from a freshly cloned or untrusted project are excluded from the catalog and slash commands until you grant trust."

Clone a repository that ships skills, open it, and none of them exist yet. Not in the catalog, not as slash commands.

A frontmatter field can opt a skill out. Zed documents this as a feature, and it is one: "Add disable-model-invocation: true to a skill's frontmatter to stop the agent from picking it up autonomously." Entirely reasonable, and easy to forget you set six weeks ago.

And one near-miss worth knowing. On descriptions: "Keep it under 1024 bytes; skills with longer descriptions still load, but with a warning." So an over-long description does not exclude the skill, but it does consume more of that 50KB budget than it should — which is how a description problem turns into somebody else's exclusion problem.

There is a sixth behaviour that is not an exclusion but explains a different confusion: "If a global and a project-local skill share the same name, the project-local skill takes precedence." Your skill may be present and shadowed rather than absent.

The pattern across all of this is the one covered in why agents ignore your instruction files — a file the tool never loaded looks identical to a file the model chose not to use, and the two need completely different fixes.

Rewriting the description to be more compelling. The usual first move, and it only helps if the skill is in the catalog and losing a relevance judgment. If it was dropped for budget, nesting, or trust, a better description changes nothing — and a longer one makes the budget problem worse.

Restarting Zed. Understandable and unnecessary for content changes. Zed documents live reload: "Adding, removing, or editing a SKILL.md takes effect immediately without restarting your session." Restarting does clear the trust question if you accept the prompt on the way back in, which is probably why it sometimes appears to work.

Invoking the skill explicitly. A good diagnostic, and note what it proves. If an explicit invocation works but autonomous use never happens, you are looking at disable-model-invocation or a description problem, not a discovery problem. If the slash command is missing too, you are in trust territory, since Zed excludes untrusted project skills "from the catalog and slash commands."

Copying the skill to the global root. This does often fix it, which is why it is such a satisfying dead end: it works because the global root is trusted and flat, so you have accidentally eliminated two causes at once without learning which one applied. The next project will have the same problem.

Moving everything into an instruction file instead. Tempting, and it changes the economics rather than solving them: instructions that are always loaded cost context on every message, which is the whole reason skills exist as an on-demand surface. The distinction between the two, and why one is not a substitute for the other, is in why agent skills aren't memory.

Do these in sequence. Each one is cheap, each one is conclusive, and the order matters because the later checks are meaningless if an earlier condition is in play.

Step 1: Settle trust and layout before you look at anything else

Both of these are structural, and both are yes-or-no.

Confirm the worktree is trusted. If you cloned this repository recently and never granted trust, every project-local skill is excluded — and the absence of slash commands for those skills is your confirmation.

Then flatten. Walk the skills roots — the user-level root and the worktree's own — and check that every skill is a direct child. Zed's example of what fails is precise: a path like ~/.agents/skills/group/my-skill/ is not discovered. If you find grouped folders, that is your answer, and the fix is to move them up one level rather than to rename anything.

Worth knowing while you are in there: .agents/skills/ is not a Zed-only convention. Windsurf, Zencoder and OpenHands all read skills from the same path, and Factory reads .agents/ as one of its compatibility directories. A grouped layout that another tool tolerated is exactly the kind of thing that arrives with a shared repository and silently costs you skills in Zed.

Step 2: Audit the catalog budget as a total, not per skill

This is the check nobody runs, because the budget is shared and the failure is attributed to the wrong file.

Add up the name and description length across every skill in both roots. You are looking for the total against a 50KB cap on names and descriptions. Then look for the warning Zed says it surfaces in the UI when skills do not fit — if it is there, you have your cause, and the fix is trimming descriptions rather than deleting skills.

Keep each description under the 1024-byte guidance while you are at it. Zed lets longer ones load with a warning, but they spend budget that a shorter description would not, and the skill they push out will not be the one you were editing.

Step 3: Separate "not in the catalog" from "chose not to use it"

Now, and only now, the frontmatter and relevance questions are answerable.

Check for disable-model-invocation: true. If it is set, the skill is deliberately opted out of autonomous selection and will only run when you ask for it.

Check for a name collision with a global skill, since the project-local one takes precedence and the global one you were expecting is being shadowed.

Then, if the skill is present and the agent still does not reach for it, you are in description territory — and note one cost of iterating there. Zed documents that "changes to a skill's name or description invalidate the model's prompt cache for the current session," so rapid tuning has a real price mid-session.

One more constraint to keep in mind before you start restructuring: "Keep the body of SKILL.md under 500 lines. Move detailed material to reference files and link to them from the body." Long bodies are a separate concern from the catalog, but they are the reason a skill that does fire can still fail to be useful.

The four causes above are mechanical, and once you have cleared them you are left with the harder question: which of this knowledge belonged in a skill at all. Reusable procedures belong in skills. Standing decisions — why this convention exists, which approach you rejected, what the constraint actually is — are not procedures, and pinning them to one editor's catalog puts them behind a byte budget and a trust prompt.

MemoryLake holds that second category as a layer every tool reads, so the decisions do not compete with your skills for catalog space and do not disappear in a freshly cloned repo.

Step 1: Create an API key

Sign in, open your workspace settings, and generate an API key. This is the credential your editor and agents use to read the same layer, so create it once and keep it reachable from each machine you work on.

Step 2: Upload your first memories

Move across the material that is currently padding your skill descriptions: the reasons behind conventions, the constraints that make the obvious approach wrong, the decisions you do not want re-litigated. Shorter descriptions, smaller catalog, same knowledge available.

Step 3: Connect your AI & agents

Connect Zed and whatever else you work in. The standing decisions arrive everywhere, and your skills go back to being what they are good at — procedures the agent can pick up on demand.

The first difference is that the budget stops being a zero-sum game. When descriptions are short because the reasoning lives elsewhere, adding a skill stops evicting another one, and the warning in the UI stops being something you learn to ignore.

The second is that a fresh clone is usable immediately. Trust gating is a sensible security default — and the knowledge a new contributor needs on their first hour should not be gated behind it. The gap it leaves is the same one described in when Zed forgets project context.

The third is that your organisational instinct stops being punished. You wanted folders because you have thirty skills across five domains. Keep the skills flat, put the domain reasoning in a layer that has no layout constraint, and you get the structure without losing discovery.

The fourth shows up with external agents. Zed is careful to note that agents it does not control read their own instruction files, which we covered in Zed's external agents and context. A layer outside the editor's catalog is the only thing all of them can share.

Treat descriptions as catalog space, not documentation. One sentence on what it does and when to use it. Everything else goes in the body or in reference files.

Audit the total after every addition. The cap applies to the sum, so the meaningful number is never per-skill.

Keep the layout flat even when it feels wrong. Direct children of the root, no grouping folders. Encode the grouping in names if you need it.

Grant trust deliberately on clone. And remember that until you do, project skills are absent from both the catalog and slash commands — which makes their absence a poor signal of anything else.

Check for shadowing before debugging content. A project-local skill with the same name wins, so the global one you were reading may not be the one in play.

Leave the authorization requirement alone. Zed states that the agent cannot edit SKILL.md files or their bundled resources without your explicit authorization, even in a trusted project, to prevent a compromised conversation from modifying the skills that govern future ones. That is a good default; do not route around it.

Decide what belongs in a skill at all. Procedures, yes. Reasoning, no. The sorting question is the same one in how much memory you should give an agent, and getting it right is what keeps the catalog small.

Zed's skills system is well documented and its constraints are all published: a 50KB budget on names and descriptions, direct children of the root only, trusted worktrees only, and an opt-out field. What makes them hard is that four independent causes produce one identical symptom, and three of them leave your file looking perfectly fine.

So work the order. Trust and layout first, because they are structural. Budget second, as a total. Frontmatter and relevance last, because those questions only mean something once the skill is actually in the catalog. And then ask the question underneath the whole exercise — whether the thing you were trying to teach the agent was ever a procedure, or whether it was a decision that should never have been competing for catalog space in the first place. What the tools actually load, and in what order, is worth understanding in general; what coding agents actually read covers the wider picture.