@modootoday/pmcp 0.13.1 → 0.14.0

package/skills/package-skill-catalog/SKILL.md

@@ -1,239 +1,54 @@
 ---
 name: package-skill-catalog
-description: A project has grown past a hundred dependencies and nobody knows which of them shipped usage documentation an agent could read, so every question about an installed package is answered by opening its source; or an agent's context is being spent listing skills it never opens, and startup cost grows with every dependency added.
+description: Find version-appropriate development instructions for installed public libraries, inspect a PMCP skill before using it, or install selected PMCP marketplace skills through a native runtime.
 ---
 
-# pmcp
+# Package skill catalog
 
-An MCP server that reads `SKILL.md` files out of `node_modules` and plugin
-marketplaces and serves them as five tools, so a session pays for the one skill
-it opens rather than for the whole catalog.
+Use PMCP when library instructions are available through its catalog or an installed
+package. Prefer the project's installed library version and preserve its package
+manager, configuration, build scripts and native runtime permissions.
 
-## When to reach for it
+## Find and inspect
 
-Reach for this when the skills you want an agent to read arrive as npm packages
-and leave when those packages are uninstalled. Discovery is derived from the
-installed tree at request time, so the catalog is always true of the project and
-there is no list for anyone to maintain.
+When PMCP MCP tools are connected, use skill_find with the concrete development
+task. Use skill_catalog for an inventory, skill_describe to inspect compatibility
+and resources, and skill_call for the selected instructions. Use skill_read for a
+referenced file and skill_bundle when the complete selected skill is needed.
 
-Do not reach for this to hold a project's own skills. Those live in the
-repository, they are not installed, and a host that already loads them does not
-need a server in front of them. This exists for the skills you did not write.
+Check the target major and verified version before following version-sensitive
+API examples. Catalog availability is not proof that a particular version was
+tested. Read only the relevant skill and its needed references.
 
-## Install and wire
+Without MCP, use pmcp list to inspect local catalogs and pmcp available to match
+the public catalog against installed npm dependencies. Public library instructions
+remain free and do not require a PMCP account.
 
-```sh
-npm install --save-dev @modootoday/pmcp
-```
+## Install deliberately
 
-For a host that spawns MCP servers over stdio:
+PMCP 0.14.0 includes the marketplace export command and public default provider.
+Older versions retain their previous install behavior; their users can install
+free website archives or native plugins.
 
-```json
-{
-  "mcpServers": {
-    "pmcp": { "command": "npx", "args": ["@modootoday/pmcp"] }
-  }
-}
-```
+Choose one library major with the native plugin manager, or use pmcp marketplace
+export to create a runtime-specific plugin directory. Installing a skill does not
+install the target library. Preserve native installation consent and project trust.
 
-Flags, all optional:
+Use pmcp install --dry-run before applying public npm skill installation with
+--yes. Hosted catalog installation is a separate explicit provider. Do not copy
+provider OAuth credentials into plugin manifests or PMCP configuration.
 
-| Flag                   | Effect                                                              |
-| ---------------------- | ------------------------------------------------------------------- |
-| `--root=<dir>`         | Use this `node_modules` instead of discovering upwards. Repeatable. |
-| `--scope=@acme,@other` | Only catalogue packages whose names start with one of these.        |
+Avoid activating competing major versions under the same unnamespaced skill name.
+When native skills and MCP both expose the same instructions, use one source for
+the task rather than loading duplicate bodies.
 
-Embedded in a host you are writing yourself:
+## Boundaries and sources
 
-```ts
-import { createSkillServer } from "@modootoday/pmcp";
+Catalog MCP tools read local files. They do not install plugins, run target library
+commands, download models or grant tool permissions. Native runtime authentication
+and approval remain native.
 
-const server = createSkillServer({
-  roots: ["./node_modules"],
-  scopes: ["@acme"],
-});
-```
-
-## What the consuming repository must supply
-
-Nothing, to read skills. To publish one, a package supplies a `SKILL.md` whose
-YAML frontmatter carries `name` and `description`, at any of these paths:
-
-```
-<package>/skills/<slug>/SKILL.md
-<package>/.agent/skills/<slug>/SKILL.md
-<package>/.claude/skills/<slug>/SKILL.md
-<package>/.gemini/skills/<slug>/SKILL.md
-<package>/.codex/skills/<slug>/SKILL.md
-```
-
-The path is not what makes it a skill; the file is. Discovery walks each package
-to a depth of three and treats any `SKILL.md` as a skill, skipping build output,
-sources, nested installs and test corpora.
-
-The `description` is the only text ranked, so write it as the symptom a reader
-already has rather than as a list of what the package does. A skill with no
-`description` is skipped rather than listed: ranking could never surface it, and
-listing it would spend a session's tokens on an entry that cannot answer.
-
-The package must also ship the file. A `SKILL.md` outside the manifest's `files`
-array is not in the tarball and therefore not in anyone's `node_modules`.
-
-## API
-
-### Server
-
-`createSkillServer(options)` returns a configured MCP server. `options.roots` is
-required and holds `node_modules` directories, not package directories.
-`options.scopes` filters by package-name prefix.
-
-`SERVER_NAME` is the name the server reports at initialize.
-
-### Catalog
-
-`readCatalog({roots, scopes})` returns `SkillEntry[]`, sorted by name and
-deduplicated: the first root wins, because a nested `node_modules` holds an older
-copy of a package the outer root already resolved.
-
-A `SkillEntry` carries `name` (`<package>/<slug>`), `package`, `slug`,
-`description` and the absolute `path` of the file.
-
-`readFrontmatter(source)` and `readBody(source)` split a `SKILL.md`. The
-frontmatter reader is deliberately not a YAML parser: it reads flat scalars on
-their own line and nothing nested, which is the honest limit rather than a
-partial YAML.
-
-`MAX_SKILL_DEPTH` and `SKIPPED_DIRS` are exported so a caller can see what
-discovery will and will not walk.
-
-### Tools on the wire
-
-| Tool             | Argument                                          | Returns                              |
-| ---------------- | ------------------------------------------------- | ------------------------------------ |
-| `skill_catalog`  | optional `page`, `pageSize`, `tier`               | each skill's name, description, tier |
-| `skill_find`     | `intent`, a sentence; optional `limit`, `filters` | ranked matches                       |
-| `skill_describe` | `name`                                            | metadata and files, no body          |
-| `skill_call`     | `name`                                            | that skill's body                    |
-| `skill_read`     | `name`, optional `path`                           | one file inside the skill, as text   |
-
-## Worked examples
-
-### Reading the catalog without a server
-
-```ts
-import { readCatalog } from "@modootoday/pmcp";
-
-const catalog = readCatalog({ roots: ["./node_modules"] });
-console.log(`${catalog.length} skills`);
-for (const entry of catalog.slice(0, 3)) {
-  console.log(`${entry.name}: ${entry.description}`);
-}
-```
-
-### Asking a question rather than a keyword
-
-`skill_find` ranks descriptions, which are written as symptoms, so a sentence
-retrieves and a bare noun does not. This is the difference the tool descriptions
-are trying to teach, and it is easy to get wrong:
-
-```ts
-// Retrieves: the sentence shares vocabulary with a symptom description.
-await client.callTool({
-  name: "skill_find",
-  arguments: {
-    intent: "my build copies dist into the image but a stale bundle ships",
-  },
-});
-
-// Does not: one word matches many descriptions weakly and none strongly.
-// Use skill_catalog for this shape of question; it filters rather than ranks.
-await client.callTool({ name: "skill_find", arguments: { intent: "build" } });
-```
-
-### Scoping a large tree
-
-```ts
-const mine = readCatalog({
-  roots: ["./node_modules"],
-  scopes: ["@acme/"],
-});
-```
-
-The prefix is matched against the package name with `startsWith`, so `@acme`
-also matches `@acmetools/thing`. Include the trailing slash when you mean the
-scope.
-
-## Testing against it
-
-### Build a tree, do not mock the filesystem
-
-`readCatalog` takes roots, so a test supplies a real temporary directory. This
-is faster than a filesystem mock and it exercises the walk rather than a stand-in
-for it.
-
-```ts
-import { mkdtempSync, mkdirSync, writeFileSync } from "node:fs";
-import { tmpdir } from "node:os";
-import { join } from "node:path";
-import { readCatalog } from "@modootoday/pmcp";
-
-const root = mkdtempSync(join(tmpdir(), "skills-"));
-const pkg = join(root, "node_modules", "example");
-mkdirSync(join(pkg, "skills", "wiring"), { recursive: true });
-writeFileSync(join(pkg, "package.json"), JSON.stringify({ name: "example" }));
-writeFileSync(
-  join(pkg, "skills", "wiring", "SKILL.md"),
-  "---\nname: wiring\ndescription: Something breaks and you need this.\n---\n\nbody\n",
-);
-
-const catalog = readCatalog({ roots: [join(root, "node_modules")] });
-```
-
-### Assert on what was found, never that something was found
-
-```ts
-// Proves nothing: passes on an empty tree and on a broken walk alike.
-expect(catalog).toBeDefined();
-
-// Proves the walk reached this package under this convention.
-expect(catalog.map((entry) => entry.name)).toContain("example/wiring");
-```
-
-A test that asserts a non-empty result cannot distinguish a catalog that found
-the wrong thing from one that found the right thing. Name the entry.
-
-## Invariants
-
-- **Discovery is derived, never declared.** Installing a package is how its
-  skill arrives and uninstalling it is how the skill leaves. There is no list.
-- **A skill without a description is not catalogued.** Ranking is over
-  descriptions, so an entry without one could only be reached by already knowing
-  its name.
-- **The first root wins.** A nested `node_modules` holds an older copy of an
-  already-resolved package; the outer one is the one the project runs.
-- **Absence is not failure.** No model, no SQLite, and an unreadable file each
-  degrade the answer rather than ending the request, and the response says which
-  path answered so a fallback is visible rather than silent.
-- **Startup does not grow with the catalog.** Bodies are read by `skill_call`,
-  one at a time. Adding a dependency that ships ten skills adds ten short
-  descriptions, not ten documents.
-
-## What it will not do
-
-The MCP tools read installed files and return text. They do not install packages
-or make catalog API requests. The CLI's available, install and sync commands are
-separate from that local reading path.
-
-The CLI does not write directly into node_modules or treat OAuth access tokens
-as npm credentials. Installation uses the project's npm or Bun configuration,
-requires confirmation, and verifies registry integrity and the installed version.
-Use --dry-run to inspect changes without applying them. Sync does not delete
-unrelated dependencies or skills authored by the user.
-
-It will not parse full YAML. Frontmatter is read as flat scalars, so a nested
-structure is ignored rather than half-understood.
-
-The default server ranks lexically. The optional index command requires
-`@huggingface/transformers` and may load model assets when explicitly invoked.
-Installing that peer alone is not proof that the server uses its index.
-No postinstall hook downloads a model.
+See the public [installation guide](https://pmcp.build/install/) and
+[skill catalog](https://pmcp.build/skills/). Skills follow
+[Agent Skills](https://agentskills.io/specification); plugin packaging follows
+[Agent Plugins](https://agent-plugins.org/) with native runtime adapters.