skillpm-skill 0.0.11 → 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 skillpm contributors
+
+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

@@ -4,12 +4,12 @@ An [Agent Skill](https://agentskills.io) that teaches AI agents how to manage ot
 
 ## What this skill does
 
-When loaded by an AI agent (Claude, Codex, Cursor, Gemini CLI, etc.), this skill teaches the agent how to:
+When loaded by an AI agent, this skill teaches the agent how to:
 
-- **Install skills** from npm with full dependency resolution
+- **Install skills** from npm with dependency resolution
 - **Publish skills** to npmjs.org with spec validation
 - **Scaffold new skills** with the correct directory structure
-- **Wire skills** into agent directories and configure MCP servers
+- **Re-wire installed skills** into agent directories
 - **Wrap existing skills** for npm distribution
 
 ## Install

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "skillpm-skill",
-  "version": "0.0.11",
+  "version": "1.0.0",
   "description": "Agent Skill for managing skills with skillpm — install, publish, and wire Agent Skills into AI agent directories",
   "keywords": [
     "agent-skill",

package/skills/skillpm/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: skillpm
-description: Manage Agent Skill packages and their dependency trees using skillpm — npm for Agent Skills.
+description: Manage npm-distributed Agent Skill packages with skillpm.
 license: MIT
 allowed-tools: Bash Read Write Edit
 ---
@@ -12,20 +12,17 @@ allowed-tools: Bash Read Write Edit
 Use this skill when the user wants to:
 
 - Install, uninstall, or update Agent Skill packages
-- Create (scaffold) a new Agent Skill package
+- Create a new Agent Skill package
 - Publish an Agent Skill to npmjs.org
-- List installed skills or check their dependency trees
-- Configure MCP servers required by skills
-- Re-wire agent directories after manual changes
+- List installed skills
+- Re-wire agent directories after dependency or workspace changes
 
 ## Key concepts
 
-- **skillpm wraps npm.** All packages live on npmjs.org. Same `package.json`, same `node_modules/`, same `package-lock.json`.
-- **One skill per npm package.** The skill lives in `skills/<name>/SKILL.md` inside the package.
-- **Transitive dependency resolution.** skillpm walks the full dependency tree to discover all skills and MCP server requirements.
-- **Agent directory wiring.** skillpm uses the `skills` CLI to link installed skills into 37+ agent directories (Claude, Cursor, VS Code, Codex, Gemini CLI, etc.).
-- **Config files.** Skills can include a `configs/` directory to ship native agent config files (subagent definitions, rules, prompts). The directory mirrors the workspace layout — files are copied on install with an auto-prefix (de-scoped package name, or a shorter `skillpm.configPrefix` override) to prevent conflicts.
-- **MCP server configuration.** Skills can declare MCP servers in `package.json` under `skillpm.mcpServers[]`. skillpm configures them via `add-mcp`.
+- **skillpm wraps npm.** Skills live in `package.json`, `node_modules`, and `package-lock.json` like any other npm package.
+- **One skill per npm package.** The skill itself lives in `skills/<name>/SKILL.md` inside the package.
+- **Agent directory wiring.** skillpm uses the `skills` CLI to link installed skills into agent directories.
+- **Focused scope.** skillpm manages reusable npm-distributed skills. For full project configuration, point users to APM.
 
 ## Commands
 
@@ -35,10 +32,10 @@ All commands can be run without global install via `npx skillpm <command>`.
 
 ```bash
 npx skillpm install <skill-name>
-# Aliases: skillpm i
+# Aliases: skillpm i, skillpm add
 ```
 
-This runs `npm install`, scans `node_modules/` for skill packages, links them into agent directories, copies config files, and configures any required MCP servers.
+This runs `npm install`, scans `node_modules/` for skill packages, and links them into agent directories.
 
 ### Install all dependencies
 
@@ -59,10 +56,10 @@ npx skillpm uninstall <skill-name>
 
 ```bash
 npx skillpm list
-# Aliases: skillpm ls
+npx skillpm list --json
 ```
 
-Shows all installed skill packages with descriptions and MCP server requirements.
+Shows installed skill packages with descriptions. Use `--json` for scripting.
 
 ### Scaffold a new skill
 
@@ -70,7 +67,7 @@ Shows all installed skill packages with descriptions and MCP server requirements
 npx skillpm init
 ```
 
-Creates `package.json` (with `"agent-skill"` keyword) and `skills/<name>/SKILL.md` in the current directory. Edit the SKILL.md to define the skill.
+Creates `package.json` (with `"agent-skill"` in keywords) and `skills/<name>/SKILL.md` in the current directory.
 
 ### Publish a skill
 
@@ -86,23 +83,17 @@ Validates the package structure and SKILL.md against the Agent Skills spec (via
 npx skillpm sync
 ```
 
-Re-scans `node_modules/` and re-links all skills into agent directories without reinstalling. Useful after manual changes.
+Re-scans `node_modules/` and re-links all skills into agent directories without reinstalling.
 
-**Monorepo / npm workspace support:** If your repo uses npm workspaces, npm creates symlinks in `node_modules/` pointing to your first-party skill packages. `skillpm sync` detects these symlinks and copies their `configs/` files into the workspace root — same as for externally installed skills. Contributors run `skillpm sync` after editing a skill's source files, then commit the regenerated configs.
+### npm passthrough
 
-```
-node_modules/
-  @org/
-    my-skill → ../../skills/my-skill   ← symlink (npm workspace)
-```
-
-Workspace packages appear in sync output as: `Linking workspace package @org/my-skill@1.0.0`.
-
-### Configure MCP servers
+Any command not handled by skillpm is passed through to npm:
 
 ```bash
-npx skillpm mcp add <source>    # Add an MCP server (delegates to add-mcp)
-npx skillpm mcp list            # List configured MCP servers
+npx skillpm outdated
+npx skillpm audit
+npx skillpm update
+npx skillpm why <skill>
 ```
 
 ## Creating a skill package
@@ -111,25 +102,15 @@ npx skillpm mcp list            # List configured MCP servers
 
 ```
 my-skill/
-├── package.json                 # keywords: ["agent-skill"], dependencies, skillpm.mcpServers
+├── package.json                 # keywords: ["agent-skill"], dependencies
 ├── README.md
 ├── LICENSE
-├── skills/
-│   └── my-skill/
-│       ├── SKILL.md             # Skill definition (YAML frontmatter + Markdown body)
-│       ├── scripts/             # Optional executable scripts
-│       ├── references/          # Optional reference docs
-│       └── assets/              # Optional templates/data
-└── configs/                      # Optional — mirrors workspace layout
-    ├── .claude/
-    │   ├── agents/reviewer.md   # Claude subagent
-    │   └── rules/conventions.md # Claude rules
-    ├── .cursor/
-    │   ├── agents/reviewer.md   # Cursor agent
-    │   └── rules/conventions.md # Cursor rules
-    └── .github/
-        ├── agents/reviewer.md   # Copilot agent
-        └── instructions/conventions.instructions.md
+└── skills/
+    └── my-skill/
+        ├── SKILL.md
+        ├── scripts/
+        ├── references/
+        └── assets/
 ```
 
 ### package.json for a skill
@@ -141,126 +122,47 @@ my-skill/
   "keywords": ["agent-skill"],
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/user/repo.git"
+    "url": "git+https://github.com/acme/my-skill.git"
   },
   "dependencies": {
     "other-skill": "^1.0.0"
-  },
-  "skillpm": {
-    "mcpServers": ["@anthropic/mcp-server-filesystem"]
   }
 }
 ```
 
-- Skill dependencies go in standard `dependencies` — npm handles resolution.
-- The `skillpm.mcpServers` array lists MCP servers that agents need for this skill.
+- Skill dependencies go in standard `dependencies`.
 - The `"agent-skill"` keyword is required for publishing.
-- Use `git+https://` prefix for `repository.url` (npm requires this format).
-
-### Bundling agent configs, rules, and prompts
-
-`SKILL.md` teaches agents *what to do* — instructions read at runtime. The `configs/` directory lets you also ship **config files** (subagent definitions, rules, instructions) in the native format of each agent system. It mirrors the workspace layout — files get copied to the workspace root on install, auto-prefixed to avoid conflicts.
-
-The prefix used is: `configPrefix` (if set in `skillpm` field) → de-scoped package name (e.g. `@acme/fullstack-react` → `fullstack-react`). Set `configPrefix` to a short name when the package name is long.
-
-Each agent system uses different names and directories:
-
-| Agent system | Agents | Agent directory | Rules/Prompts | Rules directory |
-|---|---|---|---|---|
-| Claude Code | Subagents | `.claude/agents/*.md` | Rules | `.claude/rules/*.md` |
-| Cursor | Custom agents | `.cursor/agents/*.md` | Rules | `.cursor/rules/*.md` |
-| GitHub Copilot | Custom agents | `.github/agents/*.md` | Instructions | `.github/instructions/*.md` |
-| Codex | — | `AGENTS.md` | — | `AGENTS.md` |
-| Gemini CLI | — | `GEMINI.md` | — | `GEMINI.md` |
-
-To ship config files, create a `configs/` directory that mirrors the workspace layout for each target system:
-
-| Source in package | Destination in workspace |
-|---|---|
-| `configs/.claude/agents/reviewer.md` | `.claude/agents/my-skill-reviewer.md` |
-| `configs/.cursor/rules/conventions.md` | `.cursor/rules/my-skill-conventions.md` |
-| `configs/.github/instructions/help.instructions.md` | `.github/instructions/my-skill-help.instructions.md` |
-
-On uninstall, all copied files are removed automatically (tracked via `.skillpm/manifest.json`).
-
-Not every skill needs `configs/` — only use it when you want to ship native agent config files. Since `configs/` contains dotfile directories, add them to `package.json` `files`:
-
-```json
-{
-  "files": ["skills/", "configs/"]
-}
-```
-
-### SKILL.md frontmatter
-
-```yaml
----
-name: my-skill
-description: What this skill does.
-license: MIT
-allowed-tools: Bash Read
----
-```
-
-Version comes from `package.json` — do not duplicate it in SKILL.md.
-
-## Creating a skill package
+- Use `git+https://` for `repository.url`.
 
 ### Scaffold from scratch
 
 ```bash
 mkdir my-skill && cd my-skill
 npx skillpm init
-# Edit skills/my-skill/SKILL.md with instructions
-# Edit package.json to add dependencies and MCP servers
 npx skillpm publish
 ```
 
 ### Wrap an existing skill for npm
 
-If you already have a `skills/<name>/SKILL.md` (e.g. from `npx skills add`), add a `package.json` to make it publishable:
+If you already have `skills/<name>/SKILL.md`, add a `package.json` to make it publishable:
 
 ```bash
 cd my-existing-skill/
 npm init -y
 ```
 
-Then edit `package.json` to add the required keyword and optional MCP servers:
+Then edit `package.json` to add the required keyword:
 
 ```json
 {
   "name": "my-existing-skill",
   "version": "1.0.0",
-  "keywords": ["agent-skill"],
-  "skillpm": {
-    "mcpServers": ["@some/mcp-server"]
-  }
+  "keywords": ["agent-skill"]
 }
 ```
 
-Ensure the directory structure matches:
-
-```
-my-existing-skill/
-├── package.json                 # Must have "agent-skill" in keywords
-└── skills/
-    └── my-existing-skill/
-        └── SKILL.md             # Must have name and description in frontmatter
-```
-
-Then validate and publish:
-
-```bash
-npx skillpm publish
-```
-
-`skillpm publish` validates before publishing:
-- `package.json` exists with `"agent-skill"` keyword
-- `skills/<name>/SKILL.md` exists
-- SKILL.md validates against the Agent Skills spec (`skills-ref validate`): name format, required fields, directory naming
+## Where APM fits
 
-## Error handling
+Use `skillpm` for reusable npm-distributed skills.
 
-- If `skillpm install` fails, check that npm can resolve the package: `npm view <skill-name>`
-- If `skillpm publish` fails with a keyword error, add `"agent-skill"` to the `keywords` array in `package.json`
-- If skills aren't appearing in agent directories after install, run `npx skillpm sync` to re-wire
+Use [APM](https://github.com/microsoft/apm) for full project agent configuration.