afaraha8403afaraha8403/mental/.claude/skills/publishing-mental-to-stores/SKILL.md

publishing-mental-to-stores

Skill5 starsChanged yesterdayMITView on GitHub

Publish and update the Mental CLI (@balacode/mental) on every platform it supports: npm with version lockstep and the release.yml workflow, the Claude Code marketplace and Anthropic directory, the Cursor plugin and marketplace, the GitHub Copilot CLI marketplace, VS Code plugin install, Codex/ChatGPT plugins and OpenCode npm plugins, plus per-host update steps. Use when the user asks how to release, ship, list, submit or update Mental on a store or marketplace, or why a host still shows an old version.

We split this skill into the rules it gives an agent

7 rules. About 0 are common, 0 are distinctive, and 7 are very specific to this project.

≈0
Common · estimate
Many files like this have a rule of this kind.
≈0
Distinctive · estimate
This author's own choices. Worth a look.
7
Very specific
Tied to their project's names, files or tools. Probably skip.

Common
Distinctive
Very specific

Very specific:
After the user confirms: create a GitHub Release tagged exactly vX.Y.Z (mark betas as prerelease).
line 55
Very specific:
Verify: npm view @balacode/mental version equals package.json.
line 57
Very specific:
If publish failed or was skipped: fix the workflow and run workflow_dispatch against the existing tag.
line 58
Very specific:
Never print, log or commit NPM_TOKEN, CLOUDFLARE_API_TOKEN, or CLOUDFLARE_ACCOUNT_ID.
line 65
Very specific:
Never use MENTAL_SKIP_HOST_PLUGIN_CHECK outside tests.
line 66
Very specific:
Never ship a tag that differs from package.json.
line 67
Very specific:
Do not claim a store listing exists when it does not.
line 69

≈ “Common” is an estimate: at least 1 in 5 of the 308,232 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.

Files

SKILL.md

Publishing Mental to every supported platform

Mental is one product shipped through several channels. npm is the source channel; every host plugin install reads the same Git repo. Never tag, publish, submit or open a PR unless the user explicitly asks for that in this turn, and confirm the version and branch first.

Channel map

Platform	Channel	Store submission?	Reference
npm	`@balacode/mental` via GitHub Release and `release.yml`	No (registry)	references/npm-release.md
Claude Code	Own marketplace in this repo (`.claude-plugin/marketplace.json`)	Optional: Anthropic directory portal (paid plan)	references/claude.md
Cursor	Plugin from the Git repo; `.cursor-plugin/plugin.json`	Optional: cursor.com/marketplace/publish (manual review, open source)	references/cursor.md
GitHub Copilot CLI	Same Git repo as a marketplace	None exists; push the repo	references/copilot.md
VS Code	Chat: Install Plugin From Source	No	references/copilot.md
Codex / ChatGPT	OpenAI plugin ZIP	Only with a remote MCP server; Mental is skills-only	references/codex-opencode.md
OpenCode	npm plugin	No official process; Mental has no plugin	references/codex-opencode.md

Version lockstep (the invariant)

package.json version is the source of truth. The git tag is v plus that string. npm must publish that same string. node scripts/bump-version.mjs X.Y.Z writes it to plugin.json, .cursor-plugin/plugin.json, .claude-plugin/plugin.json, the lockfile and skill metadata; --check fails on drift. Never put version on a marketplace.json plugin entry.

Release workflow (summary)

Work on main for production, staging for beta (X.Y.Z-beta.N).
node scripts/bump-version.mjs X.Y.Z, then node scripts/bump-version.mjs --check.
Cut CHANGELOG [Unreleased] into ## [X.Y.Z] - YYYY-MM-DD; commit.
After the user confirms: create a GitHub Release tagged exactly vX.Y.Z (mark betas as prerelease).
release.yml runs tests on three OSes, checks tag and lockstep, skips if already on npm, then publishes (--tag beta for prereleases). The same GitHub Release starts deploy-website.yml, which deploys website/ to Cloudflare. That workflow also runs when website/ changes on main.
Verify: npm view @balacode/mental version equals package.json. Not done until it does. The site deploy is done when the Deploy website workflow succeeds.
If publish failed or was skipped: fix the workflow and run workflow_dispatch against the existing tag. Never cut a new tag to fix npm.

Full commands, failure modes and the post-release host refresh: references/npm-release.md and references/after-release.md.

Safety

Confirm with the user before any tag, GitHub Release, npm publish, store submission or PR. Say which version and which channel.
Never print, log or commit NPM_TOKEN, CLOUDFLARE_API_TOKEN, or CLOUDFLARE_ACCOUNT_ID. Do not read the secret; the workflows use GitHub secrets. Do not npm publish or wrangler deploy production from a laptop.
Never use MENTAL_SKIP_HOST_PLUGIN_CHECK outside tests.
Never ship a tag that differs from package.json.
Repo-only skills under .agents, .claude, .cursor and .codex must stay out of the npm files list and the plugin skills/ folder.
Do not claim a store listing exists when it does not. Cursor /add-plugin mental works only after the marketplace lists it.

Checklist before asking to publish

node scripts/bump-version.mjs --check passes.
CHANGELOG has the dated section; [Unreleased] is empty or reset.
npm test and npm run check:install pass (known baseline failures noted).
On the right branch; tag name equals v plus package.json version.
User confirmed version, branch and channels in this turn.

Anti-patterns

Tagging first and bumping later.
Publishing from a laptop instead of the workflow.
Re-tagging to repair npm.
Setting version on the marketplace plugin entry (the manifest wins and the two drift).
Telling users to run the CLI install subcommand to refresh a host plugin; it does not touch the host plugin cache.

Pointers

Need	Where
npm, tags, workflow, prerelease	references/npm-release.md
Claude marketplace and directory	references/claude.md
Cursor plugin and marketplace	references/cursor.md
Copilot CLI, VS Code	references/copilot.md
Codex and OpenCode	references/codex-opencode.md
What users run after a release	references/after-release.md

Download now (ZIP)

In this repository30 other files it gives its agents.
- docs/agents.mdAGENTS.md
- website/AGENTS.mdAGENTS.md
- .github/copilot-instructions.mdCopilot instructions
- .cursor/rules/claude-desktop-skills.mdcCursor rule
- .cursor/rules/claude-mod.mdcCursor rule
- .cursor/rules/codex-desktop-skills.mdcCursor rule
- .cursor/rules/desktop-and-publishing-skills.mdcCursor rule
- .cursor/rules/release.mdcCursor rule
- claude-code-mods-guideSkill
- claude-desktop-extensionsSkill
- claude-desktop-modsSkill
- claude-desktop-pluginsSkill
- codex-desktop-extensionsSkill
- codex-desktop-pluginsSkill
- codex-desktop-skillsSkill
- copilot-desktop-extensionsSkill
- cursor-extensions-and-pluginsSkill
- opencode-pluginsSkill
- publishing-mental-to-storesSkill
- claude-code-mods-guideSkill
- claude-desktop-extensionsSkill
- claude-desktop-modsSkill
- claude-desktop-pluginsSkill
- codex-desktop-extensionsSkill
- codex-desktop-pluginsSkill
- codex-desktop-skillsSkill
- copilot-desktop-extensionsSkill
- cursor-extensions-and-pluginsSkill
- opencode-pluginsSkill
- mental-setupSkill

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

Reviews can't be read right now.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

Check your setup, free