Skip to content

Sharing & Publishing

Publishing workflow

Publishing a skill follows four steps: write, validate, push, and wait for review.

1. Write your skill

Follow the authoring guide to create a well-structured SKILL.md with front matter, clear instructions, and examples.

2. Validate locally

jsm validate ./my-skill

Fix any errors before proceeding. Common issues:

  • Missing required front matter fields
  • Name containing spaces or uppercase letters
  • Description exceeding the character limit

3. Push for review

jsm push ./my-skill -m "Initial release" --attest

The --attest flag confirms you have the right to distribute this content. This is required for all submissions.

Include a changelog message with -m describing what changed. For updates, focus on what is different from the previous version.

4. Wait for moderation

Submitted skills go through a moderation review. You will receive a notification when your skill is approved or if changes are requested.

Review typically checks:

  • The skill is functional and well-written
  • Instructions are clear and produce consistent results
  • Content does not violate the terms of service
  • The skill does not duplicate existing catalog entries without improvement

Updating a published skill

Push a new version with a changelog message:

jsm push ./my-skill -m "Fixed edge case with empty input files"

Updates go through the same review process. Existing users receive the update on their next jsm sync unless they have pinned a specific version.

Changelog best practices

Write changelogs that help users decide whether to update:

# Good
jsm push ./my-skill -m "Added TypeScript generic support; fixed false positive on arrow functions"

# Bad
jsm push ./my-skill -m "Updates"

You can validate changelog text before pushing:

jsm validate --changelog-text "Added TypeScript generic support"

Skill visibility

All published skills are visible in the catalog to subscribers. There is currently no option for private or unlisted skills in the public catalog.

Team plan subscribers can create custom skills that are only visible to their organization. These are managed through the team portal and do not go through public moderation.

Community requests

Users can request skills they would like to see built. Check the request board for ideas:

jsm requests trending

Building a skill that fulfills a popular request is a good way to contribute something users actually need.

Feedback and iteration

After publishing, monitor feedback through the skill page on the web or through CLI notifications. Use feedback to improve your skill over time.

jsm notify list --unread

Removing a published skill

Contact support to request removal of a published skill. Include the skill name and reason for removal.