Docs
Everything from your first install to removing the last skill. If you only want the short version, read Quick start.
On this page
What Musyskills is
Musyskills (Must be Yours Skills) is a set of agent skills for developers. A skill is one Markdown file,SKILL.md, that teaches your coding agent a workflow: what to check first, which steps to follow, and which rules never to break. Your agent reads the skill when your request matches it, or when you call it by name, and then follows the same steps every time.
Skills work in Claude Code, Codex, Cursor, and Antigravity. Each tool looks for skills in its own folder, and the musyskills CLI puts them there for you.
Requirements
- Node.js 24 or later for the CLI. Check with
node -v. The CLI has no other dependencies. - A project folder, or nothing at all if you install for your user with
--global. - One of the supported tools: Claude Code, Codex, Cursor, or Antigravity.
The Claude Code plugin and the manual install do not need Node.js. Skills are bundled inside the npm package, so once npx has downloaded it, installing skills works offline.
Quick start
Four steps from nothing to a working skill.
- 1
Check Node.js
The version must be 24 or later.
$ node -v - 2
Open your project
Go to the folder your agent works in.
$ cd ~/projects/my-app - 3
Install the skills
Install every skill, or name only the ones you want. The CLI finds which tools the project uses and installs into each of their folders.
$ npx musyskills add --all - 4
Start a new agent session and use a skill
Open a new session so the agent loads the skills, then ask for the work or call the skill by name.
/code-changes-review
First install
The CLI is the npm package musyskills. You do not need to install it ahead of time:npx, which comes with Node.js, downloads it the first time you run it. Start by checking your Node.js version:
$ node -vv24.11.0
Any version from v24 up works. Then run the CLI once. On the first run, npx asks to downloadmusyskills; type y and press Enter. Later runs use the downloaded copy.
$ npx musyskills --version2.1.0
Seeing the version number means the CLI works. If you would rather type musyskills withoutnpx, install it globally instead. Every command on this page then works without thenpx prefix:
$ npm install -g musyskills$ musyskills --versionWith a global install, update the CLI itself with npm install -g musyskills@latest before runningmusyskills update.
Install skills with the CLI
See every skill with a one-line description first:
$ npx musyskills listapply-review-feedback Implement fixes for existing code review comments or requested changes... code-changes-review Review modified or staged code for correctness, security, readability... explain-changes Summarize and explain the current uncommitted or unpushed code changes... pr-draft Prepare or update a pull request title and description for the current... prd-generator Generate a structured Product Requirements Document (PRD) by interviewing... project-explanation Understand a project comprehensively and explain it clearly to the user. push-to-origin Reviews uncommitted changes, excludes files that shouldn't be committed... release Cut a new release from the changes recorded under [Unreleased] in CHANGELOG.md.
Then install one skill, several, or all of them:
$ npx musyskills add pr-draft$ npx musyskills add pr-draft push-to-origin release$ npx musyskills add --allThe CLI prints which tools it detected and what it did in each folder:
Detected: claude ~/projects/my-app/.claude/skills (claude) installed pr-draft installed push-to-origin
Running add again is safe. A skill that is already current is reported asunchanged, and an older copy is replaced with the version in this CLI.
Choose a tool
Without --tool, the CLI looks in the project for files each tool creates and installs for every tool it finds:
| Tool | Detected when the project has |
|---|---|
| Claude Code | .claude or CLAUDE.md |
| Codex | .codex or AGENTS.md |
| Cursor | .cursor or .cursorrules |
| Antigravity | .gemini or GEMINI.md |
If it finds none, it asks which tool to use when you run it in a terminal, and uses Claude Code otherwise. To choose yourself, pass --tool. Repeat it, or separate names with commas, for several tools:
$ npx musyskills add --all --tool cursor$ npx musyskills add --all --tool claude,codexProject or global
By default skills go into the current project, so they only apply there and can be committed with the code. Add --global to install for your user instead, so every project on this computer gets them:
$ npx musyskills add --all --global --tool claudeWith --global, detection looks in your home folder instead of the project. Use the same flag with update, remove, and doctor to manage global skills.
Claude Code profiles
Some people keep separate Claude Code setups, for example ~/.claude-work and~/.claude-personal next to the default ~/.claude, and start each one withCLAUDE_CONFIG_DIR. A global Claude install asks whether you have more than the default. Answern to use ~/.claude, or y to pick profiles: choose them by number, or type the part after claude-. Separate several with commas.
$ npx musyskills add --all --global --tool claude Do you use more than the default Claude (~/.claude)? (y/N) y Claude profiles in your home folder: 1) claude ~/.claude 2) claude-personal ~/.claude-personal 3) claude-work ~/.claude-work Pick numbers, or type the name after "claude-". Separate several with commas. claude-work,personal
That installs into ~/.claude-work/skills/ and ~/.claude-personal/skills/. To skip the question, in a script for example, pass the profiles with --profile. Use default for~/.claude:
$ npx musyskills add --all --global --profile work,personalWithout a terminal and without --profile, skills go into ~/.claude. WhenCLAUDE_CONFIG_DIR is set, for example inside a running profile, that folder is used and nothing is asked. update --global and doctor --global cover every profile they find. Project installs are not affected: they always go into the project's .claude/skills/.
Where skills go
| Tool | Project | Global |
|---|---|---|
| Claude Code | .claude/skills/ | ~/.claude/skills/ |
| Codex | .agents/skills/ | ~/.agents/skills/ |
| Cursor | .cursor/skills/ | ~/.cursor/skills/ |
| Antigravity | .agents/skills/ | ~/.gemini/config/skills/ |
Each skill is a folder with a SKILL.md inside, for example.claude/skills/pr-draft/SKILL.md. On Windows, ~ is your user folder, such asC:\Users\you. Codex and Antigravity share .agents/skills/ in a project, so a skill is installed there once.
Use a skill
Agents load skills when a session starts, so open a new session after installing. Then there are two ways in:
- Ask for the work. Each skill's description lists the requests it handles. "Review my changes before I commit" runs
code-changes-review, and "commit and push this" runspush-to-origin. - Call it by name. Type
/and the skill name, optionally followed by what the skill expects. Each skill page on this site shows its usage.
/pr-draft/push-to-origin "fix: handle empty config"/prd-generator team invitationsSkills that change something outside your machine, such as push-to-origin andrelease, always show you what they are about to do and wait for your confirmation first.Browse every skill to see what each one does.
Check your install
doctor shows the tools it detected, every skills folder it found, and the state of each skill:
$ npx musyskills doctormusyskills 2.1.0 (project: ~/projects/my-app) Detected tools: claude ~/projects/my-app/.claude/skills (claude) pr-draft: modified push-to-origin: current
Update
update brings every skill that musyskills installed up to the CLI's version. Use@latest so npx does not reuse an older cached copy of the CLI:
$ npx musyskills@latest update$ npx musyskills@latest update --global~/projects/my-app/.claude/skills (claude) updated pr-draft unchanged push-to-origin
update checks the folders of every supported tool, so it needs no --tool. It only touches the project, or only your user folder with --global. If it finds nothing it printsNo skills installed by musyskills were found.
Your edits are kept
You can edit an installed SKILL.md to fit your team. musyskills keeps a record in each skills folder, .musyskills.json, with the version and a fingerprint of every skill it installed. Before changing anything, it compares the files with that record:
| State | Meaning | add and update | remove |
|---|---|---|---|
current | Same as this version | Left as is | Removed |
outdated | Unchanged since install, newer version available | Updated | Removed |
modified | You edited it after install | Skipped | Skipped |
foreign | A folder musyskills did not install | Skipped | Skipped |
A skipped skill is listed with the reason:
~/projects/my-app/.claude/skills (claude) skipped pr-draft: was edited after install (use --force to overwrite)
To replace your edited copy with the released one, add --force. Keep a copy of your changes first if you want them back.
Share with your team
Project skills are ordinary files. Commit the skills folder, including .musyskills.json, and everyone who clones the repository gets the same skills. Anyone can later runnpx musyskills@latest update and commit the result.
$ git add .claude/skills$ git commit -m "chore: add musyskills skills"Remove
Name the skills to remove. Only skills that musyskills installed, and that you did not edit, are removed:
$ npx musyskills remove pr-draft$ npx musyskills remove release --global --tool antigravityTo remove everything, list every skill by name, as shown by npx musyskills list. When the last skill in a folder is removed, .musyskills.json is deleted too. Add --force to also remove skills you edited.
Claude Code plugin
In Claude Code you can install every skill as one plugin instead of using the CLI. Run these inside Claude Code:
/plugin marketplace add ahmadammarm/musyskills/plugin install musyskills@musyskillsPlugin skills are namespaced: call them as /musyskills:pr-draft. The short /pr-draftalso works when no other command uses that name. Get new releases with the first command below, or turn on auto-update under /plugin > Marketplaces. The other two remove the plugin and the marketplace.
/plugin marketplace update musyskills/plugin uninstall musyskills@musyskills/plugin marketplace remove musyskillsUse either the plugin or the CLI for Claude Code, not both, so the same skill is not loaded twice.
Manual install
- Download or clone the skills folder.
- Copy the skill folders you want into your tool's folder from Where skills go, keeping the file name
SKILL.md. - Start a new agent session.
For example, skills/pr-draft/ becomes .claude/skills/pr-draft/SKILL.md. Skills copied by hand have no record in .musyskills.json, so the CLI treats them asforeign and leaves them alone. To manage them with the CLI later, delete the copies and runnpx musyskills add.
Troubleshooting
The agent does not see a new skill
Start a new session; agents read skills when a session starts. Then run npx musyskills doctor to confirm the skill is in the folder your tool reads. If it went to the wrong tool, install again with--tool.
npm warns about an unsupported engine
Your Node.js is older than 24. Check with node -v and install Node.js 24 or later fromnodejs.org or your version manager.
"was edited after install"
You or a teammate changed that skill. musyskills will not overwrite it. Keep it, or pass--force to replace it with the released version.
"exists but was not installed by musyskills"
A folder with that name was already there, for example from a manual copy. Rename or delete it, or pass--force to replace it.
"Unknown skill"
The name is misspelled. Run npx musyskills list for the exact names.
update keeps installing an old version
npx reused an older cached CLI. Run npx musyskills@latest update.
Command reference
| Command | What it does |
|---|---|
list | List every available skill with its description. |
add <skill...> | Install or update the named skills. Use --all for every skill. |
update | Update every skill musyskills installed, in all tool folders. |
remove <skill...> | Remove the named skills that musyskills installed. |
doctor | Show detected tools, skills folders, and the state of each skill. |
| Option | What it does |
|---|---|
-t, --tool <name> | claude, codex, cursor, or antigravity. Repeat or comma-separate for several. |
-g, --global | Use your user folder instead of the current project. |
-p, --profile <name> | With --global, the Claude Code profile: work for ~/.claude-work, default for ~/.claude. Repeat or comma-separate for several. |
-a, --all | With add, every skill. |
-f, --force | Overwrite or remove skills you edited or that musyskills did not install. |
-h, --help | Show help. |
-v, --version | Show the CLI version. |
The CLI exits with 0 on success, 2 for a usage mistake such as an unknown skill or tool, and 1 for any other error.