@rhize/skill-forge 0.1.0

package/LICENSE

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

@@ -0,0 +1,218 @@
+# skill-forge
+
+**The supply-chain gate for agent skills.**
+
+Status: pre-release (built 2026-07-11)
+
+> This project is unrelated to the [`skillforge`](https://www.npmjs.com/package/skillforge)
+> package on npm, which is a Claude Skills *evaluation* framework. `skill-forge` (this package,
+> hyphenated) is a supply-chain security gate for skill *installation* — see the [FAQ](#faq).
+
+## Why
+
+Agent skills (Claude Code skills, and the equivalent extension formats emerging in Cursor and
+Codex) are now distributed the way npm packages were a decade ago: a public registry, a one-line
+install command, and no vetting step in between. skills.sh alone lists 600k+ skills. A single
+`npx skills@latest add owner/name` drops arbitrary third-party instructions, scripts, and tool
+bindings directly into a working agent's context and file system — with the same trust model as
+copy-pasting a shell script from a stranger.
+
+skill-forge does not replace that install command; it wraps it. Every candidate skill is routed
+through **quarantine → profile → safety scan → overlap analysis → report → an explicit
+promote/hold/reject decision**, before it is allowed anywhere near your working skill set.
+
+## Quickstart
+
+```bash
+npx skill-forge add <owner>/<skill-name>
+```
+
+One command runs the whole gate:
+
+1. Installs the source into an isolated quarantine sandbox — never your live skill set.
+2. Profiles it: name, version, license, structure, declared MCP/tool dependencies.
+3. Runs the safety gate (a built-in deny-pattern ruleset, always; SkillSpector too, if installed).
+4. Runs overlap analysis against your configured skill set, if one is configured.
+5. Prints a report and asks you to **promote**, **hold**, or **reject** the candidate.
+
+No configuration is required for a first run: skill-forge defaults to `<cwd>/.claude/skills` as
+its promotion target and `~/.skill-forge/quarantine` as its sandbox. See
+[docs/configuration.md](docs/configuration.md) to change either.
+
+To gate a skill without installing it (always cleans up afterward):
+
+```bash
+npx skill-forge scan <owner>/<skill-name>
+```
+
+`<source>` accepts a `skills.sh` `owner/name` slug, a git URL (`https://...`, `git@...`, or
+anything ending in `.git`), or a local filesystem path.
+
+## Commands
+
+```
+skill-forge add <source> [options]     Quarantine-install a skill and run it through the gate
+skill-forge scan <source>              Gate a skill without installing it (always cleans up)
+skill-forge list                       List skills currently held in quarantine
+skill-forge status                     Show configuration and quarantine summary
+```
+
+### `add`
+
+```bash
+skill-forge add owner/name
+skill-forge add https://github.com/owner/repo.git --target ./.claude/skills
+skill-forge add ./local-skill-dir --yes
+skill-forge add owner/name --json
+skill-forge add owner/name --yes --ingest
+```
+
+Installs the source into a quarantine sandbox, then runs it through the gate: profile → safety
+scan → overlap analysis against the configured skills root (Pro) → report. Nothing touches the
+target skills root until you decide.
+
+| Option | Effect |
+|---|---|
+| *(none)* | Prompts you to **promote**, **hold**, or **reject** the candidate. |
+| `-y, --yes` | Skips the prompt and honors the gate verdict: a `block` safety verdict is rejected (process exits nonzero); anything else (`pass`/`warn`) is promoted. |
+| `-t, --target <dir>` | Skills root to promote into. Defaults to the config's `skillsRoots[0]`. |
+| `--json` | Prints the gate result (profile, safety findings, overlap) as JSON instead of the terminal report box. |
+| `--ingest` | Pro. After a successful promote, hands off to Claude — see [Claude handoff](#claude-handoff---ingest). |
+
+With a valid Pro license, a promoted skill gets a provenance entry appended to
+`<target>/SOURCES.md`, and every promote or hold decision is recorded to
+`~/.skill-forge/queue.json` (or `$SKILL_FORGE_HOME/queue.json`) — see
+[`docs/queue-schema.md`](docs/queue-schema.md) for the entry schema. A reject writes neither —
+nothing is left behind to record. Without a license, `add` prints a short upgrade notice in place
+of the ledger entry and queue write instead, and otherwise completes normally.
+
+### `scan`
+
+```bash
+skill-forge scan owner/name
+```
+
+Runs the same gate pipeline as `add` (profile → safety → overlap → report) but never promotes
+anything — the quarantine sandbox is always cleaned up afterward, on success or failure. Exits
+nonzero when the safety verdict is `block`.
+
+### `list` / `status`
+
+`list` shows what's currently held in quarantine (installed via `add`, answered "hold", not yet
+promoted or rejected). `status` shows the resolved configuration (skills roots, quarantine dir,
+strictness) plus a count of held entries.
+
+## Free vs. Pro
+
+| Capability | Free | Pro |
+|---|:---:|:---:|
+| Quarantine install (skills.sh slug / git / local path) | ✓ | ✓ |
+| Profile (name, version, license, structure, MCP/tool deps) | ✓ | ✓ |
+| Safety gate — built-in ruleset + SkillSpector shell-out | ✓ | ✓ |
+| Terminal report + `--json` | ✓ | ✓ |
+| Promote / hold / reject decision | ✓ | ✓ |
+| Overlap analysis against your configured skill set | | ✓ |
+| Provenance ledger (`SOURCES.md` audit trail) | | ✓ |
+| Pending-ingestion queue + `--ingest` Claude handoff | | ✓ |
+| Set-level organizer (capability registry, redundancy, dependency graph) | | ✓ |
+
+Free is the complete safety gate on its own — quarantine, profile, safety scan, and an explicit
+promote/reject decision, with nothing held back. Pro is the curation layer on top: whether a new
+candidate duplicates something you already have, and an ongoing provenance record across your
+whole skill set rather than a single install-time decision.
+
+**Current build status:** this is a pre-release build. Overlap analysis, the provenance ledger,
+and the pending-ingestion queue / `--ingest` handoff are gated on a valid license
+(`SKILL_FORGE_LICENSE` env var or `config.json`'s `licenseKey`, verified offline — see
+[docs/pro.md](docs/pro.md)); without one, `add` prints a short upgrade notice in place of each and
+otherwise completes normally. The set-level organizer and the skills.sh partner-audit enrichment
+are not yet exposed by any CLI command, licensed or not. See [docs/pro.md](docs/pro.md) for the
+per-feature implementation status.
+
+## Security model
+
+- **Quarantine-first.** Every source — skills.sh slug, git URL, or local path — is installed into
+  an isolated sandbox (`~/.skill-forge/quarantine/<id>/`) before anything is inspected. Nothing
+  reaches your working skill set without an explicit promote decision.
+- **Built-in safety ruleset, always on, fully offline.** A deny-pattern scan (curl/wget-into-shell,
+  base64-obfuscated exec, reverse shells, recursive force-delete, credential-file access/exfil,
+  dynamic eval, `shell=True` subprocess, persistence via shell rc files or cron, `sudo` usage) runs
+  against every candidate with no external dependency and no network call. See
+  [docs/gate-policy.md](docs/gate-policy.md) for the full rule table.
+- **Block on HIGH/CRITICAL.** Any finding at `HIGH` or `CRITICAL` severity blocks the candidate
+  outright (verdict `block`); a lower-severity finding produces `warn`; a clean scan is `pass`.
+  `--yes` honors this: `block` is rejected automatically.
+- **SkillSpector, when installed.** If [SkillSpector](https://github.com/NVIDIA/SkillSpector)
+  (Apache-2.0) is on `PATH`, skill-forge shells out to it (`--no-llm` by default, so scanned skill
+  content is never sent to an external LLM provider) and merges its findings into the same report.
+  Purely additive — its absence never blocks the gate.
+- **skills.sh partner audits — implemented, not yet wired into the CLI pipeline.** skill-forge
+  ships a client for skills.sh's documented `/api/v1/skills/audit` endpoint (partner verdicts from
+  Socket, Snyk, Gen Agent Trust Hub, Runlayer, ZeroLeaks), gated on a user-supplied
+  `VERCEL_OIDC_TOKEN`. The client exists (`src/gate/skillsSh.ts`) but `add`/`scan` do not call it
+  yet in this build — see [docs/gate-policy.md](docs/gate-policy.md) for current status.
+
+## Claude handoff (`--ingest`)
+
+`skill-forge` deliberately doesn't try to decide *what to extract* from a skill worth adopting —
+that deeper judgment (which patterns to keep, whether to absorb into an existing skill vs. fork a
+new one, verifying the result beats baseline) belongs to the companion Claude Code skill
+`rhize-skill-forge`, invoked via its `/rhize-meta:forge-ingest` slash command.
+
+```bash
+skill-forge add owner/name --yes --ingest
+```
+
+- If a `claude` binary is on `PATH`, skill-forge spawns it (inheriting your terminal) running
+  `claude -p "/rhize-meta:forge-ingest <installedPath>"`.
+- If not, skill-forge prints that exact command for you to run yourself.
+- Every promote or hold is recorded to the pending queue (`~/.skill-forge/queue.json`) regardless
+  of `--ingest` — nothing is lost if you skip the handoff. A later
+  `/rhize-meta:forge-ingest` run with no argument drains the whole pending queue.
+
+## Configuration
+
+Config lives at `~/.skill-forge/config.json` (or `$SKILL_FORGE_HOME/config.json`):
+
+```json
+{
+  "skillsRoots": ["/path/to/.claude/skills"],
+  "quarantineDir": "/path/to/quarantine",
+  "strictness": "block-high"
+}
+```
+
+Missing keys fall back to defaults (`skillsRoots: ["<cwd>/.claude/skills"]`). Full field reference,
+including current caveats, in [docs/configuration.md](docs/configuration.md).
+
+## FAQ
+
+**Is this related to the `skillforge` npm package?**
+No. [`skillforge`](https://www.npmjs.com/package/skillforge) is a Claude Skills *evaluation*
+framework — it tests whether a skill performs well. `skill-forge` (this package, hyphenated) is a
+supply-chain security gate for skill *installation* — it decides whether a skill is safe and
+non-redundant before it ever runs. Same neighborhood, different problem, name collision only.
+
+**Does skill-forge replace `npx skills@latest add`?**
+No, it wraps it. `add` uses the same install mechanisms (skills.sh, git, local copy) but stages
+the result in a quarantine sandbox and runs it through the gate before anything touches your live
+skill set.
+
+**What happens if I never configure a skills root?**
+`add`/`scan` still run — profiling and the safety scan work on any candidate independent of a
+skills root. Overlap analysis is skipped (a message goes to stderr, it isn't fatal) if
+`skillsRoots[0]` doesn't resolve to a directory containing existing skills.
+
+**Does the safety gate call out to the network?**
+The built-in ruleset is fully offline. SkillSpector, if installed, runs with `--no-llm` by default.
+See [docs/gate-policy.md](docs/gate-policy.md).
+
+**Is there a license key or activation step?**
+An offline-verified license key exists (`SKILL_FORGE_LICENSE` env var or `config.json`'s
+`licenseKey`), but there's no `license`/`activate` CLI command — you set the key via config or
+environment, not a command. It gates overlap analysis, the provenance ledger, and the
+pending-ingestion queue / `--ingest` handoff. See [docs/pro.md](docs/pro.md) for details.
+
+## License
+
+MIT — see [LICENSE](LICENSE).