Skill descriptions are truncated in initial agent context

[Kevin_Scott]

Where does the bug appear (feature/product)?

Background Agent (GitHub, Slack, Web, Linear)

Describe the Bug

The description field from SKILL.md frontmatter is not populated correctly in agents’ initial context.

In cloud environments, it’s truncated to 80 chars. Locally (Agents Window), it’s not populated at all.

This is a problem when an agent should invoke a skill i.e. the skill is not specified explicitly like /my-skill. The behavior seems to exist across every type of skill from repo, plugins, user, and Cursor-provided.

Steps to Reproduce

Create a new cloud or local agent with this prompt…

Dump the raw text of the entire <available_skills> and <agent_skills> blocks from your initial context.

Do not call any tools. Don't abbreviate or truncate anything. Just print out exactly what you were given.

You’ll see each <agent_skill> description truncated to 80 characters with ellipses before the closing </agent_skill> tag.

Expected Behavior

I assume these should contain the complete description text from each SKILL.md’s frontmatter. If not, then I would expect the full descriptions to appear elsewhere in the agent’s initial context window so it knows about the “use when…” advice from each Skill and can then load the full text of any skill it needs.

Screenshots / Screen Recordings

Operating System

MacOS

Version Information

Version: 3.8.11
VS Code Extension API: 1.105.1
Commit: e56ad3440df06d22ca7501e65fd518e905486ef0
Date: 2026-06-18T01:40:18.333Z
Layout: glass
Build Type: Stable
Release Track: Default
Electron: 40.10.3
Chromium: 144.0.7559.236
Node.js: 24.15.0
V8: 14.4.258.32-electron.0
xterm.js: 6.1.0-beta.256
OS: Darwin arm64 25.5.0

For AI issues: which model did you use?

composer-2.5

For AI issues: add Request ID with privacy disabled

Local (no description content at all):
f9e8a74d-c46c-4dce-ac06-d7442999259c
a6f44947-a506-43b0-94c4-ec1ed62bd930

Cloud (description content is truncated at 80 characters):
bc-c4ad9b48-418a-4ba5-9d8a-0fab7f9eee7e
bc-e112f982-80af-4089-a321-9e3f76021c3c

Does this stop you from using Cursor

Sometimes - I can sometimes use Cursor

[mohitjain (Mohit)]

This is actually intended behavior rather than a malfunction, though I can see why it looks broken. To keep a large skill catalog from crowding out your code and conversation, Cursor caps how much of the skill list gets preloaded into the agent’s initial context. When you have a lot of skills, it first shortens the descriptions to fit, and if they still don’t fit, it lists the skills by path with the description dropped. It’s applied the same way for everyone, so it isn’t random or a per-user experiment.

The cloud vs. local difference you saw is the same cap trimming by different amounts. Your local setup also picks up your global skills (~/.cursor/skills, ~/.claude/skills, etc.) on top of the repo and plugin skills, so there are enough of them that descriptions get dropped entirely. Your cloud agent only sees the repo plus configured plugin skills, so it has fewer and only needs to shorten the descriptions.

The key thing: skills still work even when the description is trimmed. The path is always listed, the agent can open any SKILL.md on demand, and explicit invocation with /skill-name (or attaching with @) is never affected.

That said, your underlying concern is fair. Trimming the “use when…” text does make it harder for the agent to auto-pick a skill it wasn’t explicitly handed. A few things that help today:

1. Front-load the trigger phrase. Put the “use when…” part at the very start of each skill’s description so it survives if the description gets shortened.
2. Trim the active set. Disable plugins you aren’t using and remove global skills you don’t need. Fewer skills means full descriptions are far more likely to fit.
3. Keep descriptions short so more of them fit under the cap.
4. Invoke critical skills explicitly with /skill-name when you want to guarantee one is used.

We’re aware that dropping the description can hurt auto-discovery, and it’s something we’re looking to improve. You can read more about how skills are discovered and the description / paths fields here: Agent Skills docs.

[Kevin_Scott]

The problem is that this kills auto-discovery and the failure is silent. There is no listed max number of skills in the Cursor docs, no warnings in the DX, and the token usage for skills in a new conversation isn’t even significant.

The world went to Skills because progressive disclosure was token efficient in the context window.

We intentionally use Skill auto-discovery so agents can get the information they need as they go (process steps, quality gates, architecture, requirements, etc) without having to invoke Skills manually.

This is a terrible design decision. It not only breaks our workflow, but it hinders agentic development capabilities more broadly.

[mohitjain (Mohit)]

You’re right on two counts. The trimming is silent (there’s no warning when descriptions get shortened or dropped), and the behavior, including what triggers it, isn’t documented. Those are real gaps. And yes, dropping the “use when…” text weakens auto-discovery. That’s the part we’re looking to improve.

A couple of things that genuinely help in the meantime, beyond what I mentioned earlier:

1. Auto-discovery from the catalog depends on the model recognizing a skill from its listing and choosing to open the SKILL.md. When the description is trimmed it has less to go on, which is the failure you’re describing. So for any skill that has to run, explicit /skill-name (or attaching with @) is still the only guaranteed trigger today.
2. Worth a quick check: if any of your skills have a paths: field in their frontmatter, that intentionally keeps them out of the initial skills list. They only get surfaced when the agent reads a file matching that glob, so that’s a separate reason a skill won’t auto-discover, independent of the description trimming.

On the token point, you’re right that a catalog your size is small relative to the window, and that’s exactly the case where the cap can cost more than it saves. That’s the tradeoff we’re re-weighing.

[Jason_Luo1 (Jason Luo)]

This is a good example of why skill discovery needs a visible failure mode.

If descriptions are trimmed, the agent can still open the skill when told to, but automatic discovery becomes much less reliable. I’d rather see a warning like “some skill descriptions were omitted from initial context” than have the agent silently behave as if those skills do not exist.

[Gabe_O_Leary]

This leads to a really bad experience. Using the same prompt with claude, cursor & codex, cursor is the ONLY one which is unable to fulfill my request because it doesn’t have enough of our skill descriptions in context. The idea that I need to modify my skills so they work in cursor when they work perfectly well in other harness is backwards.

[Jason_Luo1 (Jason Luo)]

That is exactly the failure mode that worries me.

If the same skill works in other harnesses, the user should not have to redesign the skill just to make discovery work in Cursor. Cursor can have its own context budget, but then it needs to make that truncation explicit instead of making the skill look broken.