musyskills 0.0.0-stage → 1.4.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ahmadammarm
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,40 @@
-# Temporary Holding Version
+# musyskills
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Install [Musyskills](https://github.com/ahmadammarm/musyskills) AI agent skills into Claude Code, Codex, Cursor, and Antigravity with one command. Requires Node.js 24 or later.
+
+```
+npx musyskills list
+npx musyskills add pr-draft push-to-origin
+npx musyskills add --all
+```
+
+## Commands
+
+| Command | What it does |
+|---|---|
+| `list` | List the available skills |
+| `add <skill...>` / `add --all` | Install skills, or update ones already installed by musyskills |
+| `remove <skill...>` | Remove skills that musyskills installed |
+| `update` | Update every skill musyskills installed to this CLI's version |
+| `doctor` | Show which tools were detected, where skills are, and their state |
+
+## Options
+
+- `--tool <name>` (`-t`): `claude`, `codex`, `cursor`, or `antigravity`. Repeat it, or separate with commas, for several tools. Without it, musyskills detects tools from the project (`.claude/`, `AGENTS.md`, `.cursor/`, `.gemini/`, and similar). If nothing is found, it asks in an interactive terminal, and otherwise uses `claude`.
+- `--global` (`-g`): install for your user instead of the current project.
+- `--force` (`-f`): overwrite or remove a skill that you edited, or that musyskills did not install.
+
+## Where skills go
+
+| Tool | Project | Global (`--global`) |
+|---|---|---|
+| claude | `.claude/skills/` | `~/.claude/skills/` |
+| codex | `.agents/skills/` | `~/.agents/skills/` |
+| cursor | `.cursor/skills/` | `~/.cursor/skills/` |
+| antigravity | `.agents/skills/` | `~/.gemini/config/skills/` |
+
+musyskills records what it installed in a `.musyskills.json` file in each skills folder. It uses that record to update or remove only its own skills, and it never overwrites a skill you changed unless you pass `--force`.
+
+## License
+
+MIT

package/bin/musyskills.js

@@ -0,0 +1,7 @@
+#!/usr/bin/env node
+import { main, UsageError } from '../src/cli.js';
+
+main(process.argv.slice(2)).catch((err) => {
+  console.error(`musyskills: ${err.message}`);
+  process.exit(err instanceof UsageError ? 2 : 1);
+});

package/package.json

@@ -1,6 +1,40 @@
 {
   "name": "musyskills",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.4.1",
+  "description": "Install Musyskills AI agent skills into Claude Code, Codex, Cursor, and Antigravity.",
+  "type": "module",
+  "bin": {
+    "musyskills": "bin/musyskills.js"
+  },
+  "files": [
+    "bin",
+    "src",
+    "skills"
+  ],
+  "scripts": {
+    "prepack": "node scripts/bundle.mjs",
+    "postpack": "node scripts/bundle.mjs --clean",
+    "test": "node --test"
+  },
+  "engines": {
+    "node": ">=24"
+  },
+  "keywords": [
+    "agent-skills",
+    "claude-code",
+    "codex",
+    "cursor",
+    "antigravity",
+    "skills",
+    "cli"
+  ],
+  "author": "ahmadammarm",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ahmadammarm/musyskills.git",
+    "directory": "packages/cli"
+  },
+  "homepage": "https://github.com/ahmadammarm/musyskills#readme",
+  "bugs": "https://github.com/ahmadammarm/musyskills/issues"
+}

package/skills/apply-review-feedback/SKILL.md

@@ -0,0 +1,85 @@
+---
+name: apply-review-feedback
+description: Implement fixes for existing code review comments or requested changes on a pull request or diff, across any language or framework. Use whenever the user pastes review comments, says "address this feedback," "fix review comments," or references reviewer requests that need to be implemented.
+argument-hint: <review-comment-or-thread>
+---
+
+# apply-review-feedback
+
+## Purpose
+
+Take a set of review comments or requested changes and implement them accurately and traceably in the codebase, without introducing unrelated modifications, regressions, or stylistic drift.
+
+## Trigger
+
+Activate this skill when the user:
+- Pastes one or more reviewer comments (from GitHub, GitLab, Bitbucket, or plain text) and asks to address them.
+- Says "fix the review feedback," "implement requested changes," "address this comment," or similar.
+- References a specific pull request review thread and wants the code changes applied locally.
+
+## Pre-flight Checks
+
+Before touching any file, perform the following checks in order:
+
+1. Run `git status` to confirm the current branch and working-tree state. If there are uncommitted changes unrelated to the review, note them and ask whether to stash or leave them before continuing.
+2. Run `git log --oneline -5` to understand recent commit context and branch name.
+3. Look for project-specific rules files (`.claude/rules`, `.agents/rules`, `.cursor/rules`, `CONTRIBUTING.md`, `.github/CONTRIBUTING.md`, or any similarly named convention file). Read whichever file is found. These rules take full priority over the generic guidance in this skill.
+4. If no project rules file exists, proceed with this skill's defaults below.
+
+## Workflow
+
+Follow these steps sequentially for every batch of review comments provided:
+
+### Step 1: Parse and Catalogue Comments
+- Read all review comments provided by the user.
+- Convert each comment into a discrete, actionable checklist item.
+- Number them in the order they will be addressed.
+- If a comment is ambiguous, contradicts existing logic, or conflicts with another comment, flag it immediately and ask the user for clarification before proceeding. Do not guess at intent.
+
+### Step 2: Map Comments to Files
+- For each checklist item, identify the target file and, if specified, the line or function referenced in the comment.
+- If the comment references code that no longer exists or has moved, flag it and ask the user how to proceed.
+
+### Step 3: Implement Changes
+- Address each comment individually in sequence.
+- Apply the minimal, targeted change that satisfies the comment. Do not refactor, rename, or restructure code beyond what the comment explicitly requests.
+- Preserve the existing code style, indentation, naming conventions, and patterns already present in the file.
+- If a comment requests a fix that would require adding a new dependency or a significant refactor, pause, note the scope impact, and ask the user for approval before continuing.
+- Do not resolve or mark comments as resolved on any review platform; only apply the local code change.
+
+### Step 4: Validate Changes
+- After all changes are applied, run `git diff` to confirm only the expected lines were modified.
+- If the project includes a test runner or linter in its configuration (`package.json`, `Makefile`, `pyproject.toml`, etc.), run the relevant command to verify no tests or lint rules are broken.
+- If tests break, diagnose the root cause and fix only what the review comment necessitated. Do not silently suppress or skip tests.
+
+### Step 5: Summarize
+- Produce a clear, traceable summary mapping each original comment to the specific change made.
+- Include the file name, the lines changed, and a one-sentence description of what was done.
+- List any comments that were left unresolved and the reason (ambiguity, scope concern, awaiting user input).
+
+## Rules
+
+- Address each comment individually and traceably. Do not bundle unrelated fixes into a single change.
+- Project rules files found during Pre-flight Checks take full priority over this skill's defaults. Apply them wherever they conflict.
+- If any comment is ambiguous or conflicts with existing code patterns, stop and ask rather than making an assumption.
+- Do not introduce new dependencies, abstract new utilities, or perform structural refactors beyond the explicit scope of the review comment.
+- Do not modify files unrelated to the review comments, even if improvements are noticed.
+- Preserve all existing comments, docstrings, and documentation in modified files unless the review comment specifically targets them.
+- Do not force-push or amend commits. Only apply file changes locally.
+
+## Edge Cases
+
+- If the user provides review comments for a file that does not exist in the current branch, state this clearly and ask whether the file was deleted or if the wrong branch is checked out.
+- If the same line is targeted by two conflicting comments, present both to the user and wait for a decision before applying either.
+- If the project has a CI/CD configuration (`.github/workflows`, `Jenkinsfile`, `.gitlab-ci.yml`), do not modify it unless the review comment explicitly targets it.
+
+## Output Format
+
+Deliver the result as a checklist summary containing:
+
+1. **Review Comment** — the original reviewer text (or a short quote).
+2. **File Changed** — the file path relative to the repo root.
+3. **Lines Affected** — the line range that was modified.
+4. **Action Taken** — a one-sentence description of the change made.
+5. **Rules Source** — whether project-specific rules or this skill's defaults governed the change.
+6. **Unresolved Comments** — any items not addressed and the explicit reason why.

package/skills/code-changes-review/SKILL.md

@@ -0,0 +1,102 @@
+---
+name: code-changes-review
+description: Review modified or staged code for correctness, security, readability, DRY-ness, performance, and overall best practices, regardless of language or framework. Use whenever the user asks to review code, review a diff, review changes, or check code before committing/merging.
+argument-hint: <branch-or-file-to-review>
+---
+
+# code-changes-review
+
+## Purpose
+
+Provide a thorough, objective, and actionable review of code changes in the current repository. The goal is to catch bugs, design issues, security risks, duplication, and readability or performance problems before code is committed or merged, ensuring only well-reasoned changes reach the main branch.
+
+## Trigger
+
+Activate this skill when the user:
+- Asks to "review my code," "review this diff," "check my changes," "look at what I wrote," or similar.
+- Is preparing to commit, push, or open a pull request and wants structured feedback first.
+- Wants a quality gate check before sharing code with teammates or deploying.
+
+## Pre-flight Checks
+
+Before reviewing any code, perform the following in order:
+
+1. Run `git status` to identify all modified, added, deleted, and renamed files.
+2. If `git status` shows no changes, state this clearly and ask the user what they would like reviewed instead. Do not proceed to generate a review file.
+3. Run `git diff` to see unstaged changes and `git diff --staged` to see staged changes. Capture both.
+4. Look for project-specific rules or coding conventions in files such as `.claude/rules`, `.agents/rules`, `.cursor/rules`, `CONTRIBUTING.md`, `.github/CONTRIBUTING.md`, style guide documents, or `eslint`/`pylint`/`rubocop` configuration files. Read whichever is found. These take full priority over this skill's generic guidance wherever they conflict.
+
+## Workflow
+
+### Step 1: Understand Context
+- Read each changed file in its full context, not just the diff hunk. Understanding surrounding logic is essential for catching issues that span multiple lines or functions.
+- Identify the apparent purpose of the change (bug fix, new feature, refactor, configuration update, etc.) to calibrate the review accordingly.
+
+### Step 2: Evaluate Each Change
+
+Assess every changed file against the following dimensions:
+
+**Correctness and Logic**
+- Are there logic errors, off-by-one errors, or incorrect conditionals?
+- Are all edge cases handled (null/undefined values, empty collections, boundary inputs)?
+- Is error handling present and appropriate? Are exceptions caught at the right level?
+
+**Security**
+- Is any user input passed to a database query, shell command, file path, or external service without validation or sanitization?
+- Are secrets, API keys, or credentials present in the diff?
+- Are authentication and authorization checks applied correctly?
+- Are dependencies introduced by this change up-to-date and free of known vulnerabilities?
+
+**Readability**
+- Are variable, function, and class names clear and descriptive?
+- Are functions small and focused on a single responsibility?
+- Is the nesting depth and cyclomatic complexity reasonable?
+- Is self-explanatory logic preferred over clever or cryptic constructs?
+
+**DRY (Don't Repeat Yourself)**
+- Is any logic, string, or value duplicated across the diff when it could be extracted or reused?
+- Are there copy-pasted blocks or magic values that should be constants or utilities?
+
+**Performance**
+- Are there unnecessary loops, redundant computations, or N+1 query patterns?
+- Are expensive operations performed inside loops when they could be hoisted or memoized?
+- Are there obvious algorithmic inefficiencies given the scale at which this code is expected to run?
+
+**Best Practices**
+- Does the code use the language and framework idiomatically?
+- Are resources (file handles, database connections, HTTP sessions) properly opened and closed?
+- Is the change consistent with the existing patterns and conventions in the repository?
+- Do project-specific rules from Step Pre-flight Check 4 apply, and are they satisfied?
+
+### Step 3: Classify Findings
+
+Group every finding into one of three categories:
+
+- **Critical**: Bugs, security risks, incorrect logic, or correctness problems that should block merging. Each finding must include a concrete, implementable fix suggestion.
+- **Suggestion**: Readability, DRY, performance, and best-practice improvements. These are recommended but do not block merging. Each must include a specific, actionable fix.
+- **Info**: Observations, neutral context, or minor notes that require no action from the author.
+
+### Step 4: Write the Review File
+
+- Format the review as a markdown file following the output structure below.
+- Name the file `code-review-<YYYY-MM-DD>.md` or `code-review-<branch-name>.md`.
+- Write it to the project root or a `reviews/` directory if one exists.
+- Present the file path to the user after writing.
+
+## Rules
+
+- Never assume a specific language, framework, or project structure. Infer everything from the repository itself.
+- Project rules files discovered in Pre-flight Checks take full priority over this skill's generic guidance wherever they conflict.
+- Do not rewrite or refactor code unless explicitly asked. Describe the issue and provide a concrete suggested fix.
+- Every Critical and Suggestion finding must cite the file name and line number and include a specific, implementable fix, not a vague "consider improving this."
+- Categorize missing or inadequate tests and DRY violations as Suggestion, not Critical, unless they directly cause a correctness or security risk.
+- If `git status` shows no changes, state that clearly and do not generate a file.
+
+## Output Format
+
+A markdown file structured as follows:
+
+1. **Summary** — Files reviewed, total findings per category (Critical / Suggestion / Info), and a one-line overall verdict (e.g., "Ready to merge" or "Needs fixes before merging").
+2. **Critical Findings** — For each finding: file path, line(s), description of the issue, and a concrete fix suggestion.
+3. **Suggestions** — For each finding: file path, line(s), category tag (Readability / DRY / Performance / Best Practice), description of the improvement opportunity, and a concrete fix suggestion.
+4. **Info** — For each finding: file path, line(s), and a short contextual note. No fix required.

package/skills/explain-changes/SKILL.md

@@ -0,0 +1,83 @@
+---
+name: explain-changes
+description: Summarize and explain the current uncommitted or unpushed code changes in a repository, in plain language, regardless of language or framework. Use whenever the user asks "what did I change," "explain my changes," "summarize this diff," or wants a recap before writing a commit message or PR description.
+argument-hint: <branch-or-scope-to-explain>
+---
+
+# explain-changes
+
+## Purpose
+
+Give a clear, accurate, and human-readable explanation of what changed in the codebase and why it likely matters. The goal is to help the developer understand the full scope of their own modifications without needing to re-read the raw diff themselves, which is particularly useful before writing a commit message, PR description, or changelog entry.
+
+## Trigger
+
+Activate this skill when the user:
+- Asks to "explain my changes," "summarize what I did," "what did I change," or "recap this diff."
+- Wants context or a summary before writing a commit message or PR description.
+- Wants to verify the scope of their modifications before staging or pushing.
+- Asks for a changelog entry or release note based on the current diff.
+
+## Pre-flight Checks
+
+Before producing any explanation, perform the following in order:
+
+1. Run `git status` to identify all modified, added, deleted, and renamed files in both the working tree and the staging area.
+2. If `git status` shows no changes, state this clearly and do not generate an explanation file. Ask the user if they want to review a specific commit or branch instead.
+3. Run `git diff` to capture unstaged changes and `git diff --staged` to capture staged changes. Use both to form a complete picture.
+4. Run `git log --oneline -10` to understand recent commit history and the current branch, which provides context for inferring the intent behind the changes.
+
+## Workflow
+
+### Step 1: Group Changes Logically
+- Do not list files in raw alphabetical or `git status` order.
+- Group changes by their logical relationship: related feature files together, configuration changes separately, test files adjacent to the code they test, documentation changes as their own group.
+- Common groupings include: core feature/logic changes, API or route changes, database or schema changes, configuration or environment changes, test additions or updates, and documentation or comment updates.
+
+### Step 2: Explain Each Group
+For each logical group, provide:
+- **What changed**: a plain-language description of the modifications (e.g., "Added a new `validateEmail` function to the utilities module").
+- **Why it likely changed**: the inferred purpose based on what the code does (e.g., "This appears to centralize email validation that was previously duplicated across three files"). Only state what the code reasonably supports. Do not speculate beyond what is evident.
+- **Impact**: whether the change is additive, a bug fix, a breaking change, a performance improvement, or a refactor. Note any changes to public interfaces, API contracts, or database schemas explicitly, as these carry downstream risk.
+
+### Step 3: Flag Unrelated or Suspicious Files
+- Identify any files in the diff that appear unrelated to the main body of change.
+- Common examples: a configuration file changed alongside a feature, a seemingly unrelated test file modified, or a lock file updated.
+- Surface these explicitly so the user can verify they were intentional before committing.
+
+### Step 4: Note Side Effects
+- Identify and call out any notable side effects of the changes:
+  - New packages or dependencies introduced.
+  - Environment variable additions or changes.
+  - Database migration files created or modified.
+  - Breaking changes to public APIs or exported interfaces.
+  - Changes to CI/CD configuration or deployment scripts.
+
+### Step 5: Confirm Output Location
+- Before writing the output file, ask the user which directory they would like it saved to.
+- Do not assume a default location or silently write to a directory without confirmation.
+- Name the file `changes-explanation-<YYYY-MM-DD>.md` or `changes-explanation-<branch-name>.md` based on the context.
+
+### Step 6: Write the Explanation File
+- Write the full explanation to a markdown file in the confirmed directory.
+- Present the file path to the user after writing.
+- Do not modify any source files. This skill is read-only with respect to the project's actual code.
+
+## Rules
+
+- Do not speculate about intent beyond what the code reasonably supports. When the purpose is unclear, state the uncertainty explicitly rather than fabricating a plausible-sounding explanation.
+- Keep the summary in plain language. Avoid restating the diff line by line or using excessive technical jargon.
+- Do not modify any source file, staged file, or git history. This skill only reads code and writes the explanation document.
+- Always confirm the target directory with the user before writing the output file. Never guess or silently default to a location.
+- If `git status` shows no changes, state that clearly and stop. Do not generate a file with empty or fabricated content.
+- Do not include sensitive information (secrets, credentials, personally identifiable data) in the explanation file, even if it appears in the diff.
+
+## Output Format
+
+A markdown file with the following sections, in order:
+
+1. **Summary** — A single paragraph giving an overall description of what the changes accomplish and their general purpose.
+2. **Changes by Area** — Grouped by logical area, each group containing: what changed, why it likely changed, and the impact on the system.
+3. **Notable Side Effects** — New dependencies, environment variable changes, schema changes, breaking API changes, or CI/CD modifications. Omit this section if none exist.
+4. **Files to Double-Check** — Files that appear unrelated to the main change and warrant a second look before committing. Omit this section if all files appear intentional.
+5. **Full File List** — A complete list of modified, added, deleted, and renamed files as reported by `git status`.

package/skills/pr-draft/SKILL.md

@@ -0,0 +1,80 @@
+---
+name: pr-draft
+description: Prepare or update a pull request title and description for the current branch's changes, reusing existing PR content whenever available, across any language, framework, or Git hosting platform. Use whenever the user asks to create a PR, open a pull request, write a PR description, or update an existing PR.
+argument-hint: <pr-title-or-context>
+---
+
+# pr-draft
+
+## Purpose
+
+Produce or update a well-structured pull request title and description that accurately reflects the current code changes. When an existing PR description is available, make targeted, incremental edits rather than rewriting it wholesale. The output should be immediately usable by the author with minimal edits.
+
+## Trigger
+
+Activate this skill when the user:
+- Asks to "create a PR," "open a pull request," "write a PR description," or "draft a PR."
+- Asks to update or refresh an existing PR title or description.
+- Wants to prepare a PR message before pushing or using the platform UI.
+
+## Pre-flight Checks
+
+Before writing any PR content, perform the following in order:
+
+1. Run `git status` to confirm there is a working branch and understand the current state of the working tree.
+2. Run `git log --oneline origin/main..HEAD` (or `origin/master..HEAD` if `main` does not exist) to see all commits that are unique to this branch. If there are no commits ahead of the base branch, state this clearly and stop.
+3. Run `git diff origin/main...HEAD` (three-dot diff) to capture the full content diff between this branch and the base.
+4. Check for a PR template in the repository. Common locations include `.github/PULL_REQUEST_TEMPLATE.md`, `.github/PULL_REQUEST_TEMPLATE/`, `docs/PULL_REQUEST_TEMPLATE.md`, or `PULL_REQUEST_TEMPLATE.md` in the root. If found, read it and use its structure as the required format for the description.
+5. Check if the user has provided an existing PR title and description (pasted text or a file path). If so, treat it as the base to update rather than starting fresh.
+
+## Workflow
+
+### Step 1: Analyze the Changes
+- Read the commit log from Step 2 to understand the scope and intent of the branch.
+- Read the full diff from Step 3 to understand the specific modifications made to the codebase.
+- Identify the primary type of change: new feature, bug fix, refactor, performance improvement, documentation update, dependency upgrade, or configuration change. A PR may span multiple types.
+
+### Step 2: Draft or Update the Title
+- The title must be concise (ideally under 72 characters), written in the imperative mood, and accurately describe the primary change.
+- Good examples: "Add email validation to the registration flow" or "Fix race condition in the session refresh handler."
+- Avoid vague titles like "Updates" or "Fix bug." Be specific enough that a reviewer understands the scope without reading the full description.
+- If an existing title is provided and still accurately reflects the change, keep it. Only update if the new commits have changed the scope or intent.
+
+### Step 3: Draft or Update the Description
+- If a PR template was found in Step 4, fill in every section of that template. Do not omit sections unless the template itself marks them as optional.
+- If no template exists, use the default structure defined in the Output Format section below.
+- If an existing PR description was provided, update only the sections affected by new commits. Preserve all other sections exactly as they are. Do not rewrite unaffected content.
+- Do not fabricate testing steps, context, or motivation that is not directly evidenced by the code or explicitly provided by the user.
+- If the diff includes a migration, schema change, or breaking API change, ensure this is prominently noted in the description under a dedicated section.
+
+### Step 4: Review CI/CD Context
+- Check for a CI/CD configuration file (`.github/workflows/`, `Jenkinsfile`, `.gitlab-ci.yml`, `.circleci/config.yml`). If one exists, note whether the PR changes affect the build or deployment pipeline and include a brief note in the PR description if so.
+
+### Step 5: Present the Output
+- Present the drafted title and description clearly, separated from each other.
+- If this is an update to an existing PR, explicitly state which sections were changed and which were preserved.
+- Mark the output as "New PR Draft" or "Updated PR Description (changes from existing)" so the author knows at a glance what to expect.
+- Ask the user if they would like any sections adjusted before they submit.
+
+## Rules
+
+- Never discard an existing PR title or description wholesale. Always make targeted, incremental edits when a base exists.
+- Match the repository's PR template structure exactly if one exists. The template's headings and section order are required, not optional.
+- Do not fabricate testing steps, screenshots, issue references, or context that is not evidenced by the code changes or user-provided input.
+- Keep the title concise and the description scannable. Use short sections, bullet points, and clear headings. Avoid writing paragraphs of dense prose where structured lists would be clearer.
+- If the branch has no commits ahead of the base branch, state this clearly and do not generate a PR description.
+- Do not push, create, or update PRs on any platform automatically. The output of this skill is a draft text only.
+
+## Output Format
+
+When no PR template is found, use the following default structure:
+
+**Title**: A concise, imperative summary of the change.
+
+**Description**:
+1. **Summary** — A 2-4 sentence explanation of what this PR does and why.
+2. **Changes Made** — A bullet list of the specific modifications, organized by file or area.
+3. **Type of Change** — Checkboxes or a list indicating: Bug Fix / New Feature / Refactor / Performance / Documentation / Dependency Update / Breaking Change.
+4. **Testing Notes** — How the change was tested, or a note if testing is not applicable. Do not invent steps; only include what is evident.
+5. **Breaking Changes** — If applicable, describe what breaks and what consumers of this code need to do. Omit if no breaking changes.
+6. **Related Issues** — Links to relevant issues or tickets if provided by the user. Omit if none.

package/skills/prd-generator/SKILL.md

@@ -0,0 +1,83 @@
+---
+name: prd-generator
+description: Generate a structured Product Requirements Document (PRD) by interviewing the user about a new feature or product idea, and save the result as a markdown file. Use whenever the user asks to write a PRD or define product requirements.
+argument-hint: <feature-idea-or-topic>
+---
+
+# prd-generator
+
+## Purpose
+
+To systematically interview the user to extract all necessary product requirements for a new feature or product, and structure that information into a comprehensive Markdown Product Requirements Document (PRD). The goal is to ensure that development does not begin until the scope, user stories, and technical constraints are well-defined and agreed upon.
+
+## Trigger
+
+Activate this skill when the user:
+- Asks to "write a PRD," "create a product requirements document," or "draft a PRD."
+- Uses the explicit slash command `/prd-generator`.
+- Asks to define, specify, or formalize a new feature's requirements before coding.
+
+## Pre-flight Checks
+
+Before beginning the interview process, the agent must:
+1. Search the workspace for a PRD template (e.g., `docs/PRD_TEMPLATE.md` or `.github/PRD_TEMPLATE.md`). If found, use its structure as the target format.
+2. Check if the user has provided an existing partial PRD, notes, or an issue ticket. If so, treat those as the base requirements and identify which sections are missing.
+3. Check if there is an existing `docs/` folder in the project. If not, note that one may need to be created.
+
+## Workflow
+
+### Step 1: Initial Discovery
+- If the user hasn't provided a specific feature idea, ask them for one.
+- Ask clarifying questions to understand:
+  - The primary problem being solved (the "Why").
+  - The target audience and personas (who will use this feature).
+  - Any known technical or business constraints.
+- *Tip:* Use interactive questions (e.g., the `ask_question` tool) or present a small, focused list of questions in the chat. Do not overwhelm the user with a massive questionnaire.
+
+### Step 2: Define Scope & Stories
+- Based on the initial discovery, propose a discrete list of "In Scope" and "Out of Scope" (Non-Goals) items. This is crucial for preventing feature creep.
+- Draft 3-5 core User Stories with basic Acceptance Criteria, following the format: *"As a [persona], I want to [action] so that [benefit]."*
+- Ask the user to review, modify, or confirm the scope and user stories before proceeding to the full draft.
+
+### Step 3: Draft the PRD
+- Once the user confirms the scope and stories, generate the full PRD according to the **Output Format** defined below.
+- Flesh out the remaining sections (Technical Considerations, UX/Design, Risks, and Success Metrics) based on best practices, standard patterns, and the context gathered in steps 1 and 2.
+
+### Step 4: Save and Present
+- Write the final PRD to a Markdown file in the project's documentation folder (e.g., `docs/PRD-[feature-name].md`).
+- If the user named a location, save the file there.
+- Otherwise, if a `docs/` folder does not exist, create it and save the file there. Tell the user the path so they can move it if they prefer another location.
+- Inform the user that the file has been created, provide a direct link to it, and ask if any sections need further refinement.
+
+## Rules
+
+- **No hallucinated requirements:** Never generate an entire PRD from a single vague sentence without first confirming the scope and user stories with the user. The interview phase is mandatory.
+- **Pacing:** Group questions logically and proceed conversationally. Do not dump all questions at once.
+- **Save to a file:** The final PRD MUST be saved as an actual `.md` file in the project. Do not just print the entire PRD in the chat response, as this pollutes the context window.
+- **Strict adherence to structure:** The final PRD must contain all sections listed in the Output Format. If a section is not applicable, include the heading and write "N/A" with a brief reason.
+
+## Output Format
+
+If a repository template is found in Pre-flight checks, use it exactly. Otherwise, the generated PRD must be formatted in Markdown and include the following sections exactly:
+
+1. **Title & Meta Information**
+   - Project/Feature Name, Author, Status (Draft/In Review/Approved), Date, Target Release.
+2. **Overview & Problem Statement**
+   - **What:** High-level summary of the feature.
+   - **Why:** The specific problem this solves.
+3. **Target Audience & Personas**
+   - Who will use this feature and what are their specific needs.
+4. **Goals & Non-Goals**
+   - **In Scope:** What is being built.
+   - **Out of Scope (Non-Goals):** What is explicitly NOT being built.
+5. **User Stories & Functional Requirements**
+   - Format: *"As a [persona], I want to [action] so that [benefit]."*
+   - Acceptance Criteria for each story (bulleted list defining when the story is "done").
+6. **User Experience (UX) & Design**
+   - Core user flows, key interactions, or references to wireframes.
+7. **Technical Considerations**
+   - High-level architecture, required API endpoints, database schema changes, etc.
+8. **Dependencies, Risks & Mitigations**
+   - Blockers, security considerations, dependencies on other systems, and mitigations.
+9. **Success Metrics**
+   - Quantifiable metrics to measure the feature's success (e.g., adoption rate, performance metrics).

package/skills/project-explanation/SKILL.md

@@ -0,0 +1,125 @@
+---
+name: project-explanation
+description: Understand a project comprehensively and explain it clearly to the user. Then (unless the user asks for no questions) ask which feature the user wants to develop, explain that feature in depth, and confirm whether the user wants to proceed with development. Trigger when the user asks to understand, explore, summarize, or explain a codebase/project, or asks "what features does this project have" or "help me understand this project".
+argument-hint: <project-name-or-feature>
+---
+
+# project-explanation
+
+## Purpose
+
+Deeply understand a project's structure, architecture, and features, then explain it clearly in plain language. After summarizing the project, guide the user interactively to select a feature for deeper exploration and, optionally, active development.
+
+## Trigger
+
+Activate this skill when the user:
+- Runs the slash command `/project-explanation`.
+- Asks to "understand this project," "explain this codebase," "give me a project overview," or similar.
+- Asks "what does this project do," "what features exist," or "help me get up to speed on this repo."
+- Wants an onboarding overview before deciding what to build or improve next.
+
+## Interaction Mode
+
+Determine the mode before starting:
+
+- **Interactive (default)**: Pause at the two decision points (feature selection and development confirmation) and wait for the user's answer.
+- **Non-interactive**: Use this mode when the user's request or the skill arguments ask for no questions (e.g., "no questions," "make no questions," "don't ask," "just summarize"). Do not ask the user anything and do not wait for input. Instead:
+  - End Step 4 with a **Recommended Next Step** section in place of the feature-selection question: name one or two features or improvements worth developing first and give a one-sentence reason for each, based on evidence from the code.
+  - Stop after Step 4. Do not perform the deep-dive or produce an implementation plan unless the user asks for one in a later message.
+
+## Pre-flight Checks
+
+Before exploring the project, perform the following in order:
+
+1. Run `git status` to confirm the current branch and working-tree state.
+2. List the root directory structure to understand the top-level layout and identify what type of project this is.
+3. Read the `README.md` (or `readme.md`, `README.rst`, `docs/index.md`) if one exists. This is the primary source of intent and feature documentation.
+4. Read configuration files relevant to the project type, such as:
+   - `package.json` / `package-lock.json` for JavaScript/TypeScript projects.
+   - `pyproject.toml` / `requirements.txt` for Python projects.
+   - `Gemfile` for Ruby projects.
+   - `go.mod` for Go projects.
+   - `Cargo.toml` for Rust projects.
+   - `.env.example` for environment variable requirements.
+   - `docker-compose.yml` / `Dockerfile` for containerized deployments.
+5. Identify the primary directories and their likely responsibilities (e.g., `src/`, `app/`, `api/`, `components/`, `services/`, `models/`, `tests/`, `scripts/`, `docs/`).
+
+## Workflow
+
+### Step 1: Identify the Tech Stack
+- Determine the primary programming language(s) from file extensions and configuration files.
+- Identify the main framework (e.g., Next.js, Django, Rails, Spring Boot, Express, FastAPI) from dependencies or configuration.
+- Identify the database layer if evident (SQL, MongoDB, Redis, etc.).
+- Identify the deployment or infrastructure approach (Docker, Kubernetes, serverless, etc.) if present.
+- Note any significant external integrations (third-party APIs, authentication providers, payment systems).
+
+### Step 2: Identify the Architecture Pattern
+- Determine the overall architectural approach from the directory structure and code organization:
+  - Frontend-only (SPA, static site)
+  - Backend-only (API server, CLI tool, library)
+  - Full-stack monolith
+  - Full-stack monorepo with separate frontend and backend packages
+  - Microservices
+- Identify key architectural layers present (e.g., controllers/routes, services/use-cases, repositories/data access, models/entities, middleware, utilities).
+
+### Step 3: Map the Features
+- Read key source files and entry points (e.g., `main.ts`, `app.py`, `index.js`, route definitions, page components) to enumerate distinct features.
+- A feature is any self-contained piece of user-facing or system-level functionality (e.g., user authentication, dashboard, report generation, background jobs, API endpoints, notification system).
+- List every feature identified with a brief one-line description.
+
+### Step 4: Present the Comprehensive Summary
+Present the findings to the user in the following structure:
+- **Project Name and Purpose** — what the project is and who it is for.
+- **Tech Stack** — languages, frameworks, databases, and key integrations.
+- **Architecture** — the overall pattern and how the main layers are organized.
+- **Features** — a numbered list of all identified features with one-line descriptions.
+- **Key Entry Points** — the main files a developer would start reading to understand the system.
+
+After presenting the summary, ask the user:
+
+> "From the features above, which one would you like to explore further?"
+
+Wait for the user's response before continuing. Do not proceed to the next step without a selection.
+
+In non-interactive mode, replace the question with the **Recommended Next Step** section described under Interaction Mode, then stop.
+
+### Step 5: Deep-Dive on the Selected Feature
+Once the user selects a feature:
+- Read all files directly related to that feature (routes, controllers, services, models, components, tests).
+- Explain how the feature currently works end-to-end: the entry point, data flow, business logic, data persistence, and any output or response.
+- List every file that contributes to this feature and describe each file's role.
+- Identify the dependencies this feature has on other parts of the system.
+- Identify any limitations, known edge cases, missing tests, or improvement opportunities observable from the code.
+
+After the detailed explanation, ask the user:
+
+> "Would you like to proceed with developing or improving this feature now?"
+
+Wait for the user's response before continuing.
+
+### Step 6: Plan or Conclude
+- If the user says **yes**, provide a concrete implementation plan:
+  - The specific files that need to be created or modified.
+  - A step-by-step technical approach.
+  - An estimated complexity level (low / medium / high) and a rationale.
+  - Any risks or prerequisites to address first.
+- If the user says **no**, offer to return to the full feature list from Step 4 or to end the exploration session.
+
+## Rules
+
+- In interactive mode, always wait for the user's explicit response at the two decision points (feature selection and development confirmation) before continuing.
+- In non-interactive mode, never ask a question or wait for input; end with the Recommended Next Step section after Step 4.
+- Use plain, accessible language. Assume the user may be new to this codebase; provide enough context to be useful without overwhelming them with jargon.
+- Do not modify any source files during this skill. It is read-only with respect to the codebase.
+- If the repository has no README and minimal configuration, state this honestly and note that the exploration will rely on reading source files directly.
+- Do not fabricate features or behaviors not evidenced by the code or documentation.
+
+## Output Format
+
+Deliver the output in up to three phases:
+
+**Phase 1 (Steps 1-4)**: A structured project summary presented inline, followed by the interactive feature-selection question. In non-interactive mode, the summary is followed by the Recommended Next Step section and the output ends here.
+
+**Phase 2 (Step 5)**: A detailed feature breakdown presented inline, including files, data flow, dependencies, and improvement opportunities, followed by the development confirmation question.
+
+**Phase 3 (Step 6, if yes)**: An implementation plan with specific files, steps, complexity estimate, and any identified risks or prerequisites.

package/skills/push-to-origin/SKILL.md

@@ -0,0 +1,101 @@
+---
+name: push-to-origin
+description: Reviews uncommitted changes, excludes files that shouldn't be committed, creates a well-formed commit, and pushes to origin (in its branch, no other branch). Runs git commands directly; no helper agent is required. ALWAYS confirms with the user before pushing — never pushes silently. Triggers on any request to commit, save, check in, or push changes — e.g. "commit my changes", "check this in", "save to git", "push to origin" — even without the word "push" or a commit message.
+argument-hint: <commit-message>
+---
+
+# push-to-origin
+
+## Purpose
+
+Safely and reliably bundle local code changes into a well-formed commit and push to the appropriate remote branch. This skill enforces a mandatory confirmation step before any push occurs, prevents common dangerous operations, and ensures internal or ignored files are never accidentally committed.
+
+## Trigger
+
+Activate this skill when the user:
+- Says "commit my changes," "save to git," "check this in," "push to origin," "push my work," or any similar phrase.
+- Requests a commit even without providing a commit message; draft one from the diff if needed.
+- Asks to "save" or "check in" their current work, even without explicitly mentioning git.
+
+## Pre-flight Checks
+
+Before staging or committing anything, perform the following in order:
+
+1. Run `git status` to identify the current branch, all modified files, and any untracked files.
+2. Run `git remote -v` to confirm an `origin` remote exists. If no `origin` remote is configured, stop and tell the user. Do not proceed.
+3. Run `git diff --stat` to get a summary of the scope of changes.
+4. Check for a CI/CD configuration file (`.github/workflows/`, `Jenkinsfile`, `.gitlab-ci.yml`, `.circleci/config.yml`) to determine whether a required commit message format exists (e.g., Conventional Commits). If one is found, read it and apply the format.
+
+## Exclusion List
+
+The following files and patterns must never be staged or committed, regardless of whether they appear in `git status`. If they were accidentally staged, unstage them before proceeding:
+
+- `.geminiignore`
+- `.antigravityignore`
+- `GEMINI.md`
+- `pr-description.md`
+- Any file matching patterns defined in `.gitignore`, `.geminiignore`, or `.antigravityignore`.
+- Any file path under `.agents/` or `.gemini/` that contains internal skill or configuration files.
+- Personal, machine-local agent files: `CLAUDE.local.md`, `.claude/settings.local.json`, and any other `*.local.*` file inside an agent configuration folder (`.claude/`, `.cursor/`, `.gemini/`, `.agents/`).
+- Any file containing secrets, credentials, or API keys (check for patterns like `*_SECRET`, `*_KEY`, `*_TOKEN` in file names or content, and flag them).
+
+If a file on the exclusion list is staged, unstage it immediately and notify the user before continuing.
+
+Shared agent files are not excluded. `CLAUDE.md`, `AGENTS.md`, `.claude/skills/`, `.claude/settings.json`, and `.cursor/rules/` are meant to be shared with the team, so commit them normally if they are part of the change, unless a rule above (such as a secret in the content) applies.
+
+## Workflow
+
+### Step 1: Gather and Filter
+- Run `git status` to get the full list of modified and untracked files.
+- Cross-reference every file against the Exclusion List above. Unstage any excluded files that are already staged.
+- Present the final, filtered list of files that will be staged to the user, so they can verify the scope before committing.
+
+### Step 2: Draft the Commit Message
+- If the user provided a commit message, check whether it complies with the format required by the CI/CD configuration (if found in Pre-flight Check 4). If it does not comply, propose a corrected version and ask the user to approve it. Do not silently rewrite it.
+- If no commit message was provided, run `git diff HEAD` to read the changes and draft a message that accurately describes the intent.
+  - Follow Conventional Commits format if required by the project: `<type>(<scope>): <description>` (e.g., `feat(auth): add email verification step`).
+  - Otherwise, write a clear imperative-mood summary (e.g., "Refactor session handling to use Redis").
+- Present the drafted commit message to the user and ask for explicit approval before proceeding. Do not commit without approval.
+
+### Step 3: Commit
+- Once the commit message is approved, stage the filtered files from Step 1.
+- Run `git commit -m "<approved-message>"`.
+- Confirm the commit was created successfully by running `git log --oneline -1`.
+
+### Step 4: Mandatory Push Confirmation
+Before pushing, display the following information to the user and ask for explicit confirmation:
+
+- The target remote and branch: `origin/<branch-name>`.
+- Whether this push will create a new upstream branch (if no upstream is set for the current branch).
+- A brief summary of the commit being pushed (message and files affected).
+- A prominent warning if the current branch is `main` or `master`.
+
+Do not push under any circumstance until the user explicitly says yes. If the user declines, leave the commit local, inform the user their changes are committed but not pushed, and stop.
+
+### Step 5: Push
+- If the branch has no upstream set, run `git push -u origin <branch-name>`.
+- If an upstream already exists, run `git push`.
+- If the push is rejected (e.g., due to a diverged history or protected branch rules), capture the exact error message, report it to the user, and ask how they would like to proceed (e.g., rebase, merge, or leave as-is). Do not attempt to auto-resolve the conflict.
+
+### Step 6: Report Result
+- If the push succeeds, confirm the result with the remote URL and branch name.
+- If the push fails, report the exact error message and stop. Do not retry automatically.
+
+## Rules
+
+- Confirmation before pushing is mandatory, every single time, without exception. Never push silently.
+- Never use `--force` or `--force-with-lease`. Force-pushing is prohibited.
+- Never amend commits (`--amend`) or rebase history as part of this skill.
+- Never push directly to `main` or `master` without the Step 4 warning being displayed and the user explicitly acknowledging it.
+- Never commit or push any file from the Exclusion List.
+- If a commit message format is required by the project's CI/CD configuration, propose a fix rather than silently rewriting the user's message.
+- If `git remote -v` shows no `origin` remote, stop immediately and tell the user.
+
+## Output Format
+
+At the end of the workflow, report:
+
+1. **Staged Files** — the list of files included in the commit.
+2. **Commit** — the commit hash (short) and the approved message.
+3. **Push Result** — success confirmation with remote URL and branch, or the exact error message if the push failed.
+4. **Excluded Files** — any files that were unstaged due to the Exclusion List, with a note explaining why each was excluded.

package/skills/release/SKILL.md

@@ -0,0 +1,84 @@
+---
+name: release
+description: Cut a new release from the changes recorded under [Unreleased] in CHANGELOG.md. Picks the Semantic Versioning bump, moves the changelog entries into a dated version section, syncs version files, creates the release commit and an annotated tag, pushes after confirmation, and publishes release notes. Use whenever the user asks to "make a release," "cut a release," "bump the version," "tag a new version," or "publish vX.Y.Z."
+argument-hint: <version-or-bump-type>
+---
+
+# release
+
+## Purpose
+
+Turn the work already recorded in the changelog into a published, tagged release in a predictable way. The skill decides the version from what actually changed, keeps the changelog and version files consistent, and never pushes or publishes without explicit confirmation.
+
+## Trigger
+
+Activate this skill when the user:
+- Runs the slash command `/release`.
+- Says "make a release," "cut a release," "release this," "bump the version," "tag a new version," or "publish v1.4.0."
+- Passes a version (`v1.4.0`) or a bump type (`patch`, `minor`, `major`) as an argument.
+
+## Pre-flight Checks
+
+Before changing anything, perform the following in order:
+
+1. Run `git status`. If there are uncommitted changes, stop and ask the user to commit or stash them first. A release must contain only committed work.
+2. Confirm the current branch is the release branch (`main` or `master`, or the branch named in a release guide such as `RELEASING.md` or `CONTRIBUTING.md`). If it is not, stop and tell the user.
+3. Run `git fetch origin` and compare with the upstream. If the local branch is behind, stop and ask the user to pull first.
+4. Read `CHANGELOG.md`. If it does not exist, or the `[Unreleased]` section is empty, stop and tell the user there is nothing to release.
+5. Find the latest version from `git tag --list --sort=-v:refname` and from the newest dated section in the changelog. If they disagree, report both and ask which one is correct.
+6. Look for a validation or test command (for example `scripts/validate.mjs`, `npm test`, `make test`) and run it. If it fails, stop and report the failure.
+7. List the files that carry a version number (for example `package.json`, `.claude-plugin/plugin.json`, `pyproject.toml`, `Cargo.toml`). These must be updated to the new version.
+
+## Workflow
+
+### Step 1: Choose the Version
+- If the user gave an explicit version, use it, but warn if it does not match the rules below.
+- Otherwise, derive the bump from the `[Unreleased]` entries using Semantic Versioning:
+  - **MAJOR**: any change that breaks existing usage, such as a removed or renamed skill, command, or API, a required format change, or anything listed under "Removed" or marked as breaking.
+  - **MINOR**: new capabilities with existing usage still working, such as anything under "Added".
+  - **PATCH**: only fixes, under "Fixed" or "Security", with no new capability.
+  - Internal-only changes (CI, tooling, docs) do not raise the bump above PATCH on their own.
+- The largest change in the release decides the bump.
+- Present the proposed version and the reason in one or two sentences, then ask the user to confirm.
+
+### Step 2: Update the Changelog and Version Files
+- Insert a new `## [vX.Y.Z] - YYYY-MM-DD` heading directly under `## [Unreleased]`, so the existing entries move into the new version and `[Unreleased]` is left empty. Use today's date and match the heading style already used in the file (with or without the `v` prefix).
+- Update every version file found in Pre-flight Check 7 to the new version.
+- Run the validation or test command again.
+
+### Step 3: Commit and Tag
+- Stage only the changelog and version files.
+- Commit using the repository's existing release commit style, found with `git log --oneline --grep=release`. If there is none, use `release: vX.Y.Z` with a short bullet list of the main changes in the body.
+- Create an annotated tag: `git tag -a vX.Y.Z -m "vX.Y.Z"`, using the same prefix style as existing tags.
+
+### Step 4: Mandatory Push Confirmation
+Show the user:
+- The commit and tag that will be pushed, and the target remote and branch.
+- The release notes draft from Step 5.
+
+Do not push until the user explicitly says yes. If the user declines, leave the commit and tag local, say so, and stop.
+
+### Step 5: Push and Publish
+- Push the branch, then the tag: `git push origin <branch>` and `git push origin vX.Y.Z`.
+- Draft release notes from the new changelog section. Match the format of previous releases (check with `gh release view <previous-tag>` if the GitHub CLI is available). End with a full changelog link comparing the previous tag to the new one.
+- If the GitHub CLI is available and authenticated, publish with `gh release create vX.Y.Z --title vX.Y.Z --notes-file <file>`. Otherwise, give the user the notes to paste into their hosting platform.
+- If the repository publishes packages on tag (for example an npm publish workflow), check the run with `gh run list` and report its result.
+
+## Rules
+
+- Never release uncommitted work, and never release from a branch that is behind its upstream.
+- Never push a commit or tag, or publish release notes, without explicit user confirmation.
+- Never use `--force` on pushes or tags, and never move or delete an existing tag. If a tag already exists for the chosen version, stop and ask the user.
+- Never invent changelog entries. Release notes must come only from the `[Unreleased]` section and the commits since the previous tag.
+- Never skip a failing validation or test command.
+
+## Output Format
+
+At the end of the workflow, report:
+
+1. **Version** — the new version and why that bump was chosen.
+2. **Files Updated** — the changelog and every version file changed.
+3. **Commit and Tag** — the short commit hash, message, and tag name.
+4. **Push Result** — success with remote and branch, or the exact error.
+5. **Release** — the release URL, or the notes to publish manually.
+6. **Follow-up** — the status of any publish workflow triggered by the tag.

package/src/cli.js

@@ -0,0 +1,187 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { dirname, join } from 'node:path';
+import { createInterface } from 'node:readline/promises';
+import { fileURLToPath } from 'node:url';
+import { parseArgs } from 'node:util';
+import { TOOLS, TOOL_NAMES, targetDir } from './targets.js';
+import { listSkills } from './skills.js';
+import { installSkills, readManifest, removeSkills, skillState } from './install.js';
+
+const pkg = JSON.parse(readFileSync(join(dirname(fileURLToPath(import.meta.url)), '..', 'package.json'), 'utf8'));
+
+const HELP = `musyskills ${pkg.version} - install AI agent skills
+
+Usage:
+  musyskills list                      List available skills
+  musyskills add <skill...> [--all]    Install skills
+  musyskills remove <skill...>         Remove skills installed by musyskills
+  musyskills update                    Update installed skills to this version
+  musyskills doctor                    Show where skills are installed and their state
+
+Options:
+  -t, --tool <name>   claude, codex, cursor, antigravity (repeatable).
+                      Default: detected from the project, otherwise claude.
+  -g, --global        Install for your user instead of the current project
+  -a, --all           With add: install every skill
+  -f, --force         Overwrite or remove skills you edited or did not install
+                      with musyskills
+  -h, --help          Show this help
+  -v, --version       Show the version
+
+Examples:
+  npx musyskills add pr-draft push-to-origin
+  npx musyskills add --all --tool cursor
+  npx musyskills update --global`;
+
+const REASONS = {
+  foreign: 'exists but was not installed by musyskills (use --force to overwrite)',
+  modified: 'was edited after install (use --force to overwrite)',
+  missing: 'is not installed',
+};
+
+export async function main(argv, { cwd = process.cwd(), home = process.env.MUSYSKILLS_HOME || homedir(), log = console.log, stdin = process.stdin } = {}) {
+  let parsed;
+  try {
+    parsed = parseArgs({
+      args: argv,
+      allowPositionals: true,
+      options: {
+        tool: { type: 'string', short: 't', multiple: true },
+        global: { type: 'boolean', short: 'g' },
+        all: { type: 'boolean', short: 'a' },
+        force: { type: 'boolean', short: 'f' },
+        help: { type: 'boolean', short: 'h' },
+        version: { type: 'boolean', short: 'v' },
+      },
+    });
+  } catch (e) {
+    throw new UsageError(e.message);
+  }
+  const { values: opts, positionals } = parsed;
+  const [command, ...args] = positionals;
+
+  if (opts.version) return log(pkg.version);
+  if (opts.help || !command) return log(HELP);
+
+  const skills = listSkills();
+  const ctx = { cwd, home, global: Boolean(opts.global) };
+
+  switch (command) {
+    case 'list': {
+      const width = Math.max(...skills.map((s) => s.name.length));
+      for (const s of skills) log(`${s.name.padEnd(width)}  ${firstSentence(s.description)}`);
+      return;
+    }
+    case 'add': {
+      const chosen = opts.all ? skills : pickSkills(skills, args);
+      if (chosen.length === 0) throw new UsageError('Name at least one skill, or use --all. Run "musyskills list" to see them.');
+      const tools = await resolveTools(opts.tool, ctx, { log, stdin });
+      for (const dir of uniqueDirs(tools, ctx)) {
+        report(log, dir, installSkills(dir.path, chosen, { version: pkg.version, force: opts.force }));
+      }
+      return;
+    }
+    case 'remove': {
+      if (args.length === 0) throw new UsageError('Name at least one skill to remove.');
+      const tools = await resolveTools(opts.tool, ctx, { log, stdin });
+      for (const dir of uniqueDirs(tools, ctx)) {
+        report(log, dir, removeSkills(dir.path, args, { force: opts.force }));
+      }
+      return;
+    }
+    case 'update': {
+      const tools = opts.tool ? validateTools(opts.tool) : TOOL_NAMES;
+      let any = false;
+      for (const dir of uniqueDirs(tools, ctx)) {
+        const installed = Object.keys(readManifest(dir.path).skills);
+        if (installed.length === 0) continue;
+        any = true;
+        const chosen = skills.filter((s) => installed.includes(s.name));
+        report(log, dir, installSkills(dir.path, chosen, { version: pkg.version, force: opts.force }));
+      }
+      if (!any) log('No skills installed by musyskills were found. Use "musyskills add" first.');
+      return;
+    }
+    case 'doctor': {
+      log(`musyskills ${pkg.version} (${ctx.global ? 'global' : 'project'}: ${ctx.global ? home : cwd})`);
+      const detected = detectTools(ctx);
+      log(`Detected tools: ${detected.length ? detected.join(', ') : 'none'}`);
+      for (const dir of uniqueDirs(TOOL_NAMES, ctx)) {
+        if (!existsSync(dir.path)) continue;
+        const manifest = readManifest(dir.path);
+        const rows = skills
+          .map((s) => [s.name, skillState(dir.path, s, manifest)])
+          .filter(([, state]) => state !== 'missing');
+        if (rows.length === 0) continue;
+        log(`\n${dir.path} (${dir.tools.join(', ')})`);
+        for (const [name, state] of rows) log(`  ${name}: ${state}`);
+      }
+      return;
+    }
+    default:
+      throw new UsageError(`Unknown command "${command}". Run "musyskills --help".`);
+  }
+}
+
+export class UsageError extends Error {}
+
+function firstSentence(text) {
+  const s = text.split(/(?<=\.)\s/)[0];
+  return s.length > 90 ? s.slice(0, 87) + '...' : s;
+}
+
+function pickSkills(skills, names) {
+  const byName = new Map(skills.map((s) => [s.name, s]));
+  const unknown = names.filter((n) => !byName.has(n));
+  if (unknown.length) throw new UsageError(`Unknown skill: ${unknown.join(', ')}. Run "musyskills list" to see them.`);
+  return [...new Set(names)].map((n) => byName.get(n));
+}
+
+function validateTools(tools) {
+  const list = tools.flatMap((t) => t.split(',')).map((t) => t.trim().toLowerCase()).filter(Boolean);
+  const unknown = list.filter((t) => !TOOLS[t]);
+  if (unknown.length) throw new UsageError(`Unknown tool: ${unknown.join(', ')}. Use one of: ${TOOL_NAMES.join(', ')}.`);
+  return [...new Set(list)];
+}
+
+export function detectTools({ cwd, home, global }) {
+  const base = global ? home : cwd;
+  return TOOL_NAMES.filter((t) => TOOLS[t].markers.some((m) => existsSync(join(base, m))));
+}
+
+async function resolveTools(flag, ctx, { log, stdin }) {
+  if (flag) return validateTools(flag);
+  const detected = detectTools(ctx);
+  if (detected.length) {
+    log(`Detected: ${detected.join(', ')}`);
+    return detected;
+  }
+  if (stdin.isTTY) {
+    const rl = createInterface({ input: stdin, output: process.stdout });
+    const answer = await rl.question(`No agent tool detected. Install for which tool? (${TOOL_NAMES.join('/')}) [claude] `);
+    rl.close();
+    return validateTools([answer.trim() || 'claude']);
+  }
+  log('No agent tool detected; installing for claude. Use --tool to choose another.');
+  return ['claude'];
+}
+
+// Several tools can share one folder (codex and antigravity both use
+// .agents/skills in a project), so install there once.
+function uniqueDirs(tools, ctx) {
+  const dirs = new Map();
+  for (const tool of tools) {
+    const path = targetDir(tool, ctx);
+    if (!dirs.has(path)) dirs.set(path, { path, tools: [] });
+    dirs.get(path).tools.push(tool);
+  }
+  return [...dirs.values()];
+}
+
+function report(log, dir, results) {
+  log(`\n${dir.path} (${dir.tools.join(', ')})`);
+  for (const r of results) {
+    log(r.action === 'skipped' ? `  skipped ${r.name}: ${REASONS[r.reason]}` : `  ${r.action} ${r.name}`);
+  }
+}

package/src/install.js

@@ -0,0 +1,91 @@
+import { cpSync, existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { hashDir } from './skills.js';
+
+export const MANIFEST = '.musyskills.json';
+
+export function readManifest(dir) {
+  const file = join(dir, MANIFEST);
+  if (!existsSync(file)) return { skills: {} };
+  try {
+    const data = JSON.parse(readFileSync(file, 'utf8'));
+    return { skills: {}, ...data };
+  } catch {
+    throw new Error(`${file} is not valid JSON. Fix or delete it, then retry.`);
+  }
+}
+
+function writeManifest(dir, manifest) {
+  const names = Object.keys(manifest.skills);
+  const file = join(dir, MANIFEST);
+  if (names.length === 0) {
+    rmSync(file, { force: true });
+    return;
+  }
+  writeFileSync(file, JSON.stringify(manifest, null, 2) + '\n');
+}
+
+// State of one skill in a target folder:
+//   missing    not on disk
+//   foreign    on disk but not installed by musyskills
+//   modified   installed by musyskills, edited since
+//   outdated   installed by musyskills, unchanged, newer version available
+//   current    installed by musyskills, same as the bundled copy
+export function skillState(dir, skill, manifest) {
+  const dest = join(dir, skill.name);
+  if (!existsSync(dest)) return 'missing';
+  const entry = manifest.skills[skill.name];
+  if (!entry) return 'foreign';
+  const onDisk = hashDir(dest);
+  if (onDisk !== entry.hash) return 'modified';
+  return onDisk === hashDir(skill.path) ? 'current' : 'outdated';
+}
+
+// Installs or updates skills in one target folder. Returns one result per skill.
+export function installSkills(dir, skills, { version, force = false } = {}) {
+  mkdirSync(dir, { recursive: true });
+  const manifest = readManifest(dir);
+  const results = [];
+  for (const skill of skills) {
+    const state = skillState(dir, skill, manifest);
+    if ((state === 'foreign' || state === 'modified') && !force) {
+      results.push({ name: skill.name, action: 'skipped', reason: state });
+      continue;
+    }
+    if (state === 'current') {
+      results.push({ name: skill.name, action: 'unchanged' });
+      continue;
+    }
+    const dest = join(dir, skill.name);
+    rmSync(dest, { recursive: true, force: true });
+    cpSync(skill.path, dest, { recursive: true });
+    manifest.skills[skill.name] = { version, hash: hashDir(dest) };
+    results.push({ name: skill.name, action: state === 'missing' ? 'installed' : 'updated' });
+  }
+  manifest.version = version;
+  writeManifest(dir, manifest);
+  return results;
+}
+
+export function removeSkills(dir, names, { force = false } = {}) {
+  const manifest = readManifest(dir);
+  const results = [];
+  for (const name of names) {
+    const entry = manifest.skills[name];
+    const dest = join(dir, name);
+    if (!entry) {
+      const reason = existsSync(dest) ? 'foreign' : 'missing';
+      results.push({ name, action: 'skipped', reason });
+      continue;
+    }
+    if (existsSync(dest) && hashDir(dest) !== entry.hash && !force) {
+      results.push({ name, action: 'skipped', reason: 'modified' });
+      continue;
+    }
+    rmSync(dest, { recursive: true, force: true });
+    delete manifest.skills[name];
+    results.push({ name, action: 'removed' });
+  }
+  writeManifest(dir, manifest);
+  return results;
+}

package/src/skills.js

@@ -0,0 +1,58 @@
+import { existsSync, readdirSync, readFileSync, statSync } from 'node:fs';
+import { createHash } from 'node:crypto';
+import { dirname, join, relative } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const here = dirname(fileURLToPath(import.meta.url));
+
+// Published package: skills are bundled next to src/. Inside the repo (tests,
+// local runs) they are read straight from the top-level skills/ folder.
+export function bundledSkillsDir() {
+  const bundled = join(here, '..', 'skills');
+  if (existsSync(bundled)) return bundled;
+  return join(here, '..', '..', '..', 'skills');
+}
+
+export function parseFrontmatter(text) {
+  const match = text.replace(/\r\n/g, '\n').match(/^---\n([\s\S]*?)\n---\n/);
+  if (!match) return null;
+  const fields = {};
+  for (const line of match[1].split('\n')) {
+    const kv = line.match(/^([\w-]+):\s*(.*)$/);
+    if (kv) fields[kv[1]] = kv[2].trim();
+  }
+  return fields;
+}
+
+export function listSkills(dir = bundledSkillsDir()) {
+  return readdirSync(dir)
+    .filter((name) => existsSync(join(dir, name, 'SKILL.md')))
+    .sort()
+    .map((name) => {
+      const fm = parseFrontmatter(readFileSync(join(dir, name, 'SKILL.md'), 'utf8')) ?? {};
+      return { name, description: fm.description ?? '', path: join(dir, name) };
+    });
+}
+
+function walk(dir) {
+  const out = [];
+  for (const entry of readdirSync(dir).sort()) {
+    const full = join(dir, entry);
+    if (statSync(full).isDirectory()) out.push(...walk(full));
+    else out.push(full);
+  }
+  return out;
+}
+
+// Hash of every file in a skill folder. Line endings are normalized so a
+// checkout with CRLF does not look "modified".
+export function hashDir(dir) {
+  const h = createHash('sha256');
+  for (const file of walk(dir)) {
+    h.update(relative(dir, file).split('\\').join('/'));
+    h.update('\0');
+    h.update(readFileSync(file, 'utf8').replace(/\r\n/g, '\n'));
+    h.update('\0');
+  }
+  return h.digest('hex');
+}

package/src/targets.js

@@ -0,0 +1,38 @@
+import { join } from 'node:path';
+
+// Where each tool loads skills from. Sources:
+//   claude      https://code.claude.com/docs/en/skills
+//   codex       https://developers.openai.com/codex/skills  (REPO and USER scopes)
+//   cursor      https://cursor.com/docs/skills
+//   antigravity https://codelabs.developers.google.com/getting-started-with-antigravity-skills
+// `markers` are paths that suggest the tool is in use, checked in the project
+// directory (or the home directory with --global).
+export const TOOLS = {
+  claude: {
+    project: '.claude/skills',
+    global: '.claude/skills',
+    markers: ['.claude', 'CLAUDE.md'],
+  },
+  codex: {
+    project: '.agents/skills',
+    global: '.agents/skills',
+    markers: ['.codex', 'AGENTS.md'],
+  },
+  cursor: {
+    project: '.cursor/skills',
+    global: '.cursor/skills',
+    markers: ['.cursor', '.cursorrules'],
+  },
+  antigravity: {
+    project: '.agents/skills',
+    global: '.gemini/config/skills',
+    markers: ['.gemini', 'GEMINI.md'],
+  },
+};
+
+export const TOOL_NAMES = Object.keys(TOOLS);
+
+export function targetDir(tool, { global, cwd, home }) {
+  const t = TOOLS[tool];
+  return global ? join(home, t.global) : join(cwd, t.project);
+}