pstack: poteto-mode `name` breaks the documented identifier constraint and fails to load on other harnesses
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:
name— Required. 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
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- 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