@rhize/skill-forge 0.2.0 → 0.3.0

package/dist/ingest-prompt.md

@@ -0,0 +1,211 @@
+# Skill Ingestion Pass
+
+You are running the deep decide/absorb pass on a skill that has just cleared the
+`skill-forge` quarantine → profile → safety scan → overlap-analysis gate. The gate already
+answered "is this safe to install?" — your job is the harder question: "given everything
+already in this skill set, what should actually be *done* with it?"
+
+You may be any coding agent (Claude Code, Codex CLI, Cursor, Windsurf, OpenCode, Gemini
+CLI, or another). Nothing below assumes a specific one. Use whatever file-reading,
+file-editing, and shell-command capabilities you have available.
+
+## 1. Find your target
+
+The absolute path to the skill you should evaluate is normally given directly in the
+message that invoked you — look for a path to a directory containing a `SKILL.md`.
+
+If no path was given directly, check the pending-ingestion queue instead:
+
+```
+~/.skill-forge/queue.json          # or $SKILL_FORGE_HOME/queue.json if that env var is set
+```
+
+Read it. If it doesn't exist yet, there is nothing queued — stop and say so. Otherwise it
+is a JSON object shaped like:
+
+```json
+{
+  "version": 1,
+  "entries": [
+    {
+      "id": "a1b2c3d4",
+      "source": "the original slug / git URL / local path the skill was installed from",
+      "sourceType": "skills.sh | git | local",
+      "installedPath": "final path after promote, or null if only held in quarantine",
+      "quarantinePath": "path to the quarantine sandbox this entry was gated from",
+      "gate": {
+        "license": "detected license string, or null",
+        "safetyVerdict": "pass | warn | block",
+        "safetyFindings": ["human-readable safety findings, one per string"],
+        "overlapTop": [{ "skill": "nearest-existing-skill-name", "score": 0.0 }],
+        "suggestedVerb": "DEFER | ABSORB | FORK | REJECT | WATCH | null"
+      },
+      "status": "pending | ingested | dismissed",
+      "createdAt": "ISO-8601 timestamp"
+    }
+  ]
+}
+```
+
+Pick the entry with `"status": "pending"` whose `installedPath` (or `quarantinePath`, if
+`installedPath` is `null`) matches your target. If several are pending, list them for the
+user and ask which to process, or work through them one at a time — don't silently drain
+the whole queue.
+
+If there is no matching queue entry at all (you were pointed straight at a skill directory
+with no CLI queue involved), that's fine — do the same evaluation, just skip the "close the
+entry" step at the end since there's nothing to close.
+
+## 2. Gather context
+
+- **Read the candidate skill**: its `SKILL.md` (frontmatter + body) and any scripts,
+  references, or templates it ships.
+- **Reuse the gate's findings** if you found a queue entry — `gate.safetyVerdict`,
+  `gate.safetyFindings`, `gate.license`, and `gate.overlapTop` were already computed by the
+  CLI. Don't re-run a safety or overlap scan on the same source; that's duplicate work the
+  gate already did.
+- **Survey the user's existing skill set** for anything that already covers similar ground
+  — same domain, same trigger conditions, overlapping capability. If the queue entry has
+  `gate.overlapTop`, start there; otherwise search the skill set yourself.
+
+## 3. Decide — pick exactly one verb
+
+Every candidate resolves to exactly one of five verbs. Forcing a single choice is
+deliberate: ambiguity is where bloat and licensing risk creep in.
+
+Inputs to weigh:
+1. **Overlap** with the nearest existing skill: low / medium / high.
+2. **Quality** of the candidate: structure, specificity, whether it explains *why* (not
+   just *what*), any test/eval coverage.
+3. **License** — classify it now, before forming an opinion (see §4).
+4. **Maintenance** — is the upstream source active, versioned, likely to keep changing?
+5. **Fit** — does it assume the same stack/conventions as the rest of the skill set, or
+   something foreign that would need translation?
+
+```
+                 LOW overlap            MEDIUM overlap          HIGH overlap
+HIGH quality   ┌──────────────────┐  ┌──────────────────┐  ┌──────────────────┐
+permissive     │ DEFER (keep it   │  │ FORK (re-skin to  │  │ ABSORB (patch the │
+license        │ as-is, point the │  │ house conventions)│  │ better parts into │
+               │ set at it)       │  │                   │  │ the near skill)   │
+               └──────────────────┘  └──────────────────┘  └──────────────────┘
+LOW quality    ┌──────────────────┐  ┌──────────────────┐  ┌──────────────────┐
+  or           │ WATCH (note it,  │  │ REJECT (or ABSORB │  │ REJECT (the set   │
+poor fit       │ revisit later)   │  │ one good part only)│ │ already does this │
+               │                  │  │                    │ │ better)           │
+               └──────────────────┘  └──────────────────┘  └──────────────────┘
+```
+
+**License overrides everything**: none-stated, copyleft entering a permissively-licensed
+set, or restrictive terms → default to REJECT or escalate to the user, regardless of
+quality or overlap. See §4.
+
+If the queue entry has a `gate.suggestedVerb`, treat it as a starting hypothesis from the
+overlap heuristic — not a verdict. Confirm or override it based on the fuller read you just
+did.
+
+### Verb definitions
+
+- **DEFER** — Adopt the candidate as-is; take nothing out of it into the existing set
+  beyond, at most, a one-line pointer from the nearest existing skill ("for X, see
+  `<candidate>`"). Best when the candidate is already high quality, actively maintained,
+  and re-implementing it would just be re-typing it.
+
+- **ABSORB** — Pull specific patterns, scripts, or reference material into an existing
+  skill. Use when one existing skill clearly owns this domain and the candidate has a
+  handful of genuinely better parts. Never absorb the whole thing wholesale — name the
+  exact pieces you took in your record (§6). If it looks like you want to absorb
+  everything, that's really a FORK.
+
+- **FORK** — Copy the candidate into a new skill of its own and re-skin it to match house
+  conventions (frontmatter, description style, stack assumptions, command namespace if
+  any). Use when the bones are good but it's a genuinely new capability (low overlap), or
+  the house style differs enough that a patch would be messier than a clean rewrite.
+  Justify choosing this over the lighter DEFER.
+
+- **REJECT** — Take nothing. Record why, so the candidate isn't silently re-evaluated
+  later. Common reasons: redundant with something already better, low quality, or a
+  license you can't accept.
+
+- **WATCH** — Don't adopt now, but don't forget it either. Leave a reference note
+  somewhere findable and record a "revisit later" marker. Use for promising-but-immature
+  candidates, or things worth citing without adopting.
+
+### Anti-patterns
+
+- Absorbing an entire skill "to be safe" — that's FORK with extra steps and no re-skin.
+- Forking when DEFER would do — if you'd copy it nearly verbatim and upstream is well
+  maintained, defer instead.
+- Skipping verification (§5) because the candidate "looks obviously fine."
+- Landing on two verbs at once (e.g. "ABSORB and FORK") — that means the overlap read in
+  step 2 was incomplete; go back and finish it.
+
+## 4. License triage
+
+Classify the detected license (from `gate.license`, a `LICENSE` file, or `SKILL.md`
+frontmatter) before you commit to a verb:
+
+| Class | Examples | Action |
+|---|---|---|
+| Permissive | MIT, Apache-2.0, BSD-2/3, ISC, CC0, Unlicense, public domain | OK to ABSORB/FORK. Keep attribution where the license requires it (Apache NOTICE, BSD copyright line). |
+| Attribution-required | CC-BY, MIT with an attribution clause | OK, but you must keep the copyright/attribution notice wherever the content ends up. |
+| Copyleft | GPL, AGPL, CC-BY-SA, MPL | Escalate to the user. Copyleft terms can spread into a permissively-licensed set. Default to DEFER (use without copying) or REJECT — don't ABSORB/FORK without explicit sign-off. |
+| None stated | No LICENSE file, no frontmatter license field | Escalate. Absence of a license means all rights are reserved by default. Default to REJECT or WATCH; ask the user before taking anything. |
+| Restrictive / proprietary | "All rights reserved", a custom EULA, "personal use only" | REJECT. Show the user the exact clause. |
+
+**Rule**: never ABSORB or FORK on a copyleft, none-stated, or restrictive license without
+showing the user the exact license text and getting explicit approval first. DEFER is
+usually fine regardless of license, since using an installed skill as-is isn't
+redistributing its source.
+
+## 5. Execute, then verify
+
+Carry out the verb from §3:
+- **ABSORB** — write the specific patterns/files/sections you're taking into the target
+  skill (patch it, don't replace it wholesale).
+- **FORK** — copy the candidate into a new skill directory and re-skin its frontmatter,
+  description, and any stack-specific assumptions to match the rest of the set.
+- **DEFER** — at most, add a one-line pointer from the nearest existing skill's
+  description. Nothing else changes.
+- **WATCH / REJECT** — no file changes to the skill set; just the record in §6.
+
+For ABSORB and FORK, verify before you call it done: exercise the absorbed/forked skill (or
+its scripts) enough to confirm it actually works in its new home and doesn't regress
+anything nearby it references or depends on. "It looked fine reading it" is not
+verification.
+
+## 6. Record the outcome
+
+Write a short record of what you decided and why. At minimum, capture:
+
+- Candidate name and source (slug/URL/path).
+- Upstream version or commit ref, if known (or "n/a").
+- License and its class from §4.
+- The verb you chose.
+- Target (which existing skill you patched, or the new skill's name, or "n/a").
+- What was actually taken — specific files/patterns, or "nothing".
+- Verification result, or "n/a" for WATCH/REJECT.
+- Your reasoning in one or two sentences.
+
+Where you put this record is up to the conventions of the project you're working in — a
+changelog, a provenance ledger, a commit message, or just a clear message back to the user.
+The one place it's *not* optional is the queue entry, if you found one in step 1.
+
+### Close the queue entry
+
+If you located a queue entry in step 1, update its `status` field:
+
+- `"ingested"` — once you've recorded the decision above, whatever the verb (including
+  REJECT and WATCH — "ingested" means *processed*, not *adopted*).
+- `"dismissed"` — if the user explicitly declined to have this entry processed at all.
+
+Never delete entries — the queue is the audit trail. To update it: read
+`~/.skill-forge/queue.json` (or `$SKILL_FORGE_HOME/queue.json`), find the entry by its `id`,
+change only its `status` field, and write the whole file back as JSON with two-space
+indentation and a trailing newline, leaving every other field untouched.
+
+## 7. Report back
+
+Close with a short summary for the user: which skill you evaluated, the verb you chose and
+why, what changed (or didn't), and whether the queue entry was closed. Keep it to a few
+sentences — the detailed record from §6 is where the full reasoning lives.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rhize/skill-forge",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "publishConfig": {
     "access": "public"
   },