cursor / cursor/plugins

pstack: poteto-mode `name` breaks the documented identifier constraint and fails to load on other harnesses

Open
#237 1 comment 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Dominant language
TypeScript
Stars
8.2k
Forks
751
Avg merge
12h 1m
Merged PRs (30d)
43

Description

Summary

pstack/skills/poteto-mode/SKILL.md declares:

name: Poteto Mode

This conflicts with Cursor's own documented constraint for the field. From Agent Skills, Frontmatter fields:

nameRequired. Skill identifier. Lowercase letters, numbers, and hyphens only. Must match the parent folder name.

Poteto Mode has capitals and a space, and it does not match its parent folder poteto-mode. The Agent Skills specification states the same requirement ("Must match the parent directory name").

It is the only one of pstack's 44 skills that does this. The other 43 conform.

Why it matters

Agent Skills is portable by design, and the Cursor docs open by describing it as an open standard. In practice this one field stops poteto-mode loading elsewhere.

Verified on Kiro, which loads skills from ~/.kiro/skills/ following the same spec, using two probes to isolate the cause:

Probe Frontmatter Result
A conforming name, plus disable-model-invocation, mode, icon, color, reminder registers normally, unknown keys ignored
B name with capitals and a space, not matching the folder, no extra keys does not register at all

So the non-standard fields are harmless, and the name value alone is what breaks it. A verbatim copy of poteto-mode does not appear in Kiro's skill menu, and no error is surfaced. It fails silently.

It also fails skills-ref, the reference validator, so a conformance check in CI turns red for a skill that works correctly inside Cursor.

Context

This was introduced deliberately in #149, with the rationale:

The name field is the display label in the slash menu; skill identity and /poteto-mode resolution derive from the folder path, so routing is unchanged.

That holds inside Cursor, and routing is indeed unaffected there. But it treats name as a display label where the docs define it as the identifier, and the cost lands on anyone consuming the skill outside Cursor.

Suggested fixes

Either of these resolves it.

1. Set name: poteto-mode and move the label into metadata, which the spec designates for client-specific extras:

name: poteto-mode
description: ...
metadata:
  cursor-display-name: Poteto Mode

2. Add skill-level displayName support, mirroring the split Cursor already uses one level up. schemas/plugin.schema.json constrains manifest name to ^[a-z0-9]([a-z0-9.-]*[a-z0-9])?$ and provides a separate free-form displayName. Applying that same pattern to skill frontmatter would give display labels a documented home and let name stay conformant.

For what it is worth, displayName in skill frontmatter is currently inert rather than harmful. I tested it on Kiro and the skill registers with the field ignored, so option 2 would need Cursor-side support to actually do anything.

Secondary question

poteto-mode also uses mode: true and reminder:, neither of which appears in the documented frontmatter table (name, description, paths, disable-model-invocation, icon, color, metadata). Are those supported and undocumented, or leftovers? Not a problem in itself, since unknown keys are tolerated, but it makes the documented field list harder to trust when authoring for portability.

Contributor guide

No contributing guide indexed for this repository

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start with pstack/skills/poteto-mode/SKILL.md and compare its frontmatter with the other skills, then inspect schemas/plugin.schema.json for the existing name/displayName pattern. Run skills-ref to confirm the current violation and verify that the chosen resolution makes poteto-mode conformant without leaving the display-label and secondary-field questions undocumented.

Written by the indexing model from the issue text.

Assessment

Tech stack
yaml
Domain
tooling
Issue type
Bug
Difficulty
3/5
Estimated time
1-2 days
Activity status
Active
Clarity
Mostly clear
Newbie friendliness
68/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.