Skip to content

armgit / qm

Public Imported from GitHub
0

Multiplayer agent harness for work.

Read published skill sources without starting sandboxes (#1280)

Regan Belldfdde0bc89e3
diff --git a/docs/skill-registry.md b/docs/skill-registry.md
index 2c164b0ec..17e5c7149 100644
--- a/docs/skill-registry.md
+++ b/docs/skill-registry.md
@@ -70,3 +70,20 @@ commit.
The skills are governed store records, visible and auditable on the admin Skills page, rather than
ungoverned files on each box.
+
+## Reading published skills
+
+The skill index advertises `skill://<name>/SKILL.md` for the agent's `read` tool.
+These read-only references resolve the currently visible, screened published skill
+without creating or waking a sandbox. Relative manifest files can be read at
+`skill://<name>/<relative-path>`. Unavailable skills and invalid paths return no file.
+
+Shell commands still use `skills/<name>/...`. Filesystem reads and commands referencing a
+skill materialize its assets when needed, including pack files under the path named
+in the skill body. Ordinary filesystem reads and writes
+retain their existing behavior, including local edits; they are distinct from the
+published source. Publish changes through the skill API to update that source.
+
+Command detection uses literal skill paths. Before executing a command that constructs
+its asset paths dynamically, read the needed file at its `skills/...` filesystem path
+to materialize it.
diff --git a/plugins/onboarding/skills/onboarding/SKILL.md b/plugins/onboarding/skills/onboarding/SKILL.md
index 65745201a..6368a20b3 100644
--- a/plugins/onboarding/skills/onboarding/SKILL.md
+++ b/plugins/onboarding/skills/onboarding/SKILL.md
@@ -75,7 +75,7 @@ form, never into chat.
### Personal connections
Check the live credential inventory first. When an authorized Composio credential is available,
-read `skills/composio/SKILL.md`, discover available apps, and use its consent flow for the
+read `skill://composio/SKILL.md`, discover available apps, and use its consent flow for the
user's choices. Reuse their connected accounts after checking identity and permissions;
a project key is not proof that a personal account is connected. Do not ask them to
create OAuth apps for connections this source already provides. Do not infer that Composio is unavailable from an empty direct OAuth list
diff --git a/skills-seed/cloud-cli/SKILL.md b/skills-seed/cloud-cli/SKILL.md
index 7d00c2920..0d507f3c3 100644
--- a/skills-seed/cloud-cli/SKILL.md
+++ b/skills-seed/cloud-cli/SKILL.md
@@ -26,7 +26,7 @@ If it is missing, say so and pick a path rather than failing halfway:
provider's own installer, into the workspace or `$HOME`, not a system path. Say that you
installed it; it lasts as long as the machine's disk.
- **Use the provider's HTTP API** with a credential you already have (a keychain entry, or
- a shared org credential by proxy — see `skills/use-shared-credential/SKILL.md`).
+ a shared org credential by proxy — see `skill://use-shared-credential/SKILL.md`).
- **Ask the operator** to add the CLI to the sandbox image if this will recur. That is the
durable fix; a per-turn install is not.
@@ -61,7 +61,7 @@ The platform recognizes these as device-flow logins and runs them as **durable p
sessions**: the command prints the verification URL and one-time code immediately and keeps
polling across turns — it does not block your turn or die at teardown. Give the user the URL
and the code, tell them to approve and then say "done". See
-`skills/interactive-login/SKILL.md` for how to drive that from the background tool.
+`skill://interactive-login/SKILL.md` for how to drive that from the background tool.
On the next turn, run the same login command again (or any provider command): if approval
landed, the platform reports you are already authenticated and the token is cached; if it is
diff --git a/skills-seed/connect-apps/SKILL.md b/skills-seed/connect-apps/SKILL.md
index c92665d16..6b89345be 100644
--- a/skills-seed/connect-apps/SKILL.md
+++ b/skills-seed/connect-apps/SKILL.md
@@ -6,7 +6,7 @@ description: Connect an administrator-enabled SaaS app for a user with a one-tim
## Connecting SaaS apps
Check the live credential inventory first. When an authorized Composio credential is
-available, read `skills/composio/SKILL.md` and use its discovery and consent flow instead
+available, read `skill://composio/SKILL.md` and use its discovery and consent flow instead
of the direct OAuth flow below. An empty direct OAuth list or a native
`oauth_not_configured` error does not describe Composio availability. Preserve explicit
app restrictions and account permissions; never switch credentials to evade a denial.
diff --git a/skills-seed/github-gitlab/SKILL.md b/skills-seed/github-gitlab/SKILL.md
index 2a54dbffa..260c9ea8c 100644
--- a/skills-seed/github-gitlab/SKILL.md
+++ b/skills-seed/github-gitlab/SKILL.md
@@ -23,7 +23,7 @@ a write, ask. Do not infer permission from a login merely being present on the c
provider account (for example, `gh api user --jq .login`) and the Git transport's auth
configuration; a CLI API identity alone does not prove which account Git will use.
- **Shared org credential:** if listed in the prompt, select its slug and use the
- core-hosted smart HTTP remote in `skills/use-shared-credential/SKILL.md`. This uses
+ core-hosted smart HTTP remote in `skill://use-shared-credential/SKILL.md`. This uses
the configured shared account, even when a personal OAuth connector is live.
Its name is an admin label, not a verified upstream username.
- **Connected app:** use only advertised capabilities. API access does not by itself
diff --git a/skills-seed/popular-web-designs/SKILL.md b/skills-seed/popular-web-designs/SKILL.md
index d6e7b3e3a..4bd99c497 100644
--- a/skills-seed/popular-web-designs/SKILL.md
+++ b/skills-seed/popular-web-designs/SKILL.md
@@ -30,7 +30,7 @@ have not named one, use your deployment's house-style skill (a `*-design` skill
1. Pick a design from the catalog below
2. Read it: `read skills/popular-web-designs/templates/<site>.md`
3. Use the design tokens and component specs when generating HTML
-4. Build with `write`, then serve the result with the `publish` skill (`skills/publish/SKILL.md`)
+4. Build with `write`, then serve the result with the `publish` skill (`skill://publish/SKILL.md`)
Each template includes an **Implementation Notes** block at the top with:
diff --git a/skills-seed/publish/SKILL.md b/skills-seed/publish/SKILL.md
index 378b55c04..ace556be3 100644
--- a/skills-seed/publish/SKILL.md
+++ b/skills-seed/publish/SKILL.md
@@ -25,9 +25,9 @@ asked for a different look:
- **The deployment's house-style skill** — if a `*-design` skill is installed (list
`skills/`), it carries the org's look as ready-to-paste CSS and design tokens. Start
there for the look.
-- **`skills/taste-skill/SKILL.md`** — the design _process_: reading the brief, layout,
+- **`skill://taste-skill/SKILL.md`** — the design _process_: reading the brief, layout,
hierarchy, verifying the result, avoiding generic AI-design slop.
-- **`skills/popular-web-designs/SKILL.md`** — when the user wants a specific visual
+- **`skill://popular-web-designs/SKILL.md`** — when the user wants a specific visual
reference (Stripe, Linear, Vercel…).
This is about the page a person sees — skip it for an internal-only API or a script with
diff --git a/skills-seed/taste-skill/SKILL.md b/skills-seed/taste-skill/SKILL.md
index 4c70aff2c..594d35f4d 100644
--- a/skills-seed/taste-skill/SKILL.md
+++ b/skills-seed/taste-skill/SKILL.md
@@ -17,7 +17,7 @@ organization's **house style**: if the deployment installs a `*-design` skill (l
it only when the user names a different brand or asks for a one-off exploration.
If the user wants a _known brand's_ look (Stripe, Linear, Vercel, Notion…), read
-`skills/popular-web-designs/SKILL.md` for the visual vocabulary and let this skill drive
+`skill://popular-web-designs/SKILL.md` for the visual vocabulary and let this skill drive
the process.
## The playbook
@@ -36,7 +36,7 @@ anything externally facing or high-fidelity. Two adjustments for this runtime:
You have a real computer, not a hosted design canvas. Build the artifact as files in your
workspace, verify it locally, and when it should outlive the turn ship it with the
-`publish` skill (`skills/publish/SKILL.md`).
+`publish` skill (`skill://publish/SKILL.md`).
- **`write` / `read` / `execute`** — author files, install deps, run build steps.
- **`background`** — run a dev server (`PORT=8080 node server.js`) so you can look at it.
diff --git a/src/api/agent-api-catalog.ts b/src/api/agent-api-catalog.ts
index fbe985748..5816a38de 100644
--- a/src/api/agent-api-catalog.ts
+++ b/src/api/agent-api-catalog.ts
@@ -675,7 +675,7 @@ const FAMILIES: AgentApiFamily[] = [
((m === "PUT" || m === "DELETE") && p.startsWith("/v1/skills/")) ||
(m === "POST" && /^\/v1\/skills\/[^/]+\/restore$/.test(p)),
guidance:
- "Save a skill when you've worked out a repeatable procedure worth keeping (a checklist, a multi-step flow, a house style) — it auto-loads (skills/<name>/SKILL.md) on every future turn. The skill homes in THIS conversation's scope: in a 1:1 DM it's yours alone; in a private channel or group DM it's owned by that room and every member can edit or delete it (the audit trail records who changed what); a public channel stays owner-only. Write the `body` as a plain-step recipe addressed to your future self; edit or delete it as it goes stale.",
+ "Save a skill when you've worked out a repeatable procedure worth keeping (a checklist, a multi-step flow, a house style) — it is advertised for reading at skill://<name>/SKILL.md on future turns. The skill homes in THIS conversation's scope: in a 1:1 DM it's yours alone; in a private channel or group DM it's owned by that room and every member can edit or delete it (the audit trail records who changed what); a public channel stays owner-only. Write the `body` as a plain-step recipe addressed to your future self; edit or delete it as it goes stale.",
routes: [
{
method: "POST",
diff --git a/src/core/orchestrator.ts b/src/core/orchestrator.ts
index 395125af5..ec240cc0b 100644
--- a/src/core/orchestrator.ts
+++ b/src/core/orchestrator.ts
@@ -1604,6 +1604,7 @@ export function createOrchestrator(deps: OrchestratorDeps): Orchestrator {
provisionResource,
provisionOwnerAuth,
ensureSkillTree,
+ readSkill,
provisionForReach,
reclaimBox,
provisionPending,
@@ -2160,6 +2161,7 @@ export function createOrchestrator(deps: OrchestratorDeps): Orchestrator {
...(ownerAuthCommand ? { ownerAuthCommand } : {}),
...(scopedCommand ? { scopedCommand } : {}),
ensureSkillTree,
+ readSkill,
...(reachAvailable
? {
reach: {
@@ -2624,7 +2626,19 @@ export function createOrchestrator(deps: OrchestratorDeps): Orchestrator {
? resumeNote({ backgroundJobs: !!backgroundBroker, workRecorded: !!resume })
: baseText;
const isPollFire = automatedTurn && !!input.surface && isPollSurface(input.surface);
- const sessionUsedTools = visibleHistory.some((e) => e.type === "tool_call");
+ const sessionUsedTools = visibleHistory.some(
+ (e) =>
+ e.type === "tool_call" &&
+ !(
+ e.payload !== null &&
+ typeof e.payload === "object" &&
+ "tool" in e.payload &&
+ e.payload.tool === "read" &&
+ "path" in e.payload &&
+ typeof e.payload.path === "string" &&
+ e.payload.path.startsWith("skill://")
+ ),
+ );
if (
!strictReadOnly &&
deps.eagerProvision &&
diff --git a/src/core/orchestrator/sandboxes.ts b/src/core/orchestrator/sandboxes.ts
index 6266122eb..56a5383ab 100644
--- a/src/core/orchestrator/sandboxes.ts
+++ b/src/core/orchestrator/sandboxes.ts
@@ -10,8 +10,11 @@ import {
import type { DeviceFlowCutoverMode } from "../../credentials/device-flow-cutover.ts";
import { expandServiceAliases } from "../../credentials/resident-paths.ts";
import { shq } from "../../util/shell.ts";
-import { createSkillMaterializer, safeSkillDirName } from "../../skills/materialize.ts";
-import type { SkillResolution } from "../../skills/skill-store.ts";
+import { createSkillMaterializer, renderSkillBody, safeSkillDirName } from "../../skills/materialize.ts";
+import { safeSkillFilePath, type SkillResolution } from "../../skills/skill-store.ts";
+import { isSafeSkillName } from "../../skills/skill-name.ts";
+import { isSkillMaterializationControlPath } from "../../skills/materialization-paths.ts";
+import type { ReadResult } from "../../tools/primitives.ts";
import { TURN_FILES_DIR } from "../attachments.ts";
import { errMessage, swallow, swallowAs } from "../../util/errors.ts";
import { sleep } from "../../util/async.ts";
@@ -300,19 +303,35 @@ export function createTurnSandboxes(ctx: TurnSandboxContext) {
box.handle = handle;
return handle;
};
+ const readSkill = async (path: string): Promise<ReadResult> => {
+ const missing = { content: null, sourceScopeId: null };
+ const match = /^skill:\/\/([^/]+)\/(.+)$/.exec(path);
+ if (!match || !isSafeSkillName(match[1]!)) return missing;
+ const [, name, file] = match;
+ try {
+ if (safeSkillFilePath(file!) !== file || isSkillMaterializationControlPath(`skills/${name}/${file}`))
+ return missing;
+ } catch {
+ return missing;
+ }
+ const resolution = (await visibleSkillsForTurn()).find((r) => r.skill?.manifest.name === name);
+ if (!resolution?.skill) return missing;
+ const content =
+ file === "SKILL.md"
+ ? renderSkillBody(resolution)
+ : resolution.skill.manifest.files?.find((f) => f.path === file)?.content;
+ if (content === undefined) return missing;
+ if (deps.skills)
+ void deps.skills.recordUse(resolution.skill.id).catch((e) => swallow("orchestrator: skill recordUse", e));
+ return { content, sourceScopeId: resolution.skill.scopeId };
+ };
const laidTrees = new Set<string>();
- const visibleSkillByDir = new Map<string, SkillResolution>();
- for (const r of visibleSkills) {
- if (r.skill) visibleSkillByDir.set(safeSkillDirName(r.skill.manifest.name), r);
- }
- const ensureSkillTree = async (skillDir: string, sandboxId?: string): Promise<void> => {
+ const materializeSkillTree = async (handle: SandboxHandle, r: SkillResolution, sandboxId?: string): Promise<void> => {
+ const skillDir = safeSkillDirName(r.skill!.manifest.name);
const treeKey = `${sandboxId ?? "default"}:${skillDir}`;
if (laidTrees.has(treeKey)) return;
- const r = visibleSkillByDir.get(skillDir);
- if (!r) return;
const start = Date.now();
try {
- const handle = sandboxId ? await provisionResource(sandboxId) : await provision();
await skillMaterializer.materializeTree(deps.sandbox, handle, r, [], async () => {
const latest = (await visibleSkillsForTurn()).find(
(candidate) => candidate.skill && safeSkillDirName(candidate.skill.manifest.name) === skillDir,
@@ -337,6 +356,17 @@ export function createTurnSandboxes(ctx: TurnSandboxContext) {
emitGapWork("skills_materialize", start, Date.now());
}
};
+ const ensureSkillTree = async (skillDir: string, sandboxId?: string): Promise<void> => {
+ const current = await visibleSkillsForTurn();
+ const requested = current.filter(
+ (r) => r.skill && (skillDir === ".packs" ? r.skill.pack : r.skill.manifest.name === skillDir),
+ );
+ if (!requested.length) return;
+ const handle = sandboxId ? await provisionResource(sandboxId) : await provision();
+ for (const r of requested) {
+ await materializeSkillTree(handle, r, sandboxId);
+ }
+ };
const provisionResource = (id: string): Promise<SandboxHandle> => {
const existing = resourceHandles.get(id);
if (existing) return Promise.resolve(existing);
@@ -634,6 +664,7 @@ export function createTurnSandboxes(ctx: TurnSandboxContext) {
provisionResource,
provisionOwnerAuth,
ensureSkillTree,
+ readSkill,
provisionForReach,
reclaimBox,
provisionPending: () => provisionInFlight !== null,
diff --git a/src/harness/agent-tools.ts b/src/harness/agent-tools.ts
index f728ca7f6..1a73767aa 100644
--- a/src/harness/agent-tools.ts
+++ b/src/harness/agent-tools.ts
@@ -940,9 +940,10 @@ export function createAgentTools(ref: ToolContextRef, opts?: AgentToolsOptions):
const read = defineTool({
name: "read",
label: "read",
- description: "Read a file from the workspace (scope, then global). Returns its contents.",
+ description:
+ "Read published skill sources at skill://<name>/<path> without a sandbox, or workspace files (scope, then global). Returns contents.",
parameters: Type.Object({
- path: Type.String({ description: "Relative path within the workspace." }),
+ path: Type.String({ description: "Published skill URI or relative path within the workspace." }),
}),
async execute(callId, params) {
const tc = ref.current;
diff --git a/src/onboarding/onboarding.ts b/src/onboarding/onboarding.ts
index bae883c97..000419ce6 100644
--- a/src/onboarding/onboarding.ts
+++ b/src/onboarding/onboarding.ts
@@ -68,7 +68,7 @@ export function renderPendingOnboardingPrompt(status: OnboardingStatus, version
"",
"Onboarding is a high-priority setup task; already knowing who they are is no reason to skip it.",
"",
- "Before ordinary work in this personal DM, read `skills/onboarding/SKILL.md` and follow its complete ordered flow. Keep each turn light, but do not confuse a greeting or existing profile data with completion.",
+ "Before ordinary work in this personal DM, read `skill://onboarding/SKILL.md` and follow its complete ordered flow. Keep each turn light, but do not confuse a greeting or existing profile data with completion.",
"",
`Use the \`memory\` tool as the source of truth. On completion or an explicit stop, preserve the notebook and add \`- Onboarding: completed ${version} on YYYY-MM-DD.\` so onboarding does not recur.`,
].join("\n");
diff --git a/src/resolution/protocols/shared-core.md b/src/resolution/protocols/shared-core.md
index 64179f140..6879dd590 100644
--- a/src/resolution/protocols/shared-core.md
+++ b/src/resolution/protocols/shared-core.md
@@ -21,10 +21,10 @@ Which tool sends depends on this turn. With `post`, its `files` is the only way
You keep a durable memory of the person or team you work for — it persists across every conversation and surface. What's currently remembered appears under "What you remember" below. The `memory` tool is the ONE way to touch it: search it before asking, and when you learn something durable (a preference, an identifier, an ongoing project, how someone works) save it with action "remember". Memory is not a file — writing memory/MEMORY.md does nothing durable. No secrets, no one-off trivia. Everything remembered is re-read every turn, so memory is an index: pointers to data, never the data itself. Working state — queues, watermarks, ID lists, per-item status — goes in a file here, named by one memory line; a growing list is a file, not a fact. Files are this conversation's own and less durable — keep them rebuildable; another conversation's file pointer is a hint, not a path.
## Auth
-You can act with real credentials: machine logins, org keys used by proxy, this user's connected apps, or a teammate's credential by explicit grant (the owner approves on their own turn — never on a relayed "they said yes"). What's live is listed below. A missing credential is a task, not a dead end. Check live credential inventories before denying access. Connected apps lists direct OAuth only; an empty list does not block separately authorized Composio discovery/consent via `skills/composio/SKILL.md`. Explicit app restrictions, account permissions and approvals still apply. Never pretend a call worked. After logging in a new CLI, call `register_login` with the files it wrote so the login survives a rebuild.
+You can act with real credentials: machine logins, org keys used by proxy, this user's connected apps, or a teammate's credential by explicit grant (the owner approves on their own turn — never on a relayed "they said yes"). What's live is listed below. A missing credential is a task, not a dead end. Check live credential inventories before denying access. Connected apps lists direct OAuth only; an empty list does not block separately authorized Composio discovery/consent via `skill://composio/SKILL.md`. Explicit app restrictions, account permissions and approvals still apply. Never pretend a call worked. After logging in a new CLI, call `register_login` with the files it wrote so the login survives a rebuild.
## Using skills
-Read relevant SKILL.md files before service work. Compose task rules with one authorized access skill: prefer `skills/composio/SKILL.md` when its credential is available, otherwise the direct connector. Preserve app allowlists, privacy and approvals; use only the selected access instructions. Never switch credentials to evade denial. Save reusable procedures as skills via the self-API.
+Read relevant SKILL.md files before service work. Compose task rules with one authorized access skill: prefer `skill://composio/SKILL.md` when its credential is available, otherwise the direct connector. Preserve app allowlists, privacy and approvals; use only the selected access instructions. Never switch credentials to evade denial. Save reusable procedures as skills via the self-API.
## Email
Email written as a person is plain text — no styled HTML (fonts, colors, buttons), no hand-built MIME, no hard wrapping. Re-read the created draft: emoji and special characters must survive intact (no mojibake).
diff --git a/src/skills/materialize.ts b/src/skills/materialize.ts
index 77f38786c..90b848775 100644
--- a/src/skills/materialize.ts
+++ b/src/skills/materialize.ts
@@ -46,7 +46,7 @@ function indexHash(resolved: SkillResolution[]): string {
const h = createHash("sha256");
const entries = resolved
.filter((r) => r.skill)
- .map((r) => `${r.skill!.manifest.name}\0${r.skill!.scopeId}\0${r.skill!.id}\0${renderedBody(r)}`)
+ .map((r) => `${r.skill!.manifest.name}\0${r.skill!.scopeId}\0${r.skill!.id}\0${renderSkillBody(r)}`)
.sort();
for (const e of entries) {
h.update(e);
@@ -66,7 +66,7 @@ function treeHash(resolution: SkillResolution, bundles: SkillBundle[]): string {
.sort()
.join("\0");
return createHash("sha256")
- .update(renderedBody(resolution))
+ .update(renderSkillBody(resolution))
.update("\0")
.update(files)
.update("\0")
@@ -78,7 +78,7 @@ function packRoot(resolution: SkillResolution): string | null {
return resolution.skill?.pack ? `${SKILL_PACKS_DIR}/${safeSkillDirName(resolution.skill.pack.packId)}` : null;
}
-function renderedBody(resolution: SkillResolution): string {
+export function renderSkillBody(resolution: SkillResolution): string {
const body = resolution.skill!.manifest.body;
const root = packRoot(resolution);
return root
@@ -265,7 +265,7 @@ async function materializeSkillIndexUnlocked(
if (!r.skill) continue;
entries.push({
path: `${SKILLS_DIR}/${safeSkillDirName(r.skill.manifest.name)}/SKILL.md`,
- content: renderedBody(r),
+ content: renderSkillBody(r),
});
}
entries.push({
@@ -337,7 +337,7 @@ async function materializeSkillTreeUnlocked(
await sandbox.removeDir(handle, dir);
}
- const entries: LayEntry[] = [{ path: `${dir}/SKILL.md`, content: renderedBody(resolution) }];
+ const entries: LayEntry[] = [{ path: `${dir}/SKILL.md`, content: renderSkillBody(resolution) }];
for (const f of files) {
let rel: string;
try {
@@ -426,11 +426,11 @@ export function skillsIndex(resolved: SkillResolution[], provenanceScopes: reado
const m = r.skill!.manifest;
const shadow = r.shadowed.length ? " (shadows a broader-scope skill of the same name)" : "";
const source = provenance.has(r.skill!.scopeId) ? ` [from ${r.skill!.scopeId}]` : "";
- return `- **${m.name}**${source} — ${m.description}${shadow} → read \`${SKILLS_DIR}/${safeSkillDirName(m.name)}/SKILL.md\``;
+ return `- **${m.name}**${source} — ${m.description}${shadow} → read \`skill://${safeSkillDirName(m.name)}/SKILL.md\``;
});
return [
"## Skills",
- "You have these skills available. To use one, read its SKILL.md and follow it (run its steps with your tools):",
+ "Read published skills with the read tool at skill://<name>/SKILL.md; this does not start a sandbox. Read relative skill files at skill://<name>/<path>. These are read-only published sources, not filesystem paths. Execute scripts and access working copies under skills/<name>/ in the sandbox; ordinary filesystem reads preserve local edits.",
...lines,
].join("\n");
}
diff --git a/src/tools/primitives.ts b/src/tools/primitives.ts
index 3206e0f55..f5c265c22 100644
--- a/src/tools/primitives.ts
+++ b/src/tools/primitives.ts
@@ -71,9 +71,9 @@ import type { CapabilityClaims } from "../auth/capability-token.ts";
import type { VisibleCron } from "../api/app.ts";
import { createPlaygroundArtifact, type PlaygroundArtifact } from "../playgrounds/playground.ts";
-const SKILL_SKILLMD_RE = /^(?:\.\/)?skills\/([^/]+)\/SKILL\.md$/;
+const SKILL_FILE_RE = /^(?:\.\/)?skills\/([^/]+)\/.+$/;
function skillTreeDirFor(path: string): string | null {
- const m = SKILL_SKILLMD_RE.exec(path);
+ const m = SKILL_FILE_RE.exec(path);
return m ? m[1]! : null;
}
@@ -143,7 +143,7 @@ export class CommandDenied extends Error {
}
}
-interface ReadResult {
+export interface ReadResult {
content: string | null;
sourceScopeId: ScopeId | null;
shared?: true;
@@ -432,6 +432,7 @@ export interface ToolContextDeps {
provisionOwnerAuth?: () => Promise<SandboxHandle>;
ownerAuthCommand?: (command: string) => string;
scopedCommand?: (command: string) => string;
+ readSkill?: (path: string) => Promise<ReadResult>;
ensureSkillTree?: (skillDir: string, sandboxId?: string) => Promise<void>;
reach?: {
resolveChannel(query: string): Promise<ReachResolution>;
@@ -811,6 +812,8 @@ export function createToolContext(deps: ToolContextDeps): ToolContext {
async read(path: string, signal?: AbortSignal): Promise<ReadResult> {
signal?.throwIfAborted();
+ if (path.startsWith("skill://"))
+ return deps.readSkill ? withAbort(() => deps.readSkill!(path), signal) : { content: null, sourceScopeId: null };
if (path === MEMORY_FILE && deps.memory && deps.memoryScopeId) {
if (!deps.memoryAccess?.read.includes(deps.memoryScopeId)) {
throw new Error("memory recall is not enabled for this conversation; use the `memory` tool when enabled");
@@ -878,6 +881,8 @@ export function createToolContext(deps: ToolContextDeps): ToolContext {
},
async write(path: string, data?: string, share?: ShareDirective[]): Promise<WriteResult> {
+ if (path.startsWith("skill://"))
+ throw new Error("Published skill sources are read-only; edit skills through the skill API.");
const wantShare = share !== undefined && share.length > 0;
if (data === undefined && !wantShare) {
throw new Error("write needs `data` to save content, `share` to grant access, or both");
diff --git a/test/deployment-skill.test.ts b/test/deployment-skill.test.ts
index c43aeeacf..8c1bc56cf 100644
--- a/test/deployment-skill.test.ts
+++ b/test/deployment-skill.test.ts
@@ -108,7 +108,7 @@ test("connector onboarding is governed by the live admin-configured list", () =>
assert.doesNotMatch(skill, /Slack and Google first|Slack, Google, Notion, Linear, and GitHub/);
}
for (const skill of [onboarding, connectApps]) {
- assert.match(skill, /skills\/composio\/SKILL\.md/);
+ assert.match(skill, /skill:\/\/composio\/SKILL\.md/);
assert.match(skill, /never switch credentials to evade a denial/i);
assert.doesNotMatch(skill, /If it says none are enabled, skip|offer none when that list is/);
}
diff --git a/test/onboarding.test.ts b/test/onboarding.test.ts
index 573fcfc96..62575821b 100644
--- a/test/onboarding.test.ts
+++ b/test/onboarding.test.ts
@@ -74,7 +74,7 @@ test("a new personal DM gets the high-priority pending onboarding prompt", async
assert.match(sys.reply ?? "", /## Pending Onboarding/);
assert.match(sys.reply ?? "", /high-priority setup task/);
assert.match(sys.reply ?? "", /no reason to skip it/);
- assert.match(sys.reply ?? "", /skills\/onboarding\/SKILL\.md/);
+ assert.match(sys.reply ?? "", /skill:\/\/onboarding\/SKILL\.md/);
});
test("completed or dismissed onboarding markers suppress the pending prompt", async () => {
diff --git a/test/prompt-modes.test.ts b/test/prompt-modes.test.ts
index 3448bd43d..3637f6059 100644
--- a/test/prompt-modes.test.ts
+++ b/test/prompt-modes.test.ts
@@ -288,7 +288,7 @@ test("shared-core platform guidance reaches both the DM and the spine prompt", a
assert.match(prompt, /## Auth/);
assert.match(prompt, /## Using skills/);
assert.match(prompt, /Compose task rules with one authorized access skill/);
- assert.match(prompt, /prefer `skills\/composio\/SKILL.md`/);
+ assert.match(prompt, /prefer `skill:\/\/composio\/SKILL.md`/);
assert.match(prompt, /Never switch credentials to evade denial/);
assert.doesNotMatch(prompt, /## Scheduling & self-configuration/);
}
diff --git a/test/skills-lazy-read-seam.test.ts b/test/skills-lazy-read-seam.test.ts
index 27126e5f6..db3a97279 100644
--- a/test/skills-lazy-read-seam.test.ts
+++ b/test/skills-lazy-read-seam.test.ts
@@ -62,13 +62,13 @@ test("a leading ./ on the SKILL.md path still triggers materialization", async (
assert.deepEqual(seen, ["taste-skill"]);
});
-test("reading an asset inside a skill dir does NOT trigger materialization (only SKILL.md does)", async () => {
+test("reading assets inside skill directories materializes their trees", async () => {
const seen: string[] = [];
const tc = ctx((d) => seen.push(d));
await tc.read("skills/popular-web-designs/scripts/render.py");
await tc.read("skills/foo/references/notes.md");
await tc.read("reports/report.md");
- assert.deepEqual(seen, [], "no lazy trigger for non-SKILL.md reads");
+ assert.deepEqual(seen, ["popular-web-designs", "foo"]);
});
test("executing a skill's script on a cold box (no prior SKILL.md read) materializes its tree first", async () => {
diff --git a/test/skills-source-read.test.ts b/test/skills-source-read.test.ts
new file mode 100644
index 000000000..7f38cca18
--- /dev/null
+++ b/test/skills-source-read.test.ts
@@ -0,0 +1,184 @@
+import "./support/auto-fake-sprites.ts";
+import { test, type TestContext } from "node:test";
+import assert from "node:assert/strict";
+import { buildApp } from "../src/wiring.ts";
+import { testConfig } from "./support/test-config.ts";
+import type { TurnRequest } from "../src/types.ts";
+
+async function fixture(t: TestContext) {
+ const built = buildApp(testConfig());
+ await built.deploymentLayerReady;
+ t.after(async () => {
+ built.scheduler.stop();
+ built.deploymentLayerRefresh.stop();
+ await built.runtime.stop();
+ });
+ let provisions = 0;
+ const provision = built.sandbox.provision.bind(built.sandbox);
+ built.sandbox.provision = async (...args) => {
+ provisions++;
+ return provision(...args);
+ };
+ const turn = async (text: string, actor = "U1") => {
+ const result = await built.app.turn({
+ surface: "test",
+ actor: { externalId: actor },
+ conversation: { kind: "dm", threadRef: `dm:${actor}:skill-source` },
+ text,
+ } as TurnRequest);
+ assert.equal(result.status, "ok", JSON.stringify(result));
+ return result.reply ?? "";
+ };
+ const publish = async (scopeId: string, body: string, packId?: string) => {
+ const skill = await built.skills.create({
+ scopeId,
+ createdBy: "U1",
+ ...(packId ? { pack: { packId, commit: "c", upstreamName: "source-helper" } } : {}),
+ manifest: {
+ name: "source-helper",
+ description: "source test",
+ body,
+ requiredCapabilities: [],
+ files: [{ path: "references/example.txt", content: "PUBLISHED_ASSET" }],
+ },
+ });
+ await built.skills.review(skill.id, "reviewer", []);
+ await built.skills.publish(skill.id);
+ return skill;
+ };
+ return { ...built, turn, publish, provisions: () => provisions };
+}
+
+test("published skill sources and assets read without a sandbox, respecting scope and archive", async (t) => {
+ const b = await fixture(t);
+ const skill = await b.publish("personal:U1", "PUBLISHED_BODY");
+ assert.match(await b.turn("!sysprompt"), /skill:\/\/source-helper\/SKILL.md/);
+ assert.equal(await b.turn("!read skill://source-helper/SKILL.md"), "PUBLISHED_BODY");
+ assert.equal(await b.turn("!read skill://source-helper/references/example.txt"), "PUBLISHED_ASSET");
+ assert.match(await b.turn("!read skill://source-helper/SKILL.md", "U2"), /no file/);
+ await b.skills.archive(skill.id);
+ assert.match(await b.turn("!read skill://source-helper/SKILL.md"), /no file/);
+ assert.equal(b.provisions(), 0);
+});
+
+test("published skill reads reject invalid and control paths without provisioning", async (t) => {
+ const b = await fixture(t);
+ await b.publish("personal:U1", "PUBLISHED_BODY");
+ for (const path of [
+ "skill://missing/SKILL.md",
+ "skill://source-helper/../SKILL.md",
+ "skill://source-helper/.tree",
+ "skill://../SKILL.md",
+ "skill://source-helper//SKILL.md",
+ "skill://source-helper/./SKILL.md",
+ "skill://source-helper/references/../../secret",
+ "skill://source-helper/%2e%2e/secret",
+ ])
+ assert.match(await b.turn(`!read ${path}`), /no file/, path);
+ assert.equal(b.provisions(), 0);
+});
+
+test("published source follows scope shadowing and preserves sandbox-authored working copies", async (t) => {
+ const b = await fixture(t);
+ await b.publish("org:default-org", "ORG_BODY");
+ const personal = await b.publish("personal:U1", "PERSONAL_BODY");
+ assert.equal(await b.turn("!read skill://source-helper/SKILL.md"), "PERSONAL_BODY");
+ assert.equal(b.provisions(), 0);
+ await b.turn("!read skills/source-helper/SKILL.md");
+ await b.turn("!write skills/source-helper/SKILL.md LOCAL_EDIT");
+ assert.equal(await b.turn("!read skill://source-helper/SKILL.md"), "PERSONAL_BODY");
+ assert.equal(await b.turn("!read skills/source-helper/SKILL.md"), "LOCAL_EDIT");
+ await b.skills.archive(personal.id);
+ assert.equal(await b.turn("!read skill://source-helper/SKILL.md"), "ORG_BODY");
+});
+
+test("a source-only read avoids sandbox work and a subsequent asset request materializes the current revision", async () => {
+ const { createTurnSandboxes } = await import("../src/core/orchestrator/sandboxes.ts");
+ const { createSkillMaterializer } = await import("../src/skills/materialize.ts");
+ type TurnSandboxContext = import("../src/core/orchestrator/sandboxes.ts").TurnSandboxContext;
+ type SkillResolution = import("../src/skills/skill-store.ts").SkillResolution;
+ const files = new Map<string, string>();
+ let provisions = 0;
+ const sandboxIds: Array<string | undefined> = [];
+ let resolution = {
+ skill: {
+ id: "s",
+ scopeId: "personal:U1",
+ manifest: {
+ name: "source-helper",
+ body: "BODY",
+ files: [{ path: "references/example.txt", content: "v1" }],
+ },
+ },
+ shadowed: [],
+ } as unknown as SkillResolution;
+ const handle = { id: "box", rootDir: "/workspace" };
+ const turn = createTurnSandboxes({
+ deps: {
+ skills: { recordUse: async () => {} },
+ sandboxResources: { get: async () => ({ ownerScopeId: "personal:U1" }) },
+ sandbox: {
+ provision: async (_layers: unknown, options?: { sandboxId?: string }) => {
+ sandboxIds.push(options?.sandboxId);
+ provisions++;
+ return handle;
+ },
+ listDir: async () => [],
+ removeDir: async () => {},
+ readFile: async (_handle: unknown, path: string) => files.get(path) ?? null,
+ writeFile: async (_handle: unknown, path: string, content: string) => {
+ files.set(path, content);
+ },
+ },
+ },
+ input: { origin: { kind: "human" } },
+ actor: { id: "U1" },
+ session: { id: "s" },
+ resolution: { layers: [{ scopeId: "personal:U1", mountPath: "", mode: "rw" }] },
+ scopeId: "personal:U1",
+ memoryScopeId: "personal:U1",
+ turnSessionDir: "turn/s",
+ turnFilesDir: "turn/s/t",
+ connectorEnv: {},
+ ownerEnvCredentialIds: [],
+ credentialCutoverServices: [],
+ visibleSkills: [resolution],
+ visibleSkillsForTurn: async () => [resolution],
+ skillMaterializer: createSkillMaterializer(),
+ emitGapWork: () => {},
+ perf: { credsMs: 0 },
+ } as unknown as TurnSandboxContext);
+ assert.equal((await turn.readSkill("skill://source-helper/SKILL.md")).content, "BODY");
+ assert.equal(provisions, 0);
+ assert.equal(files.size, 0);
+ resolution = structuredClone(resolution);
+ resolution.skill!.manifest.files![0]!.content = "v2";
+ assert.equal((await turn.readSkill("skill://source-helper/references/example.txt")).content, "v2");
+ await turn.ensureSkillTree("source-helper");
+ assert.equal(provisions, 1);
+ assert.equal(files.get("skills/source-helper/references/example.txt"), "v2");
+ files.set("skills/source-helper/references/example.txt", "local edit");
+ await turn.provision();
+ assert.equal(files.get("skills/source-helper/references/example.txt"), "local edit");
+ resolution.skill!.pack = { packId: "pack", commit: "c", upstreamName: "source-helper" };
+ resolution.screenedBundles = [
+ { packId: "pack", commit: "c", hash: "pack-hash", files: [{ path: "lib.txt", content: "PACK_RESOURCE" }] },
+ ];
+ await turn.ensureSkillTree(".packs", "resource-1");
+ assert.deepEqual(sandboxIds, [undefined, "resource-1"]);
+ assert.equal(files.get("skills/.packs/pack/lib.txt"), "PACK_RESOURCE");
+});
+
+test("pack assets remain readable and executable on later turns after source-only reads", async (t) => {
+ const { computeBundleHash } = await import("../src/skills/skill-bundle-store.ts");
+ const b = await fixture(t);
+ const skill = await b.publish("personal:U1", "PACK_BODY", "source-pack");
+ const files = [{ path: "example.sh", content: "printf PACK_ASSET" }];
+ await b.skillBundles.put({ packId: "source-pack", commit: "c", files, hash: computeBundleHash(files) });
+ assert.match(await b.turn("!read skill://source-helper/SKILL.md"), /skills\/\.packs\/source-pack/);
+ assert.equal(b.provisions(), 0);
+ assert.equal(await b.turn("!run sh skills/.packs/source-pack/example.sh"), "PACK_ASSET");
+ assert.equal(await b.turn("!read skills/.packs/source-pack/example.sh"), "printf PACK_ASSET");
+ await b.skills.archive(skill.id);
+ assert.match(await b.turn("!read skills/.packs/source-pack/example.sh"), /no file/);
+});