agent-trellis 0.21.0 → 0.22.0

package/dist/adapters/mcpPlan.d.ts

@@ -91,4 +91,6 @@ export interface LiteralSecretMatch {
  * as before this function reported a field at all.
  */
 export declare function findLiteralSecret(def: McpServerDef): LiteralSecretMatch | undefined;
-export declare function resolveMcpPlan(agentId: AgentId, mcp: McpConfig, managedAgents: readonly AgentId[], policy: SecretsPolicy): Promise<McpPlanResult>;
+export declare function resolveMcpPlan(agentId: AgentId, mcp: McpConfig, managedAgents: readonly AgentId[], policy: SecretsPolicy, options?: {
+    hosted?: boolean;
+}): Promise<McpPlanResult>;

package/dist/adapters/mcpPlan.js

@@ -20,7 +20,8 @@ import { isInScope } from "../core/adapter.js";
 import { capabilityDeliveryForAgent } from "../core/types.js";
 import { isOAuthAuth, oauthOwner } from "../core/types.js";
 import { codexBearerTokenEnvVar } from "../lib/tomlSection.js";
-import { parseEnvEntry, resolveSecretEnv } from "../lib/secretEnv.js";
+import { deliveredName, isValidSecretVarName, parseEnvEntry, resolveSecretEntries, resolveSecretEnv, SecretReferenceError } from "../lib/secretEnv.js";
+import { extractTemplateVarNames, invalidHeaderTemplate } from "../lib/envVarNames.js";
 export const HUB_ENTRY_NAME = "trellis-hub";
 export const GATEWAY_ENTRY_NAME = "trellis";
 export const LEGACY_GATEWAY_ENTRY_NAME = "trellis-gateway";
@@ -139,7 +140,10 @@ export function findLiteralSecret(def) {
  * (trellis-migrate-env-var-alias).
  */
 async function findUnresolvedEnvName(def, policy) {
-    const names = [...(def.env ?? []), ...Object.values(def.envAliases ?? {})];
+    const headerRefs = Object.values(def.headers ?? {}).flatMap(extractTemplateVarNames)
+        .filter((entry) => !isValidSecretVarName(entry));
+    const envNames = [...(def.env ?? []), ...Object.values(def.envAliases ?? {})];
+    const names = [...envNames, ...headerRefs];
     if (names.length === 0)
         return undefined;
     // A malformed `mxenv://` entry conflicts here too — it is rejected input,
@@ -147,16 +151,26 @@ async function findUnresolvedEnvName(def, policy) {
     // returned text is the DECLARED entry; resolution checks use delivered
     // names (the `KEY` segment for a reference).
     const parsed = names.map(parseEnvEntry);
-    const invalid = parsed.find((p) => p.kind === "invalid");
-    if (invalid)
-        return invalid.entry;
-    const resolved = await resolveSecretEnv(names, policy);
-    return names.find((name) => {
-        const p = parseEnvEntry(name);
-        return !resolved[p.kind === "invalid" ? name : p.delivered];
-    });
+    const invalid = names.find((entry, i) => parsed[i].kind === "invalid" || (headerRefs.includes(entry) && parsed[i].kind === "name"));
+    if (invalid !== undefined)
+        return invalid;
+    try {
+        // Retain env/envAliases' existing delivered-name collision behavior.
+        // Header references instead remain source-bound, with no bare-name fallback.
+        const env = await resolveSecretEnv(envNames, policy);
+        const missingEnv = envNames.find((entry) => !env[deliveredName(entry)]);
+        if (missingEnv !== undefined)
+            return missingEnv;
+        const headers = await resolveSecretEntries(headerRefs, policy);
+        return headerRefs.find((entry) => !headers[entry]);
+    }
+    catch (error) {
+        if (error instanceof SecretReferenceError)
+            return error.entry;
+        throw error;
+    }
 }
-export async function resolveMcpPlan(agentId, mcp, managedAgents, policy) {
+export async function resolveMcpPlan(agentId, mcp, managedAgents, policy, options = {}) {
     const route = routeForAgent(agentId, mcp, managedAgents);
     const runtimeEnabled = capabilityDeliveryForAgent(agentId, mcp) !== "native";
     // Checked before `hub`: only one entry can be "the" MCP entry for an
@@ -257,14 +271,14 @@ export async function resolveMcpPlan(agentId, mcp, managedAgents, policy) {
             conflicts: oauth.conflicts,
         };
     }
-    const native = await planDirectServers(agentId, mcp, managedAgents, policy, route);
+    const native = await planDirectServers(agentId, mcp, managedAgents, policy, route, undefined, options.hosted || agentId === "pi");
     const hosted = native.desired.filter(({ def }) => isOAuthMcpServer(def) && oauthOwner(def.auth) === "trellis");
     return {
         desired: native.desired.filter(({ def }) => !isOAuthMcpServer(def) || oauthOwner(def.auth) === "agent"),
         conflicts: [...native.conflicts, ...hosted.map(({ name }) => ({ name, message: `Trellis-owned OAuth server "${name}" requires gateway or runtime delivery for ${agentId}`, remediation: "enable gateway/runtime delivery or set auth.owner to agent" }))],
     };
 }
-async function planDirectServers(agentId, mcp, managedAgents, policy, route, filter) {
+async function planDirectServers(agentId, mcp, managedAgents, policy, route, filter, hosted = false) {
     const desired = [];
     const conflicts = [];
     for (const [name, def] of Object.entries(mcp.servers)) {
@@ -304,12 +318,17 @@ async function planDirectServers(agentId, mcp, managedAgents, policy, route, fil
             });
             continue;
         }
+        const invalidHeader = invalidHeaderTemplate(def.headers);
+        if (invalidHeader !== undefined) {
+            conflicts.push({ name, message: `refusing to write MCP server "${name}": invalid reference template in header ${invalidHeader}`, remediation: "use ${VAR} or ${mxenv://<profile>/<KEY>} in headers" });
+            continue;
+        }
         // Codex has no generic headers concept — only the single
         // Authorization-bearer-token shape is expressible there
         // (trellis-mcp-transport-auth design.md D4). Any other shape is
         // refused for Codex specifically; every other in-scope agent for
         // the same server is unaffected (this loop runs once per agentId).
-        if (agentId === "codex" && def.headers && Object.keys(def.headers).length > 0 && !codexBearerTokenEnvVar(def)) {
+        if (!hosted && agentId === "codex" && def.headers && Object.keys(def.headers).length > 0 && !codexBearerTokenEnvVar(def)) {
             conflicts.push({
                 name,
                 message: `refusing to write MCP server "${name}" for codex: its "headers" field isn't the single { Authorization: "Bearer \${VAR}" } shape Codex's own config format can express — Codex has no generic headers concept, only \`bearer_token_env_var\`. Still written normally for every other in-scope agent.`,
@@ -318,9 +337,9 @@ async function planDirectServers(agentId, mcp, managedAgents, policy, route, fil
             continue;
         }
         const unresolvedName = await findUnresolvedEnvName(def, policy);
-        if (unresolvedName) {
+        if (unresolvedName !== undefined) {
             const entry = parseEnvEntry(unresolvedName);
-            if (entry.kind === "invalid") {
+            if (entry.kind === "invalid" || !isValidSecretVarName(unresolvedName) && entry.kind === "name") {
                 conflicts.push({
                     name,
                     message: `refusing to write MCP server "${name}": its declared env entry "${unresolvedName}" is not a valid mxenv://<profile>/<KEY> reference (mx-env-secret-source)`,
@@ -339,6 +358,14 @@ async function planDirectServers(agentId, mcp, managedAgents, policy, route, fil
             });
             continue;
         }
+        if (!hosted && Object.values(def.headers ?? {}).flatMap(extractTemplateVarNames).some((entry) => parseEnvEntry(entry).kind === "ref")) {
+            conflicts.push({
+                name,
+                message: `refusing to write MCP server "${name}": mxenv header references require Trellis gateway/runtime delivery; native clients cannot resolve them`,
+                remediation: `enable gateway/runtime delivery for ${agentId}, keeping transport and headers in servers.yaml`,
+            });
+            continue;
+        }
         desired.push({ name, def });
     }
     return { desired, conflicts };

package/dist/cli.js

@@ -118,7 +118,7 @@ Commands:
               --skill, -s <name>       required unless --list
               --branch <ref>           Git branch, tag, or ref; default is
                                        the source repository's default branch
-              --agent, -a <ids|*>      restrict delivery to managed Agent ids
+              --agent, -a <ids|*|none> choose applicable managed Agents
               --list                   show discovered Skills without import
               --global, --yes          accepted skills-CLI compatibility flags
               --dry-run                fetch and preview; write nothing
@@ -205,19 +205,22 @@ Commands:
               --dry-run    preview the plan, write nothing
               --json       machine-readable output, no report text
   skill list
-            List canonical skills with resolved scope
+            List canonical skills; unregistered skills are paused
+              --agent <id>  filter by agent and show actual delivery status
               --json    machine-readable output, no report text
   skill add <name> --from <path>
             Import a real skill directory into canonical (refuses on
               an existing name with different content, no overwrite)
               --workspace  copy into .agents/skills/ instead of canonical
+              --agents <ids> | --all | --none
+                           required without an interactive terminal
               --dry-run    preview the plan, write nothing
               --json       machine-readable output, no report text
   skill remove <name>
   skill scope <name> --agents <ids> | --all | --none
             Choose which managed agents receive a canonical skill, then
-            sync it. Same selector rules as mcp scope; a built-in skill's
-            scope is not editable
+            sync it. --all records today's managed set; newly managed
+            agents need explicit registration. Built-in scope is not editable
               --dry-run    preview the plan, write nothing
               --json       machine-readable output, no report text
   skill update-builtin
@@ -527,7 +530,7 @@ async function main(argv) {
         const json = skillRest.includes("--json");
         const dryRun = skillRest.includes("--dry-run");
         if (subcommand === "list") {
-            process.exitCode = runSkillList({ json }).exitCode;
+            process.exitCode = runSkillList({ json, agent: flagValue(skillRest, "--agent") }).exitCode;
             return;
         }
         if (subcommand === "add") {
@@ -538,7 +541,7 @@ async function main(argv) {
                 process.exitCode = 1;
                 return;
             }
-            process.exitCode = (await runSkillAdd(name, from, { json, dryRun, workspace: skillRest.includes("--workspace") })).exitCode;
+            process.exitCode = (await runSkillAdd(name, from, { json, dryRun, workspace: skillRest.includes("--workspace"), selection: parseScopeArgs(skillRest) })).exitCode;
             return;
         }
         if (subcommand === "remove") {

package/dist/commands/mcpGateway.js

@@ -90,7 +90,7 @@ export async function resolveGatewayUpstreams(agentId, canonical) {
     // ownership-gated removal clears it. Serving that stale entry would hand
     // every server, and every secret resolved into it, to the one agent the
     // user just said to stop involving.
-    const { desired, conflicts } = await resolveMcpPlan(agentId, direct, canonical.managedAgents, canonical.secretsPolicy);
+    const { desired, conflicts } = await resolveMcpPlan(agentId, direct, canonical.managedAgents, canonical.secretsPolicy, { hosted: true });
     // Agent-owned OAuth servers bypass the gateway as direct entries, so no
     // connection state exists for them here — but Trellis owns the token
     // store, so `trellis.mcp.status` reports their credential health for

package/dist/commands/migrate.js

@@ -19,7 +19,7 @@ import { deepEqual } from "../lib/deepEqual.js";
 import { readClaudeCodeMcpDefs, readCodexMcpDefs, readKiroMcpDefs, readKimiCodeMcpDefs, readZcodeMcpDefs, resolvedEnvTextMap } from "../lib/mcpMigrateRead.js";
 import { parseDotenv, writeLocalSecretValue } from "../lib/secretEnv.js";
 import { findLiteralSecret } from "../adapters/mcpPlan.js";
-import { ensureGitignoreEntry, ensureShellEnvSource, loadCanonicalSource, upsertServerYaml, writeSecretsPolicyExtraction } from "../core/canonical.js";
+import { ensureGitignoreEntry, ensureShellEnvSource, loadCanonicalSource, upsertServerYaml, validateSkillScopeYaml, writeSecretsPolicyExtraction, writeSkillScopeYaml } from "../core/canonical.js";
 import { ALL_AGENTS } from "../core/types.js";
 import { discoverNativeMemory, MAX_NATIVE_MEMORY_BYTES, renderNativeMemory } from "../lib/nativeMemory.js";
 /** Where a `staticEnv` literal secret's real value goes when
@@ -390,6 +390,11 @@ function copyDirectoryThroughBackup(sourceDir, destDir, backup) {
 }
 export function applyMigratePlan(plan, homeDir = homedir(), backup) {
     const canonicalRoot = join(homeDir, ".trellis");
+    if (plan.items.some((item) => item.kind === "skill" && item.action === "create")) {
+        const validation = validateSkillScopeYaml(join(canonicalRoot, "scope.yaml"));
+        if (!validation.ok)
+            throw new Error(validation.error);
+    }
     for (const item of plan.items) {
         if (item.action !== "create" && item.action !== "reclassify" && item.action !== "extract-secret")
             continue;
@@ -400,6 +405,11 @@ export function applyMigratePlan(plan, homeDir = homedir(), backup) {
                 copyDirectoryThroughBackup(item.sourceDir, dest, backup);
             else
                 cpSync(item.sourceDir, dest, { recursive: true });
+            // Migration proves applicability to its source agent only. Sharing
+            // with other agents is a separate, explicit compatibility decision.
+            const scope = writeSkillScopeYaml(join(canonicalRoot, "scope.yaml"), item.name, [plan.agent], backup);
+            if (!scope.ok)
+                throw new Error(scope.error);
         }
         else if (item.kind === "instructions" && item.sourceContent !== undefined) {
             mkdirSync(canonicalRoot, { recursive: true });

package/dist/commands/remoteSkill.js

@@ -15,6 +15,7 @@ import { isBuiltinSkillName } from "../lib/builtinSkills.js";
 import { emptyRemoteSkillLock, readRemoteSkillLock, writeRemoteSkillLock } from "../lib/remoteSkillLock.js";
 import { fetchRemoteRepository, normalizeGitHubRepository } from "../lib/remoteSkillSource.js";
 import { collectSyncReport, printReport as printSyncReport } from "./sync.js";
+import { requestSkillScope } from "../lib/skillScope.js";
 function safeSkillName(name) {
     return typeof name === "string" && /^[A-Za-z0-9][A-Za-z0-9_.-]*$/.test(name) && name !== "." && name !== "..";
 }
@@ -41,7 +42,9 @@ function scopeForRequest(homeDir, agents) {
         return { error: error instanceof Error ? error.message : String(error) };
     }
     if (!agents || agents.length === 0)
-        return { scope: undefined };
+        return { error: 'choose applicable agents with --agent <ids> or --agent "*"' };
+    if (agents.length === 1 && agents[0] === "none")
+        return { scope: [] };
     const values = agents.flatMap((value) => value.split(",").map((id) => id.trim()).filter(Boolean));
     if (values.length === 0)
         return { error: "--agent needs at least one Agent id" };
@@ -164,6 +167,20 @@ export async function runRemoteSkillAdd(sourceInput, name, opts = {}) {
             console.error(plan.detail);
         return { exitCode: 1 };
     }
+    if (!opts.agents) {
+        const home = opts.homeDir ?? homedir();
+        const managed = existsSync(join(home, ".trellis")) ? loadCanonicalSource(home).managedAgents : [];
+        const selected = await requestSkillScope({}, managed, !opts.json);
+        if ("error" in selected) {
+            const detail = `${selected.error}; remote import uses --agent <ids>, --agent "*" or --agent none`;
+            if (opts.json)
+                console.log(JSON.stringify({ action: "invalid-options", detail }));
+            else
+                console.error(detail);
+            return { exitCode: 1 };
+        }
+        opts = { ...opts, agents: selected.scope.length ? selected.scope : ["none"] };
+    }
     let fetched;
     try {
         fetched = fetchRemoteRepository(repository, { branch: opts.branch });

package/dist/commands/secretsAudit.js

@@ -29,7 +29,7 @@ import { KiroAdapter } from "../adapters/kiro.js";
 import { ZcodeAdapter } from "../adapters/zcode.js";
 import { declaredEnvNames, extractJsonEnvVarNames, extractTomlEnvVarNames, extractZcodeEnvVarNames } from "../lib/envVarNames.js";
 import { resolveZcodeProfile } from "../probes/zcode.js";
-import { parseEnvEntry, resolveSecretEnv } from "../lib/secretEnv.js";
+import { parseEnvEntry, resolveSecretEntries, SecretReferenceError } from "../lib/secretEnv.js";
 /** Only agents in `managedAgents` — a present-but-unmanaged agent's config
  * file is never even read (trellis-managed-agents), same restriction as
  * `sync`/`mcp sync`. pi has no static, generated MCP config file to audit
@@ -76,16 +76,29 @@ async function findMissingEnvValues(servers, policy) {
     if (resolvable.length === 0)
         return findings;
     // Findings name the DELIVERED name (the KEY segment for a reference).
-    const resolved = await resolveSecretEnv(resolvable, policy);
+    const pending = [...resolvable];
+    let resolved = {};
+    // One broken profile must be a finding, not abort the entire audit.
+    while (pending.length) {
+        try {
+            resolved = await resolveSecretEntries(pending, policy);
+            break;
+        }
+        catch (error) {
+            if (!(error instanceof SecretReferenceError))
+                throw error;
+            pending.splice(pending.indexOf(error.entry), 1);
+        }
+    }
     for (const entry of resolvable) {
         const p = parseEnvEntry(entry);
         const delivered = p.kind === "invalid" ? entry : p.delivered;
-        if (!resolved[delivered]) {
+        if (!resolved[entry]) {
             findings.push({
                 agent: "environment",
                 file: p.kind === "ref" ? `the mxenv composition (profile "${p.profile}")` : (policy.envFile ?? "process environment"),
                 kind: "missing-env-value",
-                detail: `"${delivered}" is declared by a canonical MCP server's env but has no resolvable value`,
+                detail: `"${delivered}" is declared by a canonical MCP server's env or headers but has no resolvable value`,
             });
         }
     }

package/dist/commands/skill.d.ts

@@ -31,12 +31,18 @@ export declare function runSkillUpdateBuiltin(opts?: {
 export interface SkillListEntry {
     name: string;
     scope: readonly AgentId[];
+    registered?: boolean;
+    delivery?: {
+        state: "linked" | "missing" | "conflict" | "runtime";
+        path?: string;
+    };
     remote?: Pick<RemoteSkillLockEntry, "source" | "requestedRef" | "commit" | "subdirectory" | "digest">;
 }
-export declare function collectSkillList(homeDir?: string): SkillListEntry[];
+export declare function collectSkillList(homeDir?: string, agent?: AgentId): SkillListEntry[];
 export declare function runSkillList(opts?: {
     homeDir?: string;
     json?: boolean;
+    agent?: string;
 }): {
     exitCode: number;
 };
@@ -46,6 +52,7 @@ export interface SkillAddPlan {
     action: SkillAddAction;
     detail: string;
     sourceDir?: string;
+    scope?: AgentId[];
 }
 export declare function collectSkillAddPlan(name: string, fromPath: string, homeDir?: string): SkillAddPlan;
 export declare function applySkillAddPlan(plan: SkillAddPlan, homeDir?: string, backup?: BackupSession): void;
@@ -84,6 +91,7 @@ export declare function runSkillAdd(name: string, fromPath: string, opts?: {
     dryRun?: boolean;
     workspace?: boolean;
     workspaceDir?: string;
+    selection?: ScopeSelectorRaw;
 }): Promise<{
     exitCode: number;
 }>;
@@ -117,13 +125,10 @@ export interface SkillScopePlan {
     name: string;
     action: SkillScopeAction;
     detail: string;
-    /** What will be recorded in `scope.yaml`; `undefined` clears the explicit
-     * scope so the skill reaches every managed agent. Set when the selection was
-     * valid, whatever the action. */
+    /** Applicable agents recorded in scope.yaml. Even --all is a fixed list. */
     scope?: AgentId[];
     mode?: "all" | "none" | "explicit";
-    /** True when a full selection was dropped instead of recorded
-     * (trellis-scope-editing-and-auth-status design.md D3). */
+    /** Retained for API compatibility; skill lists are never normalized away. */
     normalizedFromFull?: boolean;
     /** The agents that will actually receive the skill afterwards. */
     effective?: readonly AgentId[];

package/dist/commands/skill.js

@@ -14,14 +14,17 @@ import { dirname } from "node:path";
 import { fileURLToPath } from "node:url";
 import { decideDirImport } from "../lib/dirEquals.js";
 import { findSkillFile } from "../lib/skillFile.js";
-import { loadCanonicalSource, writeSkillScopeYaml } from "../core/canonical.js";
+import { loadCanonicalSource, validateSkillScopeYaml, writeSkillScopeYaml } from "../core/canonical.js";
 import { resolveScope } from "../core/types.js";
 import { isBuiltinSkillName } from "../lib/builtinSkills.js";
 import { openBackupSession } from "../lib/backup.js";
 import { collectSyncReport, printReport as printSyncReport } from "./sync.js";
 import { remoteSkillProvenance } from "./remoteSkill.js";
-import { describeScope, resolveScopeSelection, sameScope } from "../lib/scopeSelection.js";
+import { sameScope } from "../lib/scopeSelection.js";
 import { findWorkspaceRoot } from "../lib/workspace.js";
+import { readSkillScopes, requestSkillScope, selectSkillScope } from "../lib/skillScope.js";
+import { isSymlinkTo } from "../lib/fsIdentity.js";
+import { usesNativeCapabilityDelivery, ALL_AGENTS } from "../core/types.js";
 function builtinSkillTemplate() {
     const here = dirname(fileURLToPath(import.meta.url));
     return readFileSync(join(here, "..", "..", "schema", "builtin-skills", "trellis-runtime", "SKILL.md"), "utf8");
@@ -58,17 +61,34 @@ export function runSkillUpdateBuiltin(opts = {}) {
         console.log(`${opts.dryRun ? "[dry run] " : ""}skill update-builtin\n  [${plan.action}] ${plan.detail}`);
     return { exitCode: 0 };
 }
-export function collectSkillList(homeDir = homedir()) {
+export function collectSkillList(homeDir = homedir(), agent) {
     const canonical = loadCanonicalSource(homeDir);
     const provenance = remoteSkillProvenance(homeDir);
-    return canonical.skills.filter((skill) => !isBuiltinSkillName(skill.name)).map((skill) => ({
+    const registry = readSkillScopes(join(homeDir, ".trellis", "scope.yaml"));
+    const roots = {
+        "claude-code": join(homeDir, ".claude", "skills"), codex: join(homeDir, ".agents", "skills"),
+        kiro: join(homeDir, ".kiro", "skills"), pi: join(homeDir, ".pi", "agent", "skills"),
+        "kimi-code": join(homeDir, ".kimi-code", "skills"), zcode: "",
+    };
+    return canonical.skills.filter((skill) => agent ? resolveScope(skill.scope, canonical.managedAgents).includes(agent) : !isBuiltinSkillName(skill.name)).map((skill) => ({
         name: skill.name,
         scope: resolveScope(skill.scope, canonical.managedAgents),
+        ...(agent ? {
+            registered: Object.hasOwn(registry, skill.name) || isBuiltinSkillName(skill.name),
+            delivery: !usesNativeCapabilityDelivery(agent, canonical.mcp) || agent === "zcode"
+                ? { state: "runtime" }
+                : { state: isSymlinkTo(join(roots[agent], skill.name), skill.dir) ? "linked"
+                        : existsSync(join(roots[agent], skill.name)) ? "conflict" : "missing", path: join(roots[agent], skill.name) },
+        } : {}),
         ...(provenance[skill.name] ? { remote: provenance[skill.name] } : {}),
     }));
 }
 export function runSkillList(opts = {}) {
-    const entries = collectSkillList(opts.homeDir ?? homedir());
+    if (opts.agent !== undefined && !ALL_AGENTS.includes(opts.agent)) {
+        console.error(`unknown agent: ${opts.agent}; choose ${ALL_AGENTS.join(", ")}`);
+        return { exitCode: 1 };
+    }
+    const entries = collectSkillList(opts.homeDir ?? homedir(), opts.agent);
     if (opts.json) {
         console.log(JSON.stringify(entries, null, 2));
     }
@@ -76,9 +96,9 @@ export function runSkillList(opts = {}) {
         console.log("No skills in canonical source yet.");
     }
     else {
-        for (const { name, scope, remote } of entries) {
+        for (const { name, scope, remote, delivery } of entries) {
             const provenance = remote ? ` — remote: ${remote.source}@${remote.commit.slice(0, 12)}` : "";
-            console.log(`${name} — ${scope.length > 0 ? scope.join(", ") : "(no managed agent reaches it)"}${provenance}`);
+            console.log(`${name} — ${scope.length > 0 ? scope.join(", ") : "(paused: no applicable managed agent)"}${delivery ? ` [${delivery.state}]` : ""}${provenance}`);
         }
     }
     return { exitCode: 0 };
@@ -105,15 +125,26 @@ export function collectSkillAddPlan(name, fromPath, homeDir = homedir()) {
     }
 }
 export function applySkillAddPlan(plan, homeDir = homedir(), backup) {
-    if (plan.action !== "create" || !plan.sourceDir)
+    if (plan.action !== "create" && !(plan.action === "already-present" && plan.scope !== undefined))
         return;
-    const dest = join(homeDir, ".trellis", "skills", plan.name);
-    if (backup) {
-        backup.createDirFromSource(dest, plan.sourceDir);
+    if (plan.action === "create" && !plan.sourceDir)
         return;
+    const scopePath = join(homeDir, ".trellis", "scope.yaml");
+    const validation = validateSkillScopeYaml(scopePath);
+    if (!validation.ok)
+        throw new Error(validation.error);
+    const dest = join(homeDir, ".trellis", "skills", plan.name);
+    if (plan.action === "create") {
+        if (backup)
+            backup.createDirFromSource(dest, plan.sourceDir);
+        else {
+            mkdirSync(dest, { recursive: true });
+            cpSync(plan.sourceDir, dest, { recursive: true });
+        }
     }
-    mkdirSync(dest, { recursive: true });
-    cpSync(plan.sourceDir, dest, { recursive: true });
+    const written = writeSkillScopeYaml(scopePath, plan.name, plan.scope ?? [], backup);
+    if (!written.ok)
+        throw new Error(written.error);
 }
 /** The workspace twin of `collectSkillAddPlan` (trellis-workspace-scope
  * task 3.4): same source validation, destination is `.agents/skills/`
@@ -137,29 +168,40 @@ export function collectSkillAddWorkspacePlan(name, fromPath, workspaceRoot) {
     }
 }
 export function applySkillAddWorkspacePlan(plan, workspaceRoot, backup) {
-    if (plan.action !== "create" || !plan.sourceDir)
+    if (plan.action !== "create" && !(plan.action === "already-present" && plan.scope !== undefined))
         return;
-    const dest = join(workspaceRoot, ".agents", "skills", plan.name);
-    if (backup) {
-        backup.createDirFromSource(dest, plan.sourceDir);
+    if (plan.action === "create" && !plan.sourceDir)
         return;
+    const scopePath = join(workspaceRoot, ".agents", "scope.yaml");
+    const validation = validateSkillScopeYaml(scopePath);
+    if (!validation.ok)
+        throw new Error(validation.error);
+    const dest = join(workspaceRoot, ".agents", "skills", plan.name);
+    if (plan.action === "create") {
+        if (backup)
+            backup.createDirFromSource(dest, plan.sourceDir);
+        else {
+            mkdirSync(dest, { recursive: true });
+            cpSync(plan.sourceDir, dest, { recursive: true });
+        }
     }
-    mkdirSync(dest, { recursive: true });
-    cpSync(plan.sourceDir, dest, { recursive: true });
+    const written = writeSkillScopeYaml(scopePath, plan.name, plan.scope ?? [], backup);
+    if (!written.ok)
+        throw new Error(written.error);
 }
 /** Same own-backup-session + cascade-sync posture as
  * `applySkillAddWithSync`, scoped to the workspace layer. */
 export async function applySkillAddWorkspaceWithSync(plan, workspaceRoot, opts = {}) {
     const homeDir = opts.homeDir ?? homedir();
-    const ownSession = !opts.dryRun && !opts.backupSession && plan.action === "create" ? openBackupSession(homeDir, "skill-add") : undefined;
+    const ownSession = !opts.dryRun && !opts.backupSession && (plan.action === "create" || plan.action === "already-present" && plan.scope !== undefined) ? openBackupSession(homeDir, "skill-add") : undefined;
     const session = opts.backupSession ?? ownSession;
-    if (!opts.dryRun && plan.action === "create") {
+    if (!opts.dryRun && (plan.action === "create" || plan.action === "already-present")) {
         applySkillAddWorkspacePlan(plan, workspaceRoot, session);
     }
     ownSession?.finalize();
     const failed = plan.action === "conflict" || plan.action === "invalid-source";
     let syncReport;
-    if (!failed && plan.action === "create" && existsSync(join(homeDir, ".trellis"))) {
+    if (!failed && (plan.action === "create" || plan.scope !== undefined) && existsSync(join(homeDir, ".trellis"))) {
         syncReport = await collectSyncReport({ target: "skills", homeDir, workspaceDir: workspaceRoot, dryRun: opts.dryRun });
     }
     return { plan, ...(syncReport ? { sync: syncReport } : {}) };
@@ -174,21 +216,30 @@ export async function applySkillAddWorkspaceWithSync(plan, workspaceRoot, opts =
  */
 export async function applySkillAddWithSync(plan, opts = {}) {
     const homeDir = opts.homeDir ?? homedir();
-    const ownSession = !opts.dryRun && !opts.backupSession && plan.action === "create" ? openBackupSession(homeDir, "skill-add") : undefined;
+    const ownSession = !opts.dryRun && !opts.backupSession && (plan.action === "create" || plan.action === "already-present" && plan.scope !== undefined) ? openBackupSession(homeDir, "skill-add") : undefined;
     const session = opts.backupSession ?? ownSession;
-    if (!opts.dryRun && plan.action === "create") {
+    if (!opts.dryRun && (plan.action === "create" || plan.action === "already-present")) {
         applySkillAddPlan(plan, homeDir, session);
     }
     ownSession?.finalize();
     const failed = plan.action === "conflict" || plan.action === "invalid-source";
     let syncReport;
-    if (!failed && plan.action === "create" && existsSync(join(homeDir, ".trellis"))) {
+    if (!failed && (plan.action === "create" || plan.scope !== undefined) && existsSync(join(homeDir, ".trellis"))) {
         syncReport = await collectSyncReport({ target: "skills", homeDir, dryRun: opts.dryRun });
     }
     return { plan, ...(syncReport ? { sync: syncReport } : {}) };
 }
 export async function runSkillAdd(name, fromPath, opts = {}) {
     const homeDir = opts.homeDir ?? homedir();
+    const managed = existsSync(join(homeDir, ".trellis")) ? loadCanonicalSource(homeDir).managedAgents : [];
+    const selected = await requestSkillScope(opts.selection ?? {}, managed, !opts.json);
+    if ("error" in selected) {
+        if (opts.json)
+            console.log(JSON.stringify({ name, action: "invalid-source", detail: selected.error }));
+        else
+            console.error(selected.error);
+        return { exitCode: 1 };
+    }
     if (opts.workspace) {
         const workspaceRoot = opts.workspaceDir ?? findWorkspaceRoot(process.cwd());
         if (!workspaceRoot) {
@@ -196,6 +247,7 @@ export async function runSkillAdd(name, fromPath, opts = {}) {
             return { exitCode: 1 };
         }
         const plan = collectSkillAddWorkspacePlan(name, fromPath, workspaceRoot);
+        plan.scope = selected.scope;
         const { sync: syncReport } = await applySkillAddWorkspaceWithSync(plan, workspaceRoot, { homeDir, dryRun: opts.dryRun });
         const failed = plan.action === "conflict" || plan.action === "invalid-source";
         if (opts.json) {
@@ -211,6 +263,7 @@ export async function runSkillAdd(name, fromPath, opts = {}) {
         return { exitCode: failed || syncConflict ? 1 : 0 };
     }
     const plan = collectSkillAddPlan(name, fromPath, homeDir);
+    plan.scope = selected.scope;
     const { sync: syncReport } = await applySkillAddWithSync(plan, { homeDir, dryRun: opts.dryRun });
     const failed = plan.action === "conflict" || plan.action === "invalid-source";
     if (opts.json) {
@@ -289,9 +342,10 @@ export function collectSkillScopePlan(name, raw, homeDir = homedir()) {
         return { name, action: "invalid-input", detail: `"${name}" is a Trellis package-owned Skill — its scope is not editable` };
     }
     const canonical = loadCanonicalSource(homeDir);
-    const selection = resolveScopeSelection(raw, canonical.managedAgents);
-    if (!selection.ok)
-        return { name, action: "invalid-input", detail: selection.detail };
+    const chosen = selectSkillScope(raw, canonical.managedAgents);
+    if ("error" in chosen)
+        return { name, action: "invalid-input", detail: chosen.error };
+    const selection = { scope: chosen.scope, mode: raw.all ? "all" : raw.none ? "none" : "explicit", normalizedFromFull: false };
     const skill = canonical.skills.find((candidate) => candidate.name === name);
     if (!skill)
         return { name, action: "not-found", detail: `no canonical skill named "${name}"` };
@@ -302,12 +356,11 @@ export function collectSkillScopePlan(name, raw, homeDir = homedir()) {
         normalizedFromFull: selection.normalizedFromFull,
         effective: resolveScope(selection.scope, canonical.managedAgents),
     };
-    const summary = describeScope(selection.scope, canonical.managedAgents);
-    const normalized = selection.normalizedFromFull ? " (every managed agent selected — recorded as the default, so a newly managed agent is included)" : "";
-    if (sameScope(skill.scope, selection.scope)) {
+    const summary = selection.scope.length ? selection.scope.join(", ") : "no agent (paused)";
+    if (sameScope(skill.scope, selection.scope) && Object.hasOwn(readSkillScopes(join(homeDir, ".trellis", "scope.yaml")), name)) {
         return { ...base, action: "already-set", detail: `scope is already ${summary}` };
     }
-    return { ...base, action: "updated", detail: `set scope to ${summary}${normalized}` };
+    return { ...base, action: "updated", detail: `set scope to ${summary}` };
 }
 /** Write inside a backup session so `trellis rollback` covers it, then the
  * same skills sync `add` / `remove` run — narrowing is converged by

package/dist/commands/sync.d.ts

@@ -55,6 +55,7 @@ export interface AgentSyncReport {
 }
 export interface SyncReport {
     reports: AgentSyncReport[];
+    diagnostics?: string[];
     /** Workspace root when a `.agents/` layer participated in this run. */
     workspaceRoot?: string;
 }

package/dist/commands/sync.js

@@ -83,7 +83,7 @@ export async function collectSyncReport(opts = {}) {
         reports.push({ agent: adapter.id, present: true, items: allItems, ...(warnings.length > 0 ? { warnings } : {}) });
     }
     ownSession?.finalize();
-    return { reports, ...(canonical.workspace ? { workspaceRoot: canonical.workspace.root } : {}) };
+    return { reports, ...(canonical.diagnostics.length ? { diagnostics: canonical.diagnostics } : {}), ...(canonical.workspace ? { workspaceRoot: canonical.workspace.root } : {}) };
 }
 export async function runSync(opts = {}) {
     let report;
@@ -118,6 +118,8 @@ export function printReport(report, dryRun, check = false) {
         console.log("[dry run]");
     if (check)
         console.log("[check]");
+    for (const diagnostic of report.diagnostics ?? [])
+        console.log(`  ${diagnostic}`);
     if (report.workspaceRoot) {
         console.log(`Workspace layer: ${report.workspaceRoot} (.agents/)`);
     }

package/dist/core/canonical.d.ts

@@ -27,8 +27,7 @@ export type ScopeYamlWriteResult = {
 export declare function validateSkillScopeYaml(path: string): ScopeYamlWriteResult;
 /**
  * Sets one Skill's canonical scope without rebuilding unrelated hand-authored
- * scope entries.  `undefined` removes this Skill's explicit entry and
- * therefore restores the normal all-managed default.
+ * scope entries. `undefined` removes registration, pausing distribution.
  */
 export declare function writeSkillScopeYaml(path: string, name: string, scope: Scope, backup?: BackupSession): ScopeYamlWriteResult;
 export declare function upsertServerYaml(path: string, name: string, def: McpServerDef, backup?: BackupSession): ServersYamlWriteResult;