@lovehlmmm/primekit 1.0.0

package/skills/skill-creator/references/plugin-marketplace-overview.md

@@ -0,0 +1,90 @@
+# Plugin Marketplaces Overview
+
+Plugin marketplace = catalog distributing Claude Code extensions across teams/communities.
+Provides centralized discovery, version tracking, automatic updates, multiple source types.
+
+## Creation & Distribution Flow
+
+1. **Create plugins** — commands, agents, hooks, MCP servers, LSP servers (see [Plugins docs](https://code.claude.com/docs/en/plugins.md))
+2. **Create marketplace file** — `.claude-plugin/marketplace.json` listing plugins + sources
+3. **Host marketplace** — push to GitHub/GitLab/git host
+4. **Share** — users add via `/plugin marketplace add`, install via `/plugin install`
+
+Updates: push changes to repo → users refresh via `/plugin marketplace update`.
+
+## Directory Structure
+
+```
+my-marketplace/
+├── .claude-plugin/
+│   └── marketplace.json        # Marketplace catalog (required)
+└── plugins/
+    └── review-plugin/
+        ├── .claude-plugin/
+        │   └── plugin.json     # Plugin manifest
+        └── skills/
+            └── review/
+                └── SKILL.md    # Skill definition
+```
+
+## Walkthrough: Local Marketplace
+
+```bash
+# 1. Create structure
+mkdir -p my-marketplace/.claude-plugin
+mkdir -p my-marketplace/plugins/review-plugin/.claude-plugin
+mkdir -p my-marketplace/plugins/review-plugin/skills/review
+
+# 2. Create skill (SKILL.md), plugin manifest (plugin.json), marketplace catalog (marketplace.json)
+
+# 3. Add and install
+/plugin marketplace add ./my-marketplace
+/plugin install review-plugin@my-plugins
+
+# 4. Test
+/review
+```
+
+## Plugin Installation Behavior
+
+Plugins copied to cache location on install. Cannot reference files outside plugin directory with `../`.
+Workarounds: symlinks (followed during copying) or restructure so shared files are inside plugin source path.
+
+## User Commands
+
+| Command | Purpose |
+|---------|---------|
+| `/plugin marketplace add <source>` | Add marketplace |
+| `/plugin marketplace update` | Refresh marketplace |
+| `/plugin install <name>@<marketplace>` | Install plugin |
+| `/plugin validate .` | Validate marketplace JSON |
+| `claude plugin validate .` | CLI validation |
+
+## Validation & Testing
+
+```bash
+# Validate marketplace JSON
+claude plugin validate .
+# or within Claude Code:
+/plugin validate .
+
+# Test locally before distribution
+/plugin marketplace add ./my-local-marketplace
+/plugin install test-plugin@my-local-marketplace
+```
+
+## Related References
+
+- **Schema:** `references/plugin-marketplace-schema.md`
+- **Sources:** `references/plugin-marketplace-sources.md`
+- **Hosting:** `references/plugin-marketplace-hosting.md`
+- **Troubleshooting:** `references/plugin-marketplace-troubleshooting.md`
+- **Cross-marketplace (Codex, Vercel skills.sh):** `references/cross-marketplace-distribution.md`
+
+## Official Documentation
+
+- [Plugin Marketplaces](https://code.claude.com/docs/en/plugin-marketplaces.md)
+- [Discover Plugins](https://code.claude.com/docs/en/discover-plugins.md)
+- [Create Plugins](https://code.claude.com/docs/en/plugins.md)
+- [Plugins Reference](https://code.claude.com/docs/en/plugins-reference.md)
+- [Plugin Settings](https://code.claude.com/docs/en/settings.md#plugin-settings)

package/skills/skill-creator/references/plugin-marketplace-schema.md

@@ -0,0 +1,93 @@
+# Plugin Marketplace Schema
+
+Full JSON schema for `.claude-plugin/marketplace.json`.
+
+## Required Top-Level Fields
+
+| Field | Type | Description | Example |
+|-------|------|-------------|---------|
+| `name` | string | Marketplace ID (kebab-case, no spaces). Users see: `/plugin install tool@name` | `"acme-tools"` |
+| `owner` | object | Maintainer info (`name` required, `email` optional) | |
+| `plugins` | array | List of plugin entries | |
+
+### Reserved Names (Cannot Use)
+
+`claude-code-marketplace`, `claude-code-plugins`, `claude-plugins-official`, `anthropic-marketplace`, `anthropic-plugins`, `agent-skills`, `life-sciences`. Names impersonating official marketplaces also blocked.
+
+## Optional Metadata
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `metadata.description` | string | Brief marketplace description |
+| `metadata.version` | string | Marketplace version |
+| `metadata.pluginRoot` | string | Base dir prepended to relative source paths (e.g., `"./plugins"`) |
+
+## Plugin Entry — Required Fields
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `name` | string | Plugin ID (kebab-case). Users see: `/plugin install name@marketplace` |
+| `source` | string\|object | Where to fetch plugin (see `plugin-marketplace-sources.md`) |
+
+## Plugin Entry — Optional Metadata
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `description` | string | Brief plugin description |
+| `version` | string | Plugin version |
+| `author` | object | Author info (`name` required, `email` optional) |
+| `homepage` | string | Plugin docs URL |
+| `repository` | string | Source code URL |
+| `license` | string | SPDX license ID (MIT, Apache-2.0) |
+| `keywords` | array | Discovery/categorization tags |
+| `category` | string | Plugin category |
+| `tags` | array | Searchability tags |
+| `strict` | boolean | Default `true`: merges with plugin.json. `false`: marketplace entry defines plugin entirely |
+
+## Plugin Entry — Component Configuration
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `commands` | string\|array | Custom paths to command files/dirs |
+| `agents` | string\|array | Custom paths to agent files |
+| `hooks` | string\|object | Hooks config or path to hooks file |
+| `mcpServers` | string\|object | MCP server configs or path |
+| `lspServers` | string\|object | LSP server configs or path |
+
+## Minimal Example
+
+```json
+{
+  "name": "my-plugins",
+  "owner": { "name": "Your Name" },
+  "plugins": [{
+    "name": "review-plugin",
+    "source": "./plugins/review-plugin",
+    "description": "Adds a review skill for quick code reviews"
+  }]
+}
+```
+
+## Full Example
+
+```json
+{
+  "name": "company-tools",
+  "owner": { "name": "DevTools Team", "email": "devtools@example.com" },
+  "metadata": { "description": "Internal dev tools", "version": "1.0.0", "pluginRoot": "./plugins" },
+  "plugins": [
+    {
+      "name": "code-formatter",
+      "source": "./plugins/formatter",
+      "description": "Automatic code formatting on save",
+      "version": "2.1.0",
+      "author": { "name": "DevTools Team" }
+    },
+    {
+      "name": "deployment-tools",
+      "source": { "source": "github", "repo": "company/deploy-plugin" },
+      "description": "Deployment automation tools"
+    }
+  ]
+}
+```

package/skills/skill-creator/references/plugin-marketplace-sources.md

@@ -0,0 +1,103 @@
+# Plugin Marketplace Sources
+
+Plugin source types for `marketplace.json` plugin entries.
+
+## Relative Paths (Same Repo)
+
+```json
+{ "name": "my-plugin", "source": "./plugins/my-plugin" }
+```
+
+**Note:** Only works when marketplace added via Git (GitHub/GitLab/git URL). URL-based marketplaces only download `marketplace.json`, not plugin files. Use GitHub/git sources for URL-based distribution.
+
+## GitHub Repositories
+
+```json
+{
+  "name": "github-plugin",
+  "source": { "source": "github", "repo": "owner/plugin-repo" }
+}
+```
+
+Pin to specific version:
+```json
+{
+  "name": "github-plugin",
+  "source": {
+    "source": "github",
+    "repo": "owner/plugin-repo",
+    "ref": "v2.0.0",
+    "sha": "a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0"
+  }
+}
+```
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `repo` | string | Required. `owner/repo` format |
+| `ref` | string | Optional. Branch or tag (defaults to repo default) |
+| `sha` | string | Optional. Full 40-char commit SHA for exact pinning |
+
+## Git Repositories (GitLab, Bitbucket, etc.)
+
+```json
+{
+  "name": "git-plugin",
+  "source": { "source": "url", "url": "https://gitlab.com/team/plugin.git" }
+}
+```
+
+Pin to specific version:
+```json
+{
+  "name": "git-plugin",
+  "source": {
+    "source": "url",
+    "url": "https://gitlab.com/team/plugin.git",
+    "ref": "main",
+    "sha": "a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0"
+  }
+}
+```
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `url` | string | Required. Full git URL (must end `.git`) |
+| `ref` | string | Optional. Branch or tag |
+| `sha` | string | Optional. Full 40-char commit SHA |
+
+## Advanced Example (All Features)
+
+```json
+{
+  "name": "enterprise-tools",
+  "source": { "source": "github", "repo": "company/enterprise-plugin" },
+  "description": "Enterprise workflow automation tools",
+  "version": "2.1.0",
+  "author": { "name": "Enterprise Team", "email": "enterprise@example.com" },
+  "homepage": "https://docs.example.com/plugins/enterprise-tools",
+  "license": "MIT",
+  "keywords": ["enterprise", "workflow", "automation"],
+  "category": "productivity",
+  "commands": ["./commands/core/", "./commands/enterprise/"],
+  "agents": ["./agents/security-reviewer.md", "./agents/compliance-checker.md"],
+  "hooks": {
+    "PostToolUse": [{
+      "matcher": "Write|Edit",
+      "hooks": [{ "type": "command", "command": "${CLAUDE_PLUGIN_ROOT}/scripts/validate.sh" }]
+    }]
+  },
+  "mcpServers": {
+    "enterprise-db": {
+      "command": "${CLAUDE_PLUGIN_ROOT}/servers/db-server",
+      "args": ["--config", "${CLAUDE_PLUGIN_ROOT}/config.json"]
+    }
+  },
+  "strict": false
+}
+```
+
+**Key notes:**
+- `${CLAUDE_PLUGIN_ROOT}` — references files within plugin's installation cache directory
+- `strict: false` — marketplace entry defines plugin entirely, no `plugin.json` needed
+- `commands`/`agents` — multiple directories or individual files, paths relative to plugin root

package/skills/skill-creator/references/plugin-marketplace-troubleshooting.md

@@ -0,0 +1,76 @@
+# Plugin Marketplace Troubleshooting
+
+## Marketplace Not Loading
+
+**Symptoms:** Can't add marketplace or see plugins.
+
+**Checklist:**
+- Marketplace URL accessible?
+- `.claude-plugin/marketplace.json` exists at specified path?
+- JSON syntax valid? Run `claude plugin validate .` or `/plugin validate .`
+- Private repo — do you have access permissions?
+
+## Validation Errors
+
+Run `claude plugin validate .` from marketplace directory. Common errors:
+
+| Error | Cause | Fix |
+|-------|-------|-----|
+| `File not found: .claude-plugin/marketplace.json` | Missing manifest | Create with required fields |
+| `Invalid JSON syntax: Unexpected token...` | JSON syntax error | Fix commas, quotes, brackets |
+| `Duplicate plugin name "x"` | Two plugins share name | Give unique `name` values |
+| `plugins[0].source: Path traversal not allowed` | Source contains `..` | Use paths relative to root, no `..` |
+
+**Warnings (non-blocking):**
+- `Marketplace has no plugins defined` — add plugins to array
+- `No marketplace description provided` — add `metadata.description`
+- `Plugin "x" uses npm source` — npm not fully implemented, use github/local
+
+## Plugin Installation Failures
+
+**Symptoms:** Marketplace appears but install fails.
+
+**Checklist:**
+- Plugin source URLs accessible?
+- Plugin directories contain required files?
+- GitHub sources — repos public or you have access?
+- Test manually by cloning/downloading source
+
+## Private Repository Auth Fails
+
+### Manual Install/Update
+- Authenticated with git provider? `gh auth status` for GitHub
+- Credential helper configured? `git config --global credential.helper`
+- Can you clone repo manually?
+
+### Background Auto-Updates
+- Token set in environment? `echo $GITHUB_TOKEN`
+- Token has required permissions?
+  - GitHub: `repo` scope for private repos
+  - GitLab: `read_repository` scope minimum
+- Token not expired?
+
+## Relative Paths Fail in URL-Based Marketplaces
+
+**Symptoms:** Added marketplace via URL, plugins with `"./plugins/my-plugin"` source fail.
+
+**Cause:** URL-based marketplaces only download `marketplace.json`, not plugin files. Relative paths reference files on remote server that weren't downloaded.
+
+**Fixes:**
+1. **Use external sources:**
+   ```json
+   { "name": "my-plugin", "source": { "source": "github", "repo": "owner/repo" } }
+   ```
+2. **Use Git-based marketplace:** Host in Git repo, add via git URL. Clones entire repo, relative paths work.
+
+## Files Not Found After Installation
+
+**Symptoms:** Plugin installs but file references fail, especially outside plugin directory.
+
+**Cause:** Plugins copied to cache directory, not used in-place. Paths like `../shared-utils` won't work.
+
+**Fixes:**
+- Use symlinks (followed during copying)
+- Restructure so shared directory is inside plugin source path
+- Use `${CLAUDE_PLUGIN_ROOT}` in hooks/MCP configs for cache-aware paths
+- See [Plugin caching docs](https://code.claude.com/docs/en/plugins-reference.md#plugin-caching-and-file-resolution)

package/skills/skill-creator/references/script-dependency-strategy.md

@@ -0,0 +1,141 @@
+# Script Dependency Strategy
+
+How a skill declares external code without bloating disk. Guidance for skill
+authors from version 4.1.0 onward — see the compatibility note at the end
+for existing skills.
+
+The one-line rule: **no per-skill copy of anything a central cache can own.
+Declare deps at the invocation site — pinned runner command or PEP 723 inline
+metadata — never as an installed footprint inside the skill directory.**
+
+## 1. Decision Tree
+
+Follow in order; drop out at the first match.
+
+1. **Stdlib is enough.** Ship zero deps. Prefer `argparse`, `pathlib`, `json`,
+   `subprocess`, `urllib.request` over reaching for a library.
+2. **A maintained CLI exists.** Invoke via a pinned ephemeral runner:
+   - Node: `npx -y pkg@1.2.3 …` or `pnpm dlx pkg@1.2.3 …`
+   - Python: `pipx run pkg==1.2.3 …` or `uvx --from 'pkg==1.2.3' cmd …`
+   Never re-wrap a CLI in your own script.
+3. **Python library, no CLI.** Use PEP 723 inline metadata + `uv run`:
+   ```python
+   #!/usr/bin/env -S uv run --script
+   # /// script
+   # dependencies = ["httpx==0.27.0"]
+   # ///
+   import httpx
+   ```
+   `pipx run` also honors the inline block. Deps resolve into the central
+   cache, not into a per-skill `.venv`.
+4. **Node library, no CLI (weak spot).** Options in preference order:
+   - Prefer a Python equivalent for that script.
+   - Wrap the lib behind a maintained CLI you can `npx` instead.
+   - Last resort: minimal `package.json` with a documented setup step;
+     accept that `node_modules/` is stripped by `package_skill.py` and the
+     end-user must run `npm ci` before invoking.
+5. **Legit local-dep exceptions.** Documented setup is required in `SKILL.md`
+   when any of these apply:
+   - offline / air-gapped user environments,
+   - native or binary deps that ephemeral runners handle poorly,
+   - org policy mandates vendored, auditable installs.
+   Keep it minimal (≤2 deps), pinned exactly, and never auto-install silently.
+
+## 2. Pinning & Fail-Fast Rules
+
+**Exact pins are mandatory.** Floating tags drift and open a typosquat /
+hijack surface at the *user's* runtime, not yours.
+
+| Runner | Correct | Wrong |
+|--------|---------|-------|
+| `npx` | `npx -y pkg@1.2.3` | `npx pkg`, `npx pkg@latest` |
+| `pipx` | `pipx run pkg==1.2.3` | `pipx run pkg` |
+| `uvx` | `uvx --from 'pkg==1.2.3' cmd` | `uvx cmd` |
+| `pnpm` | `pnpm dlx pkg@1.2.3` | `pnpm dlx pkg` |
+
+**Non-interactive by default.** `npx` without `-y` will hang forever waiting
+for a "install this package? (y/n)" prompt in an agent context. Always pass
+`-y`. `pipx run` and `uvx` are non-interactive by default.
+
+**Fail-fast availability check.** The user machine may not have `uv`, `pipx`,
+`bun`, or even a network. Detect early with an actionable message:
+
+```python
+import shutil, sys
+if shutil.which("uv") is None:
+    sys.exit("uv is required. Install with: curl -LsSf https://astral.sh/uv/install.sh | sh")
+```
+
+**Network note in SKILL.md.** When a skill relies on ephemeral runners, add
+one line to its `SKILL.md`: *"Requires network on first invocation to fetch
+`<pkg>`; cached thereafter."*
+
+**Pick one primary runner per ecosystem.** Not a fallback ladder — a single
+runner. Suggested defaults:
+
+- Node → `npx -y` (ships with Node; most universally available).
+- Python → `uvx` primary, `pipx run` fallback.
+
+## 3. Central-Cache Rationale
+
+Ephemeral runners share their caches across every skill on the machine:
+
+- **`npx`** stores packages in `~/.npm/_npx/` — each pinned version once,
+  reused by any skill or project.
+- **`uv`** keeps a hard-linked cache at `~/.cache/uv/`; ten skills asking for
+  `httpx==0.27.0` cost one copy on disk.
+- **`pipx`** creates one venv per tool under `~/.local/pipx/venvs/`, shared
+  across projects.
+
+Per-skill `node_modules/` or `.venv/` defeats all of this: N skills → N
+copies, each hundreds of MB, none reusable.
+
+**Packaging-contract argument (the strongest one).** `scripts/package_skill.py`
+already strips `node_modules/` (and, from 4.1.0, `venv/` and `.venv/`). A
+skill that expects its bundled `node_modules/` to be present at the user's
+runtime is **broken by contract** — the zip never had them. Declaring deps
+at the invocation site makes what was implicit explicit.
+
+## 4. Eight Anti-Patterns
+
+Each entry: **cause → fix.**
+
+1. **Commit `node_modules/`, `.venv/`, `venv/`, vendored wheels/tarballs.**
+   Bloat + broken-by-contract (venvs are non-relocatable). → Add to
+   `.gitignore`; use a pinned runner or PEP 723 instead.
+2. **Skill-local `requirements.txt` for a tool already exposed as a CLI.**
+   Duplicates what `pipx run pkg==x.y.z` gives for free. → Drop the file;
+   invoke the CLI directly.
+3. **First-run bootstrap that runs `npm install` / `pip install` into the
+   skill directory.** Silently mutates the skill's own tree. → Use a pinned
+   ephemeral runner or PEP 723; keep the skill dir read-only.
+4. **`pip install --user` or `npm install -g` from inside a script.** Mutates
+   global env, causes cross-skill version conflicts, needs elevated perms on
+   some systems. → Never mutate global env from a script; use ephemeral
+   runners.
+5. **Unpinned ephemeral invocation (`npx tool`, `pipx run pkg`, `@latest`).**
+   Behavior drifts silently; supply-chain surface widens. → Pin every version
+   exactly.
+6. **Interactive runner in a non-interactive context (`npx` without `-y`).**
+   Hangs the agent turn forever. → Always pass `-y` (or the runner's
+   equivalent).
+7. **Heavy library for a stdlib-sized job** (e.g. pandas to read one CSV,
+   requests for one GET). → Use `csv`, `urllib.request`, `pathlib`.
+8. **Re-implement in a bundled script something a maintained CLI already
+   does.** Doubles the maintenance surface. → Invoke the CLI via `npx`/`uvx`.
+
+## 5. Migration & Compatibility
+
+**Additive, not breaking.** This guidance applies to skills authored from
+`primekit-skill-creator` version 4.1.0 onward. Skills that currently ship
+`requirements.txt`, `package.json`, or a documented local setup remain
+valid — no migration required, no scanner enforced, and `package_skill.py`
+will keep packaging them exactly as before (minus the always-stripped
+`node_modules/` and, from 4.1.0, `venv/`/`.venv/` and the newly-excluded
+`.env`).
+
+**Templates that were mandatory become conditional.** `requirements.txt` and
+the `python-dotenv` recipe are exception paths from 4.1.0 — used only when
+justified by one of the "Legit local-dep exceptions" cases in §1. Existing
+skills that use them stay valid; new skills should route through the
+decision tree first.

package/skills/skill-creator/references/script-quality-criteria.md

@@ -0,0 +1,151 @@
+# Script Quality Criteria
+
+Scripts provide deterministic reliability and token efficiency.
+
+## Dependency Strategy
+
+Before bundling any external code with a skill, decide **where** the dep
+should live: a central cache the runner already owns, or the skill directory.
+The default is the central cache. See
+[`./script-dependency-strategy.md`](./script-dependency-strategy.md) for the
+decision tree, pinning rules, central-cache rationale, and the anti-patterns
+this section shorthands to.
+
+Rule of thumb: **declare deps at the invocation site** — pinned ephemeral
+runner (`npx -y pkg@x.y.z`, `pipx run pkg==x.y.z`, `uvx --from 'pkg==x.y.z' cmd`)
+or PEP 723 inline metadata + `uv run`. Reach for `requirements.txt` or
+`package.json` only under the "Legit local-dep exceptions" cases in the
+strategy ref (offline, native binaries, org vendoring policy).
+
+## When to Include Scripts
+
+- Same code rewritten repeatedly
+- Deterministic operations needed
+- Complex transformations
+- External tool integrations
+
+## Cross-Platform Requirements
+
+**Prefer:** Node.js or Python
+**Avoid:** Bash scripts (not well-supported on Windows)
+
+If bash required, provide Node.js/Python alternative.
+
+## Testing Requirements
+
+**Mandatory:** All scripts must have tests
+
+```bash
+# Run tests before packaging
+python -m pytest scripts/tests/
+# or
+npm test
+```
+
+Tests must pass. No skipping failed tests.
+
+## Environment Variables
+
+Respect hierarchy (first found wins):
+
+1. `process.env` (runtime)
+2. User skill `.env` (skill-specific)
+3. Shared user skills `.env`
+4. `$HOME/.claude/.env` (global)
+5. Project skill `.env` (cwd)
+6. Shared project skills `.env` (cwd)
+7. `./.claude/.env` (cwd)
+
+**Implementation pattern (Python).** `python-dotenv` is optional — treat it
+as a soft dep so the script keeps working when the module is unavailable in
+the user's runtime (which will be the common case once skills stop shipping
+per-skill venvs). Fall back to `os.environ` (already populated by the shell
+or the runtime) when import fails, and log the fallback so it stays
+observable:
+
+```python
+import os, logging
+
+try:
+    from dotenv import load_dotenv
+    for path in (
+        os.path.expanduser('~/.claude/.env'),
+        user_shared_skills_env,
+        user_skill_env,
+        project_skill_env,
+        project_shared_skills_env,
+        './.claude/.env',
+    ):
+        load_dotenv(path)
+except ImportError:
+    logging.warning(
+        "python-dotenv not installed; relying on process env only. "
+        "Run this script via `uv run --script` with python-dotenv declared "
+        "in its PEP 723 metadata, or export the vars directly."
+    )
+# process.env / os.environ already takes precedence
+```
+
+`.env` files themselves are never shipped with a skill —
+`scripts/package_skill.py` excludes them (see the packager's `EXCLUDE_GLOBS`).
+Ship `.env.example` instead as a documentation template.
+
+## Documentation Requirements
+
+### .env.example
+Show required variables without values:
+
+```
+API_KEY=
+DATABASE_URL=
+DEBUG=false
+```
+
+### requirements.txt (Python) — conditional
+Ship a `requirements.txt` **only** when the "Legit local-dep exceptions" cases
+in [`./script-dependency-strategy.md`](./script-dependency-strategy.md) apply
+(offline user runtime, native/binary deps ephemeral runners handle poorly, org
+vendoring policy). When you do ship one, pin exactly and keep it minimal
+(≤2 deps):
+
+```
+requests==2.32.3
+python-dotenv==1.0.1
+```
+
+For the default path (no exception), invoke tools via `pipx run pkg==x.y.z`
+or `uvx --from 'pkg==x.y.z' cmd`, or declare deps inline via PEP 723 + `uv run`.
+
+### package.json (Node.js) — conditional
+Only ship a `package.json` under the same exception cases as `requirements.txt`.
+Otherwise call the tool via `npx -y pkg@x.y.z` at the invocation site.
+`node_modules/` is stripped by `scripts/package_skill.py` when packaging, so
+any skill that expects its bundled `node_modules/` at the user's runtime is
+broken by contract — declare deps at the invocation site instead. When a
+`package.json` is warranted, include scripts:
+
+```json
+{
+  "scripts": {
+    "test": "jest"
+  }
+}
+```
+
+## Manual Testing
+
+Before packaging, test with real use cases:
+
+```bash
+# Example: PDF rotation script
+python scripts/rotate_pdf.py input.pdf 90 output.pdf
+```
+
+Verify output matches expectations.
+
+## Error Handling
+
+- Clear error messages
+- Graceful failures
+- No silent errors
+- Exit codes: 0 success, non-zero failure