feat: a trigger may inject an operator-authored skills directory (issue #60)

`run.skillsDir` names a directory of skills on the WORKER host, in the same
`<name>/SKILL.md` layout as `~/.pi/agent/skills`. Its contents are copied into
that trigger's jobs and layered between the serviced repo's own `.pi/skills` and
the deployment-wide overlay: repo > injected > overlay.

Until now `run.flow` could only name a flow that already existed, committed to
the target repo or baked into the overlay. So an operator could not run a flow
against a repo that has not adopted `.pi/skills/`, A/B two versions of a flow
across two triggers, or keep a private flow out of a public repo's history. The
overlay was the only operator-side path and it is per DEPLOYMENT; this is the
same capability at the granularity the decision actually has.

COPIED, NOT MOUNTED, and the mount count is the weakest of the three reasons.

The copy is the PIN. `:ro` bounds the container, not the host, and pi reads a
skill's body on demand through the read tool, so under a live bind an operator
editing their skills directory would change the instructions of a job already
running. Copying gives the injected tier the property INT-CONTAINER-JOB-INPUTS
cites for materialising `.pi/` at a fixed sha: the agent cannot be handed a
moving target.

It also answers symlinks once, on the side that can. loadSkillsFromDirInternal
follows both file and directory links, so under a mount a directory symlink at
`/` would turn skill discovery into a walk of the container filesystem, and one
into `/workspace` would alias repo-controlled content into the operator-trusted
tier. The host-side copier refuses links outright.

And it adds no mount. CONST-ISOLATION-CONTAINER-PER-JOB's acceptance ENUMERATES
them, and DES-OPERATOR-GLOBAL-OVERLAY already refused a mount for staged
packages on exactly that trade, so this entry can borrow the argument the
2026-07-31 /session row explicitly could not. A job carrying injected skills has
a docker argv byte-identical to one without, and there is a test that says so.

Precedence is enforced twice, because once is not enough: by path order in
additionalSkillPaths, and again in skillsOverride's protected roots, since pi
puts a staged package's skill paths first no matter where we list the package.
The exact deepEqual on PROTECTED_SKILL_ROOTS is updated rather than loosened.
The middle tier's position is argued on specificity, not trust: "for THIS
trigger" is narrower than "for this deployment", and both are the operator's own.

Validated as a non-empty untrimmed string in triggers.mjs and NO FURTHER, which
is two deliberate omissions. Existence is not checked there because both
services parse the file and the receiver may run on another host (run.folder's
split). Absoluteness is not either, and that one is subtler: path.isAbsolute is
OS-dependent, so a shared check would let a Windows worker and a Linux receiver
disagree about the same reviewed file. The worker enforces both where the answer
is knowable, at boot for cron and pre-spend per job for every kind.

The value never reaches /job/event.json. It rides at JOB level and never inside
`trigger`, which is what the event subset is built from, because a worker-host
path in an agent-readable file is what prepare-local's basename(folder)
restraint already exists to prevent. It is in no log line either: the injection
logs counts only.

Gap 5 is recorded rather than built. An injected flow already fails closed at
the ai-trigger gate, which reads the repo's object store at a pre-agent sha and
finds no-skill. Two tests pin it, DES-AI-TRIGGER-FLOW-GATE states it, and doctor
warns about the corollary an operator cannot otherwise discover: an injected
SKILL.md carrying `ai-trigger: allow` is never read. Residual OQ-022.

Doctor dry-runs the REAL copier against each named directory rather than
reimplementing its rules, because a second agreeing-by-hand checker is how
doctor comes to report green on a directory the worker then refuses.

REQ-PER-TRIGGER-SKILLS and DES-TRIGGER-SKILLS-COPIED-NOT-MOUNTED are NEW, the
latter recording four rejected alternatives including the per-trigger :ro bind
the issue originally sketched and an env var naming the injected root.
INT-TRIGGERS-FILE-CONTRACT, INT-CONTAINER-JOB-INPUTS, INT-SDK-SESSION-OPTIONS,
INT-RUN-HISTORY-FILE-CONTRACT, REQ-GLOBAL-PI-OVERLAY, DES-AI-TRIGGER-FLOW-GATE:
AMENDED. OQ-022 added.

CONST-ISOLATION-CONTAINER-PER-JOB, INT-CONTAINER-RUNTIME-CONTRACT,
CONST-NO-CONTEXT-FILES-MANDATORY, CONST-ISSUE-TEXT-IS-DATA,
CONST-PERSONA-IN-CACHED-PREFIX, CONST-BUDGET-BEFORE-TOKENS,
CONST-RETRY-INFRA-ONLY, CONST-TOKEN-SCOPED-PER-JOB,
REQ-UPSTREAM-CONTRACT-TESTS, REQ-RESURRECTABLE-SANDBOX: UNCHANGED, checked.

Mutation-checked: dropping the injected root from protectedSkillRoots turns the
package-shadow test red, and dropping it from additionalSkillPaths turns both
precedence tests red.

2053 tests, 0 failures, 0 skipped in the CI posture.

Signed-off-by: Rob Boerman <robboerman@live.nl>

Author: edgehero

README.md

@@ -172,6 +172,12 @@ or what it costs):
   ([`docs/job-image.md`](docs/job-image.md)).
 - `"packages": false` opts one trigger out of the staged third-party pi packages, which is also how a
   workflow extension is withheld from one flow ([`docs/workflows.md`](docs/workflows.md)).
+- `"skillsDir"` points at a directory of skills on the worker host, in the same `<name>/SKILL.md` layout
+  as your own `~/.pi/agent/skills`. They are copied into that trigger's jobs and layered under the repo's
+  own `.pi/skills` and over the global overlay, so a repo skill of the same name still wins. Use it to run
+  a flow against a repo that has not adopted `.pi/skills/` at all, to A/B two versions of a flow across two
+  triggers, or to keep a private flow out of a public repo's history
+  ([`docs/global-pi-overlay.md`](docs/global-pi-overlay.md)).
 - `"replicas": 2` (GitHub only) races independent sandboxes on the same event and opens one PR per
   replica. Each replica spends its own budget slot ([`docs/replicas.md`](docs/replicas.md)).
 - `"resume": true` continues the session that opened the PR ([`docs/sessions.md`](docs/sessions.md)).

SECURITY.md

@@ -247,8 +247,9 @@ Stated openly rather than discovered later:
   flow.** A trigger's `run.image` names the container its jobs run in; absent, they run `PI_JOB_IMAGE`.
   Whichever it is, the *isolation* holds: `--cap-drop=ALL`, `--security-opt no-new-privileges`, the
   memory/CPU/pids limits, `/job` read-only, the closed env allowlist and the mount set (four mounts, five
-  once `run.resume` is armed) are all built by the worker's `docker run` argv, so nothing an image contains
-  can weaken them. **Non-root is not in that argv.** It is `USER pi` in the image itself, as the trust table
+  once `run.resume` is armed, and `run.skillsDir` adds none: its skills are copied into the per-job dir and
+  ride the `/job` mount that already exists) are all built by the worker's `docker run` argv, so nothing an
+  image contains can weaken them. **Non-root is not in that argv.** It is `USER pi` in the image itself, as the trust table
   above says, and that is exactly why an unconformant image can lose it: `docs/job-image.md` requires a
   non-root runtime user with a writable agent dir, and nothing here verifies that the image you named
   honours it. What is **not** checked is the image's contents, and every way that can be wrong fails

admin/src/read-model.mjs

@@ -692,6 +692,10 @@ export function normalizeTriggerForDisplay(entry) {
   const flow = typeof run.flow === "string" ? run.flow : null;
   const packages = run.packages !== false;
   const image = typeof run.image === "string" && run.image.trim() !== "" ? run.image : null;
+  // The trigger's injected skills dir (REQ-PER-TRIGGER-SKILLS, issue #60). Carried on all four kinds like
+  // `image`, and shown for the same reason: which skills a job loads IS what the agent can do. `null` is
+  // the none sentinel, matching this function's own convention.
+  const skillsDir = typeof run.skillsDir === "string" && run.skillsDir.trim() !== "" ? run.skillsDir : null;
   // An opt-IN, so `=== true` and not `!== false` -- the opposite test from `packages` directly above, and
   // the difference is the whole point. Getting this polarity wrong is the defect 0.1.4 shipped a fix for:
   // the riskiest triggers rendered with no badge and no warning, quiet exactly where the risk was.
@@ -716,12 +720,13 @@ export function normalizeTriggerForDisplay(entry) {
         model: typeof run.model === "string" ? run.model : null,
         packages,
         image,
+        skillsDir,
         resume,
       };
     case "label":
-      return { type: "label", any: normalizeSelector(on.any), all: normalizeSelector(on.all), none: normalizeSelector(on.none), flow, packages, image, resume, replicas, forge };
+      return { type: "label", any: normalizeSelector(on.any), all: normalizeSelector(on.all), none: normalizeSelector(on.none), flow, packages, image, skillsDir, resume, replicas, forge };
     case "comment":
-      return { type: "comment", phrase: typeof on.phrase === "string" ? on.phrase : null, flow, packages, image, resume, replicas, forge };
+      return { type: "comment", phrase: typeof on.phrase === "string" ? on.phrase : null, flow, packages, image, skillsDir, resume, replicas, forge };
     case "pull_request":
       return {
         type: "pull_request",
@@ -732,6 +737,7 @@ export function normalizeTriggerForDisplay(entry) {
         flow,
         packages,
         image,
+        skillsDir,
         resume,
         replicas,
         forge,

admin/src/render.mjs

@@ -175,22 +175,28 @@ function triggerLine(t) {
   // A trigger that PERSISTS the agent's working history to disk says so. Without this badge it renders
   // identically to one that does not, which is the defect 0.1.4 fixed for [packages] arriving in a new
   // field -- and a transcript is a bigger disclosure than staged packages are.
+  // A trigger whose jobs load operator-authored skills from the host says which directory (issue #60).
+  // Same doctrine as [resume] and [image]: it must never render the same as one that does not, because
+  // choosing the skills IS choosing what the agent can do. The BASENAME only, so the line stays skimmable;
+  // the full path lives in the trigger detail view, where the panel is the operator's own session on their
+  // own host and a path discloses nothing new.
+  const skl = t?.skillsDir ? `  [skills ${String(t.skillsDir).split(/[\\/]/).filter(Boolean).pop()}]` : "";
   const res = t?.resume === true ? "  [resume]" : "";
   // A trigger that turns one delivery into N paid runs says so (REQ-REPLICA-RUNS). Same class of badge as
   // [resume]: not a preference an operator can skim past, but the field that multiplies the bill. Absent on
   // an unreplicated trigger, appended last, so every existing line is byte-identical.
   const rep = t?.replicas > 1 ? `  [x${t.replicas}]` : "";
   switch (t?.type) {
     case "cron":
-      return `cron  ${t.id ?? "-"}  ${t.pattern ?? "-"} → ${t.folder ?? "-"}/${flow}${forge}${pkgs}${img}${res}${rep}`;
+      return `cron  ${t.id ?? "-"}  ${t.pattern ?? "-"} → ${t.folder ?? "-"}/${flow}${forge}${pkgs}${img}${skl}${res}${rep}`;
     case "label":
-      return `label  ${ruleClauses(t) || "(no selector)"} → ${flow}${forge}${pkgs}${img}${res}${rep}`;
+      return `label  ${ruleClauses(t) || "(no selector)"} → ${flow}${forge}${pkgs}${img}${skl}${res}${rep}`;
     case "comment":
-      return `comment  "${t.phrase ?? "-"}" → ${flow}${forge}${pkgs}${img}${res}${rep}`;
+      return `comment  "${t.phrase ?? "-"}" → ${flow}${forge}${pkgs}${img}${skl}${res}${rep}`;
     case "pull_request": {
       const clauses = ruleClauses(t);
       const action = `action[${(t.action ?? []).join(",")}]`;
-      return `pull_request  ${action}${clauses ? ` ${clauses}` : ""} → ${flow}${forge}${pkgs}${img}${res}${rep}`;
+      return `pull_request  ${action}${clauses ? ` ${clauses}` : ""} → ${flow}${forge}${pkgs}${img}${skl}${res}${rep}`;
     }
     default:
       return "(unknown trigger)";

admin/test/read-model.test.mjs

@@ -448,10 +448,10 @@ test("readTriggers normalizes each on.type into its discriminated display record
   const res = readTriggers({ triggersPath: "/x/triggers.json", fs: fakeFs(files) });
   // Every entry omits `run.packages`, and packages is an OPT-OUT -- so all four normalize to `true`.
   assert.deepEqual(res.triggers, [
-    { type: "cron", id: "nightly", pattern: "0 3 * * *", folder: "/srv/p", flow: "tidy", model: null, packages: true, image: null, resume: false },
-    { type: "label", any: ["pi:frontend"], all: [], none: ["wontfix"], flow: "frontend-fix", packages: true, image: null, resume: false, replicas: null, forge: "github" },
-    { type: "comment", phrase: "@pi", flow: "fix", packages: true, image: null, resume: false, replicas: null, forge: "github" },
-    { type: "pull_request", action: ["labeled"], any: ["pi:review"], all: [], none: [], flow: "review", packages: true, image: null, resume: false, replicas: null, forge: "github" },
+    { type: "cron", id: "nightly", pattern: "0 3 * * *", folder: "/srv/p", flow: "tidy", model: null, packages: true, image: null, skillsDir: null, resume: false },
+    { type: "label", any: ["pi:frontend"], all: [], none: ["wontfix"], flow: "frontend-fix", packages: true, image: null, skillsDir: null, resume: false, replicas: null, forge: "github" },
+    { type: "comment", phrase: "@pi", flow: "fix", packages: true, image: null, skillsDir: null, resume: false, replicas: null, forge: "github" },
+    { type: "pull_request", action: ["labeled"], any: ["pi:review"], all: [], none: [], flow: "review", packages: true, image: null, skillsDir: null, resume: false, replicas: null, forge: "github" },
   ]);
 });
 
@@ -516,7 +516,7 @@ test("readTriggers skips an entry that is not a usable { on, run } object (viewe
     }),
   };
   const res = readTriggers({ triggersPath: "/x/triggers.json", fs: fakeFs(files) });
-  assert.deepEqual(res.triggers, [{ type: "label", any: ["pi:frontend"], all: [], none: [], flow: "frontend-fix", packages: true, image: null, resume: false, replicas: null, forge: "github" }]);
+  assert.deepEqual(res.triggers, [{ type: "label", any: ["pi:frontend"], all: [], none: [], flow: "frontend-fix", packages: true, image: null, skillsDir: null, resume: false, replicas: null, forge: "github" }]);
 });
 
 test("readTriggers returns { invalid } when there is no triggers array", () => {

docs/global-pi-overlay.md

@@ -34,12 +34,18 @@ Four tiers, most-trusted first; each refines but never removes the one above:
 | 1. Safety floor | baked `HARD_RULES.md` (from **whichever image the trigger names** — `run.image`) | image, root-owned | no (immutable) |
 | 2a. **Global overlay** | `PI_GLOBAL_PI_DIR` → `/opt/pi-global:ro` | **operator, deploy-time** | re-run `import-pi` |
 | 2b. **Staged packages** | `<overlay>/packages/<dir>` — per-trigger opt-out | **third-party**, operator-pinned | re-run `import-pi --with-packages` |
+| 2c. **Injected skills** | a trigger's `run.skillsDir`, copied per job into `/job/trigger-skills` | **operator, per trigger** | edit `triggers.json` |
 | 3. Per-repo `.pi/` | repo's committed `.pi/` (default-branch SHA) | trusted-by-merge | per PR |
 | 3b. Repo `AGENTS.md` + `.pi/extensions` | the checkout, which is always the **default-branch SHA** | trusted-by-merge; **extensions execute** | per PR |
 | 4. Task/issue text | the webhook / CLI input | **adversarial — never instructions** | — |
 
 - **Skills**: repo skills are listed **first**, so a repo skill **overrides** a global one of the same name
   (pi is first-path-wins); names that don't collide all load.
+  A trigger's own `run.skillsDir` sits **between** the two: repo beats injected beats global. "For this
+  trigger" is a narrower statement than "for this deployment", so it refines the overlay, and the repo's
+  own committed skills refine both. Those skills are **copied** per job rather than mounted, which is what
+  stops an edit to your skills directory from changing a job that is already running, and it means the
+  feature adds no mount to any container.
 - **Persona**: the assembled prompt is `guardrails → outbox protocol → global persona → repo persona`. The
   floor is always first and cannot be removed; global is your baseline; the repo's `.pi/APPEND_SYSTEM.md` is
   most specific. The outbox tier is **local jobs only**: it is read only when the `/outbox` mount exists, so

docs/workflows.md

@@ -15,6 +15,7 @@ skills, or a pi extension that orchestrates them.
 | **skill** | pi's unit of instruction; a flow is just the entry one. The whole directory travels, not only `SKILL.md` | the target repo, or the overlay |
 | **workflow extension** | a pi extension that chains skills into stages, with its own state and routing | a third party, staged by you |
 | **staged package** | the pinned directory a workflow extension lives in, inside the global overlay | `import-pi --with-packages` |
+| **injected skills** | a directory of skills on the worker host that one trigger's jobs load, via `run.skillsDir` | you, in a reviewed file |
 
 ## How a workflow gets triggered
 
@@ -38,7 +39,9 @@ Four properties of that chain decide what is possible inside it.
 
 **`run.flow` is the only entry point.** There is no `run.workflow` and there is not going to be one. Which
 stages run is a property of the repo's own skill, which the repo changes by merging; the trigger stays a
-reviewed pairing of an event with a flow name. That split is the same one the whole trigger schema rests
+reviewed pairing of an event with a flow name. `run.skillsDir` does not change that and is worth being
+precise about why: it supplies **where a flow comes from**, never **which stages run**. The trigger still
+names one flow, and what that flow does is still the skill's business. That split is the same one the whole trigger schema rests
 on: this service decides *when* and *in what box*, the repo decides *what*.
 
 **A job is not an interactive session.** The runner assembles one prompt, calls pi once, and reads the exit

image/runner/run-job.mjs

@@ -7,7 +7,7 @@ import {
 	SettingsManager,
 } from "@earendil-works/pi-coding-agent";
 import { assertPackagePathsExist, assertSessionMountReady, enforceOfflineMode, parseRunnerEnv } from "./src/config.mjs";
-import { buildLoadedResourceLoader, GLOBAL_PI_DIR, JOB_PI_DIR, WORKSPACE } from "./src/loader.mjs";
+import { buildLoadedResourceLoader, GLOBAL_PI_DIR, JOB_PI_DIR, TRIGGER_SKILLS_DIR, WORKSPACE } from "./src/loader.mjs";
 import {
 	captureTerminal,
 	classifyThrow,
@@ -127,7 +127,7 @@ async function main() {
 		// The protected roots are derived from the loader's own constants rather than written out
 		// again, so a change to where the worker materialises .pi/ cannot leave this check guarding
 		// paths that no longer exist.
-		const protectedRoots = [`${JOB_PI_DIR}/skills`, `${GLOBAL_PI_DIR}/skills`];
+		const protectedRoots = [`${JOB_PI_DIR}/skills`, TRIGGER_SKILLS_DIR, `${GLOBAL_PI_DIR}/skills`];
 		const shadowed = findShadowedSkills(diagnostics, { packageRoots: cfg.packages, protectedRoots });
 		if (shadowed.length > 0) {
 			// The winner is read off the LOADED skill, not off pi's pre-override diagnostic: the

image/runner/src/loader.mjs

@@ -14,6 +14,21 @@ export const OUTBOX_MOUNT = "/outbox";
 /** Read-only mount the worker materialises the project's .pi/ into, from the default-branch SHA. */
 export const JOB_PI_DIR = "/job/pi";
 
+/**
+ * Where a trigger's INJECTED skills land (REQ-PER-TRIGGER-SKILLS, issue #60). Operator-authored, copied
+ * per job by the worker from the host directory `run.skillsDir` names, and reaching us on the /job:ro
+ * bind that already exists -- this feature adds NO mount, which is what keeps
+ * CONST-ISOLATION-CONTAINER-PER-JOB's mount enumeration untouched.
+ *
+ * Spelled `trigger-skills` and NOT `skills`: `/job/skills` beside `/job/pi/skills` would be two roots one
+ * letter apart in a precedence list, which is how the wrong one gets edited.
+ *
+ * The worker writes the same last segment from its own side (TRIGGER_SKILLS_SUBDIR in prepare.mjs); it is
+ * not in this container and this file is not on that host, so the duplication is forced. CHANGE BOTH, IN
+ * THE SAME COMMIT -- the same discipline ADMIN_EXTENSION_RE carries, and each side pins the literal.
+ */
+export const TRIGGER_SKILLS_DIR = "/job/trigger-skills";
+
 /**
  * Read-only mount of the operator's global pi overlay (REQ-GLOBAL-PI-OVERLAY): custom models, global
  * skills, and a global persona from the operator's own ~/.pi/agent, present only when configured. It is
@@ -217,6 +232,7 @@ export function buildResourceLoader({
 	guardrailsPath = GUARDRAILS_PATH,
 	jobPiDir = JOB_PI_DIR,
 	globalPiDir = GLOBAL_PI_DIR,
+	triggerSkillsDir = TRIGGER_SKILLS_DIR,
 	outboxMount = OUTBOX_MOUNT,
 	outboxProtocolPath = OUTBOX_PROTOCOL_PATH,
 	// ON, matching the runtime posture (REQ-GLOBAL-PI-OVERLAY): the operator staged that dir themselves,
@@ -243,7 +259,7 @@ export function buildResourceLoader({
 	// The roots a staged package may never take a skill name from. Both are listed unconditionally: a
 	// root that is not mounted contributes no skill to protect, so gating it would only add a way to
 	// forget one.
-	const protectedSkillRoots = [`${jobPiDir}/skills`, globalSkills];
+	const protectedSkillRoots = [`${jobPiDir}/skills`, triggerSkillsDir, globalSkills];
 	// Roots the recursion guard can NAME in its log line, most specific FIRST: a staged package sits
 	// under the overlay, so an overlay-first list would report a package's extension as the operator's.
 	// The workspace is last because it is the catch-all -- a discovered repo extension is anywhere in it.
@@ -263,7 +279,18 @@ export function buildResourceLoader({
 		// second path and take the mount out of force on a first-path-wins collision. See the docstring.
 		noSkills: true,
 		// Repo path FIRST so a repo skill overrides a global one of the same name (first-path-wins).
-		additionalSkillPaths: [`${jobPiDir}/skills`, ...(existsSync(globalSkills) ? [globalSkills] : [])],
+		// then the trigger's INJECTED skills, then the deployment-wide overlay: repo > injected > overlay
+		// (REQ-GLOBAL-PI-OVERLAY, REQ-PER-TRIGGER-SKILLS). The middle tier is the narrower operator statement,
+		// "for THIS trigger", so it refines the overlay and is refined by the repo -- the same most-specific-
+		// wins ordering the persona layers use. The order here is OURS: under noSkills, pi builds skillPaths as
+		// mergePaths(cliEnabledSkills, additionalSkillPaths), mergePaths preserves order, and loadSkills keeps
+		// the first of each name. existsSync-gated like the overlay, because an absent path becomes a permanent
+		// "skill path does not exist" diagnostic, and an always-populated channel cannot detect anything.
+		additionalSkillPaths: [
+			`${jobPiDir}/skills`,
+			...(existsSync(triggerSkillsDir) ? [triggerSkillsDir] : []),
+			...(existsSync(globalSkills) ? [globalSkills] : []),
+		],
 		// Global overlay extensions load whenever the dir is present -- staging them IS the operator's
 		// decision, so a second arming step was friction rather than safety. PI_GLOBAL_ALLOW_EXTENSIONS=0
 		// is the opt-out, and any other value is refused at config load so a typo cannot silently mean

image/runner/src/packages.mjs

@@ -8,8 +8,14 @@
  */
 import { basename, dirname } from "node:path";
 
-/** Roots whose skills a staged package must never be able to replace. */
-export const PROTECTED_SKILL_ROOTS = ["/job/pi/skills", "/opt/pi-global/skills"];
+/**
+ * Roots whose skills a staged package must never be able to replace, most specific FIRST.
+ *
+ * The middle entry is a trigger's injected skills (REQ-PER-TRIGGER-SKILLS, issue #60), and it sits
+ * between the repo and the overlay for the same reason it does in additionalSkillPaths: "for THIS
+ * trigger" is a narrower operator statement than "for this deployment", and narrower wins.
+ */
+export const PROTECTED_SKILL_ROOTS = ["/job/pi/skills", "/job/trigger-skills", "/opt/pi-global/skills"];
 
 /**
  * The admin extension, BY NAME -- a deliberate duplicate of `ADMIN_RE` in worker/src/import-pi.mjs.